Authentication

CCP authenticates via email one-time passwords (OTP). On macOS, the session is stored in an owner-only (0600) file at ~/.cluster/ccp-session.json; on Linux and Windows it's stored in the OS keyring. See Session storage to change this.

Login

ccp auth login
# Email: you@example.com
# Sending code to you@example.com...
# Check your email for a login code.
# Code: 123456
# ◼ You are now logged in!

You can also pass your email directly:

ccp auth login --email you@example.com

Scripted Login

For non-interactive use (CI, dev VMs, agents), pass both --email and --code. --code skips the OTP send step and assumes a code has already been issued for that address:

ccp auth login --email you@example.com --code 123456

In a long-lived headless context, prefer exporting an existing token via CCP_SESSION_TOKEN instead — see Headless Mode.

Logout

ccp auth logout

Session storage

Where CCP keeps your session depends on the platform:

• macOS — a 0600, owner-only file at ~/.cluster/ccp-session.json (default). macOS binds the Keychain's access ACL to the exact signed binary that wrote the item, so a rebuilt or unsigned ccp is treated as a new app and prompts for your login password on every read and write. The file avoids that friction. The tradeoff is a plaintext token at rest, protected by file permissions rather than the encrypted Keychain.
• Linux / Windows — the OS keyring (secret service / Credential Manager), falling back to the same 0600 file when no keyring is available.

Override the default with the CCP_AUTH_STORE environment variable:

If you used CCP on macOS before the file became the default, your session lives only in the Keychain. After upgrading, run ccp auth login once to populate the file (a promptless email OTP) — or set CCP_AUTH_STORE=keychain to keep reading from the Keychain.

Access Tokens

Export your access token for use in scripts or API calls:

# Print as export statement (use with eval)
eval $(ccp auth export-access-token)

# Print raw token to stdout
ccp auth print-access-token

Shell Wrapper

For convenience, add the shell wrapper to auto-export tokens:

# Print the wrapper function
ccp auth shell-setup

# Add to your ~/.zshrc:
ccp() {
  case "$1:$2" in
    auth:export-access-token)
      eval $(command ccp "$@")
      ;;
    *)
      command ccp "$@"
      ;;
  esac
}

Sync Your Session Into a Dev VM

ccp auth sync gives the ccp running inside a dev VM your session, so an agent in the VM can run ccp deploy (and other authenticated commands) as you:

ccp auth sync --vm <vm_id>      # the in-VM ccp now acts as you
ccp auth desync --vm <vm_id>    # remove it

It snapshots your current access token into the VM as a hidden CCP_SESSION_TOKEN variable (the in-VM ccp reads it automatically; it is never shown by ccp env list).

Note: the synced token is your current access token (about 1 hour) and is not refreshed inside the VM — refreshing it would rotate your own login session. Re-run ccp auth sync when it expires. (A scoped, longer-lived successor is planned.)

Auth Subcommands