CLI reference

Run keygrant with no arguments for a summary. Commands marked cloud need the cloud extra (uv tool install 'keygrant[cloud]') and an account.

Secrets

keygrant set NAME [--desc TEXT]

Store a secret. The value is read from stdin, never from an argument, and surrounding whitespace is trimmed.

echo "sk-..." | keygrant set STRIPE_KEY --desc "stripe, test mode"

Setting an existing name replaces the value and the description: pass --desc again to keep one. The use count resets. If the secret is synced, the change stays local until you keygrant push it.

keygrant list

List names, use counts and descriptions. Never prints values.

STRIPE_KEY        used 2x       stripe, test mode
UV_PUBLISH_TOKEN  never used    PyPI upload token

keygrant rm NAME

Delete a secret from this machine. A synced copy stays in the cloud and on other devices; use keygrant push --delete NAME to remove it everywhere.

keygrant exec [--redact] NAME[,NAME...] -- COMMAND [ARGS...]

Run a command with the named secrets set as environment variables. Asks for approval on every run.

• The command runs directly, not through a shell. To use $NAME, wrap it: -- sh -c '...' or, on Windows, -- cmd /c "...".
• --redact captures the output and scrubs secret values from it. Without it, output goes straight to your terminal.
• Exit codes: 2 usage error, 1 unknown secret or other error, 3 denied, otherwise the command’s own exit code.

keygrant exec --redact STRIPE_KEY -- sh -c 'curl -s https://api.stripe.com/v1/charges -u "$STRIPE_KEY:"'
keygrant exec AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY -- aws s3 ls

keygrant revoke NAME | --all

Void existing grants for one secret, or for all of them, in every running session. See Approvals and grants.

Setup

keygrant init

Wire the current folder up for Claude Code: add the server to .mcp.json and append guidance to CLAUDE.md. Safe to run more than once.

keygrant mcp

Run the MCP server on stdio. Same as the keygrant-mcp command.

Cloud

keygrant cloud init · cloud

Create an account on this device: choose a password, then write down the Emergency Kit it prints.

keygrant cloud status · cloud

Show the account, this device’s fingerprint, the number of devices and the sync state. keygrant cloud with no subcommand does the same.

keygrant push [--delete] NAME... · cloud

Upload local secrets, or with --delete remove them from the account and every device. Refused if another device changed the same secret since your last sync: run keygrant sync first.

keygrant sync · cloud

Pull changes now. list and exec also pull on their own, at most once a minute.

keygrant devices · cloud

List devices: fingerprint, kind, name and ID.

keygrant devices add · cloud

Show a pairing code so a new machine (keygrant pair) or a browser approver (app.keygrant.app) can join. Valid for 10 minutes.

keygrant pair · cloud

Join this machine to an account with a pairing code from devices add.

keygrant devices remove ID · cloud

Remove a device; an ID prefix is enough. Removing a machine rotates the vault key.

keygrant devices trust · cloud

Trust browser approvers that another device paired, after checking their fingerprints.

keygrant recover · cloud

Join this machine with the Emergency Kit and password alone, no other device needed. See Recovery.

keygrant cloud kit · cloud

Print the Emergency Kit again.

keygrant cloud enable-recovery · cloud

Turn on recovery for an account created before 0.1.4. Run once, from any machine in the account.

keygrant cloud audit [off | metadata | full] · cloud

Show or set what this device uploads about secret use. See Audit trail.

keygrant cloud delete · cloud

Delete the account, its ciphertext and every device. Local secrets stay as local-only entries.