Docs
A 60-second quickstart: an empty Vault, one Secret, a Manifest declaring it, the Claude Code integration, and a command that uses the Secret without ever printing it.
Quickstart
# 1. Create a Vault. CPASS_KEY (CI) or the platform's unlock source
# (macOS Keychain, or a passphrase on Linux) supplies the encryption
# key.
cpass init
# 2. Store a Secret under a Handle. The value is typed at a hidden
# prompt — cpass add refuses without a terminal, so an Agent can
# never pipe a value it already knows straight into the Vault.
cpass add stripe/live
# 3. Declare the Handles this project needs. No values live in this
# file; it's meant to be committed.
cpass manifest init
cpass manifest add stripe/live
# 4. Wire up Claude Code: an Intercept hook, a Command Policy hook, and
# a skill teaching an Agent to use cpass. Idempotent — safe to re-run.
cpass integrate claude
# 5. Run the real command. cpass run reads the Manifest, injects
# stripe/live as $STRIPE_LIVE into this one child process, and
# nothing else — swap the sh -c '...' below for your actual
# deploy/curl/psql/gcloud command; the Secret reaches it the same
# way, by reading its own environment.
cpass run -- sh -c '[ -n "$STRIPE_LIVE" ] && echo "deploy: authenticated"'The value of stripe/live is never typed into a command line, never appears in this terminal's scrollback, and — because Claude Code's plugin is installed — never gets past a paste into the Agent's prompt either.
Vocabulary
- Secret
- A sensitive value (API key, password, token, private key) that must never appear in an agent's context.
- Handle
- An opaque name that refers to a Secret without revealing its value. The only form in which a Secret is visible to an Agent. For example, stripe/live.
- Agent
- An AI coding session (Claude Code, Codex, or similar) whose context must be kept free of Secret values.
Broker- The local component that resolves a Handle into a Secret value at the moment a command runs, so the value reaches the destination process but not the Agent.
- Context
- Everything an Agent sees: prompts, tool results, and anything persisted from them (transcripts, logs, history).
- Redaction
- The Broker's replacement of a Secret value, in any recognisable encoding, with a marker in the output of a command before that output can reach an Agent.
- Command Policy
- The rules deciding whether a command an Agent wants to run may proceed: refusing commands that would reveal a Secret rather than use it, read Secrets from disk, or carry a raw Secret value. Applied both before a command runs and when the Broker injects.
- Vault
- The encrypted local store, owned by ClaudePass, where Secrets live. The only source the Broker reads from.
- Binding
- How a Secret lands in a command's process: either as an environment variable holding the value, or as a temporary file whose path is placed in an environment variable and which is destroyed when the command exits. A Handle carries a default Binding; a command may override it.
Manifest- A committed, per-project declaration of which Handles the project needs and their Bindings. Contains no Secret values and is safe to share. For example,
.claudepass.toml. - Global Manifest
- A per-machine declaration, in the same format as a Manifest, of which Handles every onboarded project should receive without naming them itself. Reaches a directory only through that directory's own Manifest, and never crosses into a nested repository. Contains no Secret values. For example,
global.toml. - Capture
- Storing the output of a command directly into the Vault as a new Secret, so that a value born in a tool result never reaches an Agent.
- Intercept
- Catching a Secret value in a human's prompt before it reaches an Agent, moving it into the Vault, and erasing the prompt so the Agent only ever sees a Handle.
Exposed- The state of a Secret whose value has entered an Agent's Context at least once. An Exposed Secret is treated as compromised and due for rotation.