|
| 1 | +--- |
| 2 | +title: "AI Agent Integration" |
| 3 | +weight: 6 |
| 4 | +toc: true |
| 5 | +--- |
| 6 | + |
| 7 | +pass-cli is built to be driven safely by **AI coding agents** (Claude Code, |
| 8 | +Cursor, Codex, Continue, and similar) — not just humans at a keyboard. An agent |
| 9 | +can use your real credentials to run real commands **without the secret ever |
| 10 | +landing in the chat transcript, a log, CI output, or a file the agent's harness |
| 11 | +watches**. |
| 12 | + |
| 13 | +This is the differentiator: most ways of handing a secret to an agent — pasting |
| 14 | +it, `echo`-ing it, capturing it into a shell variable — leak it into the |
| 15 | +conversation log the moment they happen. pass-cli exists to move a secret from |
| 16 | +your encrypted vault into the process that needs it through a channel the |
| 17 | +transcript never sees. |
| 18 | + |
| 19 | +## The safety model |
| 20 | + |
| 21 | +> **Never let a secret value reach the transcript, a log, or a watched file.** |
| 22 | +> Once a secret is in the conversation log on disk it is compromised and must be |
| 23 | +> rotated. |
| 24 | +
|
| 25 | +Everything below is a way to satisfy that rule. The default — `exec` — passes |
| 26 | +the secret **only** through a child process's environment, so it never touches |
| 27 | +stdout, the clipboard, or shell history. |
| 28 | + |
| 29 | +## Hand a secret to a command — `exec` |
| 30 | + |
| 31 | +The primary tool. Runs a command with credentials injected as environment |
| 32 | +variables; pass-cli writes nothing of its own to stdout, and the child's exit |
| 33 | +code is propagated unchanged. |
| 34 | + |
| 35 | +```bash |
| 36 | +# Explicit mapping: ENV_NAME=service |
| 37 | +pass-cli exec --set GITHUB_TOKEN=github -- gh repo list |
| 38 | + |
| 39 | +# Multiple credentials at once |
| 40 | +pass-cli exec --set AWS_ACCESS_KEY_ID=aws-id --set AWS_SECRET_ACCESS_KEY=aws-secret -- aws s3 ls |
| 41 | + |
| 42 | +# Convenience form: derive the env name from the service (openai-api -> OPENAI_API) |
| 43 | +pass-cli exec openai-api -- python train.py |
| 44 | +``` |
| 45 | + |
| 46 | +`exec` is read-only: it records no usage and triggers no sync push, so it is safe |
| 47 | +to call on a hot path. |
| 48 | + |
| 49 | +## Composite and derived secrets — `export` and `inject` |
| 50 | + |
| 51 | +- **`export`** prints shell statements to load credentials into the current |
| 52 | + shell (`eval "$(pass-cli export --set GITHUB_TOKEN=github)"`). A weaker |
| 53 | + boundary than `exec` — prefer `exec` when you only need to launch a command. |
| 54 | +- **`inject`** renders a template, replacing `${pass:service/field}` references |
| 55 | + with values — the tool for a config file or a connection string that *embeds* a |
| 56 | + secret: |
| 57 | + |
| 58 | + ```bash |
| 59 | + echo 'postgres://app:${pass:db/password}@localhost/app' | pass-cli inject |
| 60 | + ``` |
| 61 | + |
| 62 | + References support value filters — `base64`, `base64url`, and `basicauth` |
| 63 | + (`base64("user:pass")` for an HTTP `Authorization: Basic` header) — so an agent |
| 64 | + never has to shell out to `base64` and risk the value on stdout: |
| 65 | + |
| 66 | + ```bash |
| 67 | + echo 'Authorization: Basic ${pass:api | basicauth}' | pass-cli inject |
| 68 | + ``` |
| 69 | + |
| 70 | +## Promptless access — the background agent |
| 71 | + |
| 72 | +For a session where an agent resolves many credentials, the optional background |
| 73 | +agent unlocks the vault once and holds it in memory, so `exec`/`export`/`inject` |
| 74 | +need **no master-password prompt and no key derivation** on each call: |
| 75 | + |
| 76 | +```bash |
| 77 | +pass-cli agent start # unlock once, then background itself |
| 78 | +pass-cli exec --set GITHUB_TOKEN=github -- gh repo list # resolves via the agent, no prompt |
| 79 | +pass-cli agent stop # zero secrets and stop |
| 80 | +``` |
| 81 | + |
| 82 | +It serves resolved field **values only** — the master password and derived key |
| 83 | +never leave the agent process — and auto-locks after inactivity (`--idle`, |
| 84 | +default 15m) and always after `--max-ttl` (default 8h). When no agent is running, |
| 85 | +every command **transparently falls back** to opening the vault directly, so the |
| 86 | +agent is a pure optimization, never a dependency. POSIX only for now; on Windows |
| 87 | +commands fall back to direct-open. See the [Background Agent](../05-operations/agent) |
| 88 | +reference for details. |
| 89 | + |
| 90 | +## Self-describing: `pass-cli skills` |
| 91 | + |
| 92 | +pass-cli ships an **agent usage guide inside the binary**, so an agent can load |
| 93 | +version-matched guidance straight from the CLI — the instructions never drift |
| 94 | +from the installed version: |
| 95 | + |
| 96 | +```bash |
| 97 | +pass-cli skills get core # safe-usage guide: exec/export/inject/agent/list/get + leak traps |
| 98 | +pass-cli skills get core --full # also include the full command reference |
| 99 | +pass-cli skills list # list every skill shipped with this version |
| 100 | +``` |
| 101 | + |
| 102 | +To make an agent discover pass-cli automatically, install a small discovery stub |
| 103 | +into its skills directory: |
| 104 | + |
| 105 | +```bash |
| 106 | +pass-cli skills install # auto-detects ~/.claude/skills or ~/.agents/skills |
| 107 | +``` |
| 108 | + |
| 109 | +The stub is intentionally thin — it points the agent at `pass-cli skills get |
| 110 | +core`, and the real, version-matched guidance stays in the binary. See |
| 111 | +[AI Agent Skills](../05-operations/agent-skills) for the full command. |
| 112 | + |
| 113 | +## Quickstart for agents |
| 114 | + |
| 115 | +An agent working on a user's machine can bootstrap in three commands: |
| 116 | + |
| 117 | +```bash |
| 118 | +pass-cli skills get core # learn the safe-usage rules |
| 119 | +pass-cli list -q # discover available service names (no secrets) |
| 120 | +pass-cli exec --set API_KEY=some-service -- <cmd> # run a command with the secret injected |
| 121 | +``` |
| 122 | + |
| 123 | +## Learn more |
| 124 | + |
| 125 | +- [Command Reference](../03-reference/command-reference) — every command and flag |
| 126 | +- [Background Agent](../05-operations/agent) — the promptless daemon in depth |
| 127 | +- [AI Agent Skills](../05-operations/agent-skills) — the `skills` command |
| 128 | +- [Scripting Guide](scripting-guide) — non-agent automation and output modes |
0 commit comments