Synopsis
Description
Accepts a redeem code produced by capy invite. The same command takes the code capy transport prints when you move your own account to another machine.
Capy reads the expiry packed into the code first, so an expired code fails before you’re asked to sign in. It then authenticates you - silently from a cached session where it can, with a browser sign-in where it can’t - and refreshes that session into the organization the code targets. If you land on a different organization, Capy stops there: you aren’t a member of the invited org, or the invite was revoked.
With a session for the right org, Capy asks the service to strip the outer wrap, then strips the inner wrap locally using the invite token baked into the code. The inner wrap is derived from the org ID plus the invited address, so if the authenticated email doesn’t match the one the inviter targeted, decryption fails cryptographically - not by policy.
capy redeem is disabled in local-only mode - local mode has no organization, team, or server.
What it changes on your machine
Before it decrypts anything, Capy repoints local state at the redeemed org:
- Rewrites
.capy/sync-state in the current directory with the new org and user IDs and an empty sync record.
- Deletes
keep.lock from the current directory when that file belongs to a different org, or can’t be parsed. Run capy redeem from an empty directory or from a project that belongs to the org you’re joining, not from a checkout of another org’s project.
Then, once the service has confirmed your membership, Capy writes the org’s master key to ~/.capy/orgs/{orgId}/users/{userId}/key.enc, double-wrapped for local storage: your local key inside, the service’s KMS wrap outside.
If that key file is already on this machine, Capy skips the unwrap and reports that your keys are configured. The co-decrypt call still ran, so redeeming again doubles as a membership check.
If the service answers that call by reporting your membership as revoked, Capy clears the local state for that org and user - ~/.capy/orgs/{orgId}/users/{userId}/, the org’s cached project keys, and keep.lock in the current directory - and exits. Every other failure, such as a network blip or a tampered code, leaves your keys and per-org state intact so you can retry - though the .capy/sync-state rewrite and any keep.lock removal described above have already happened by that point.
Example
See also
Last modified on August 11, 2026
