Docs

CLI reference

Every command the caddi CLI exposes, with its options and an example. Every command also accepts a global --api-url <url>, or the CADDI_API_URL env var, to point at a non-default API host, plus -v, --version to print the installed CLI version and --no-color to disable colored output.

login

caddi login [--recovery] [--no-browser]

--recovery: paste a vault recovery code to self-approve this device instead of waiting for another device to approve it.
--no-browser: don’t try to open the authorize page in a browser; just print the URL.

Prints a device code and a URL, waits for you to authorize in the browser, then bootstraps this device’s keypair and its relationship to the account’s vault (creating the vault and printing a recovery code, on the very first device; unwrapping the vault key, if this device already holds a wrapped copy; or printing pending-approval instructions otherwise).

caddi login
caddi login --recovery
caddi login --no-browser

logout

Sign out and remove the locally stored session token.

caddi logout

whoami

Print the signed-in user, workspace, and role.

caddi whoami

devices

Manage the devices linked to your vault.

devices list

List devices registered on your account.

caddi devices list

devices approve <id>

Approve a pending device, granting it access to the vault. Prints the fingerprint of the key the vault is about to be wrapped to and requires an explicit confirmation that it matches what the pending device itself printed.

caddi devices approve <id> [-y|--yes]

-y, --yes: skip the fingerprint confirmation prompt (for scripting).

caddi devices approve 3f1e2c4a-...

devices revoke <id>

Revoke a device, removing its access to the vault. Terminal: a revoked device can never be re-approved.

caddi devices revoke 3f1e2c4a-...

connect

Connect a provider account by sealing an API token to your vault. Accepts any catalog provider id, or custom <slug> for a connection outside the catalog.

caddi connect <service> [--token <token>] [--name <name>] [-y|--yes]
caddi connect custom <slug> --name "<display name>" [--token <token>] [-y|--yes]

--token <token>: API token, non-interactive (otherwise you’re prompted, input masked).
--name <name>: display name for a custom connection, required with custom.
-y, --yes: skip the fingerprint confirmation prompt shown when this device has no local vault key (for scripting).

caddi connect github
caddi connect resend --token re_live_...
caddi connect custom my-internal-api --name "My internal API"

OAuth-only catalog providers (Gmail, Google Drive, Google Calendar, Canva) print “coming soon” and exit rather than attempting to seal anything, since there’s no token to paste for them yet.

status

Show connection, device, and vault status: sign-in state, API reachability, this device’s registration, the vault fingerprint, and every connection’s status.

caddi status

mcp

Start the caddi MCP gateway over stdio. This is what coding agents spawn as a subprocess (via caddi install’s registration); it’s not meant to be run by hand. Speaks JSON-RPC over stdin/stdout and doesn’t exit until its stdin closes.

caddi mcp

install

Detect coding agents on this machine (Claude Code, Cursor, Windsurf, Codex CLI) and register the caddi MCP gateway with each one found. Never touches an agent’s other MCP servers or config keys.

caddi install

doctor

Diagnose common setup problems: CLI and Node version, config readability, API reachability, keychain access, sign-in state, this device’s keypair and vault key, and whether the caddi gateway is registered with any coding agent detected on this machine. Each check prints pass, fail, or skip, plus the exact fix command on failure. Secrets are never printed, only their presence or a public fingerprint.

caddi doctor

Exits 0 if every check passed or was skipped, 1 if any check failed. A skip (for example, not signed in yet) is informational and never fails the run on its own.

skills

Manage your skill library.

skills add <source>

Add a skill: a git URL (public, stored by reference) or a local directory (private, end-to-end encrypted).

caddi skills add <source> [--name <name>] [--ref <ref>] [--path <path>]

--name <name>: override the derived skill name.
--ref <ref>: pin a reference skill to a specific commit or ref (default: the remote’s current HEAD, resolved and pinned immediately).
--path <path>: subdirectory within the repo containing the skill (reference skills only).

caddi skills add https://github.com/anthropics/skills
caddi skills add https://github.com/org/skills-monorepo --path skills/foo --name foo
caddi skills add ./my-private-skill

skills list

List the skills in your library.

caddi skills list

skills remove <name>

Remove a skill from your library.

caddi skills remove my-skill

skills sync

Materialize your skill library into ~/.claude/skills/.

caddi skills sync

env pull

Write this project’s caddi.json-allowlisted env vars, resolved from connected providers’ decrypted credentials, to .env.local (created or merged, chmod 600). Only the var names being written are ever printed, never values.

caddi env pull [--project <dir>]

--project <dir>: project directory to operate in (default: the current directory).

caddi env pull
caddi env pull --project ./apps/web

approve [kind]

Record a user-level ack for a caddi.json toggle that widens gateway privileges (get_secret, env). A repo-committed caddi.json alone can never widen what a coding agent can reach; this command, run outside the repo, is what actually flips it on.

caddi approve <get_secret|env> [-y|--yes] [--project <dir>]
caddi approve --list
caddi approve --revoke [hash]

-y, --yes: skip the confirmation prompt (for scripting).
--project <dir>: project directory to operate in (default: the current directory).
--list: list every recorded approval.
--revoke [hash]: revoke an approval (defaults to the current project’s).

caddi approve get_secret
caddi approve env --yes
caddi approve --list
caddi approve --revoke
caddi approve --revoke 3f1e2c4a...

audit

Show recent gateway audit events from ~/.caddi/audit/: service, tool, a hashed project identifier, and outcome. Never argument values.

caddi audit [--tail]

--tail: follow today’s audit file for new events as they happen.

caddi audit
caddi audit --tail

vault rotate

Rotate the vault keypair, re-sealing every connection to a fresh key. Run this after revoking a possibly-compromised device or leaking a recovery code. This device must already hold the vault private key. A new recovery code is generated and printed once; the old one stops working immediately. Every currently-active device keeps working automatically; any device that was already pending or revoked is unaffected.

caddi vault rotate [-y|--yes]

-y, --yes: skip the confirmation prompt (for scripting).

caddi vault rotate
caddi vault rotate --yes

caddi.json: the schema behind allow, env, and get_secret.
Skills: what skills add and skills sync do under the hood.
Security model: the crypto behind login, devices, and vault rotate.