capy invite: Add a Teammate to Your Organization

Synopsis

capy invite <email>
capy invite <email> --role project-admin --project api-backend
capy invite <email> --role member --project api-backend --ttl 24h --json --non-tty

Description

Generates a redeem code that grants <email> access to the current organization. Capy asks which role to grant, offering only the roles your own role can grant: an Owner or Admin can invite a Member, Project Admin, or Admin; a Project Admin can invite a Member or Project Admin. There is exactly one Owner per org, so Owner is never on the list. Member and Project Admin are scoped to projects, so Capy then asks which projects to grant - a checkbox list with the project in your current directory preselected. Capy prints the full capy redeem <code> command for you to pass on, then offers to copy that command: press c to copy, any other key to continue. The recipient runs the command to complete the flow. Inviting an address that already belongs to a member re-issues their invite instead: same role, same projects, fresh code. That’s how you get a teammate onto a new machine. Pass --role to change their role on the way through. capy invite is disabled in local-only mode - local mode has no organization, team, or server.

Flags

Flag	Description
`--role <role>`	`member`, `project-admin`, or `admin`. Skips the role prompt. Capy refuses a role your own role can’t grant.
`--project <id\|name>`	Grant access to a project, by id or name. Repeatable, and accepts a comma-separated list.
`--ttl <duration>`	How long the code stays valid: `30m`, `24h`, `7d`, or a bare number of seconds.
`--expires <iso>`	Absolute expiry as an ISO date, e.g. `2026-06-01T00:00:00Z`. Overrides `--ttl`.
`--json`	Emit machine-readable JSON instead of the human output, and skip the clipboard prompt.
`--non-tty`	Never prompt. Resolve every choice from flags, or fail fast.

Codes last 7 days by default. Set CAPY_INVITE_TTL_SECONDS to change that default for the invites you issue.

Agents and CI

Under --non-tty - or whenever stdin isn’t a TTY - Capy resolves everything from flags instead of prompting:

No --role: falls back to member for a new invitee. On a re-issue, Capy keeps the member’s existing role unless you pass --role.
No --project: keeps the member’s existing projects on a re-issue, otherwise the project in your current directory. If neither applies, Capy exits with code 3 and tells you to pass --project.

--json writes the code and its metadata to stdout and skips both the human output and the clipboard prompt:

{
  "email": "alice@example.com",
  "role": "member",
  "reissued": false,
  "projectIds": ["<project-id>"],
  "redeemCode": "<base64 redeem code>",
  "redeemCommand": "capy redeem <base64 redeem code>",
  "expiresAt": "2026-08-18T09:41:02.517Z",
  "projectAssignmentFailures": []
}

The redeem code

The code is a base64 string that packs a format version, the invite token T, the expiry timestamp, the organization ID, and a double-wrapped copy of the master key. The expiry is bound into the outer wrap, so editing the timestamp in the code makes it fail to unwrap. Deliver it out-of-band (Signal, a password manager share, a QR code, a phone call). Interception alone doesn’t hand over the master key - redeeming needs the service to strip the outer wrap for an authenticated account, and the inner wrap is derived from the org ID plus the invited address, so it only opens for whoever signs in as <email>. Treat the code as a bearer credential for that mailbox anyway. Email and Slack DMs are not acceptable channels. See Inviting users for why.

Example

$ capy invite alice@example.com
✔ Select a role for alice@example.com: Member
✔ Grant Member access to which projects? api-backend

  Invite created for alice@example.com as Member

  Send them this command:

    capy redeem AgR5xk...9pQw

  The code contains a double-wrapped copy of the org key.
  It cannot be decrypted without service co-decryption + authentication.
  Expires 2026-08-18T09:41:02.517Z.

  Press c to copy, or any other key to continue...

Getting started

Using Capy

Deploying

Organizations

Branches

Team

CLI reference

Under the hood

Comparisons

capy invite: Add a Teammate to Your Organization

Synopsis

Description

Flags

Agents and CI

The redeem code

Example

See also

​Synopsis

​Description

​Flags

​Agents and CI

​The redeem code

​Example

​See also

Synopsis

Description

Flags

Agents and CI

The redeem code

Example

See also