pass-cli

name

pass-cli

description

How an AI agent should safely drive the pass-cli password manager (this repo's binary). Use whenever a task needs a stored secret/credential to run a command, when reading from or listing a pass-cli vault, or when you're about to capture a secret with `get`/command substitution — there is a safer path. Covers `exec` (hand a secret to a child process without it ever touching stdout), the safe-by-default `list`, and the leak traps to avoid.

Using pass-cli safely as an agent

pass-cli is a local, offline-first password manager. Its vault is a single AES-GCM-encrypted file. As an agent you will mostly need it to give a stored secret to a command you're about to run — and the cardinal rule is:

Never let a secret value land in the transcript, a log, CI output, or any file a tool watches. Once a secret is in the conversation log on disk it is compromised and must be rotated.

The whole point of the commands below is to move a secret from the vault into a child process without it passing through stdout, the clipboard, your shell history, or a set -x trace.

The decision: how do you need the secret?

You need to…	Use	Why
Run a command that reads the secret from its environment	pass-cli exec	Secret goes straight into the child's env; never on stdout
Know which services exist	pass-cli list -q	Bare service names; usernames hidden by default
Capture a value into a variable (last resort)	pass-cli get … --quiet --no-clipboard	Only if exec truly can't express it; see the trap below

Default to exec. Reach for get only when nothing else works.

pass-cli exec — the safe way to hand a secret to a command

Runs a child command with credentials injected as environment variables. The value is passed only through the child's environment — never a file, the clipboard, or shell history. pass-cli writes nothing of its own to stdout, and the child's exit code is propagated unchanged.

# Explicit mapping (repeatable): --set ENV_NAME=service
pass-cli exec --set GITHUB_TOKEN=github -- gh repo list

# Multiple credentials at once
pass-cli exec --set AWS_ACCESS_KEY_ID=aws-id --set AWS_SECRET_ACCESS_KEY=aws-secret -- aws s3 ls

# Pick a non-password field for ALL mappings with -f/--field
pass-cli exec --set DB_USER=postgres --field username -- ./run-migration.sh

# Per-mapping field with service:field (overrides -f for that one entry)
pass-cli exec --set DB_USER=postgres:username --set DB_PASS=postgres -- ./run-migration.sh

# Convenience form: derive ENV name from the service (openai-api -> OPENAI_API)
pass-cli exec openai-api -- python train.py

Key facts:

• -- separates pass-cli's flags from the child command. Everything after -- is the child's argv. Omitting it is an error ("no command to run").
• -f/--field (default password) selects the field for all --set mappings; valid fields: username, password, category, url, notes, service.
• service:field in a --set overrides -f for that single mapping.
• Exit code is propagated — pass-cli exec … -- sh -c 'exit 7' exits 7. Safe to use in &&/|| chains and CI gates.
• exec is read-only: it does NOT record field-access usage and does NOT trigger a sync push, so calling it in a hot loop won't mutate the vault or hit the network on every run.
• Honest limit: the value lives in the child's environment — readable via /proc/<pid>/environ by the same user and inherited by descendants. This is the same model as op run / aws-vault exec: far safer than files, clipboards, or history, but it is not process isolation.

pass-cli list — listing is the safe step

pass-cli list            # default table: NO username column (usernames can be sensitive)
pass-cli list -q         # bare service names, one per line — ideal for agents/scripts
pass-cli list --show-usernames   # opt the username column back in (only if you need it)
pass-cli list --format json      # full metadata incl. usernames — explicit, structured opt-in

Usernames are hidden by default because that field often holds sensitive values (card/account/routing numbers stored as an entry's "username"). Use pass-cli list -q to discover service names without dumping anything sensitive.

pass-cli get — last resort, and the trap

pass-cli get github --quiet --no-clipboard --field password

--quiet prints only the field value to stdout; --no-clipboard skips the clipboard. But this still puts the secret on stdout — and the trap is what you do with it next:

# ❌ NEVER — the value is now in the transcript / log
echo "$(pass-cli get github --quiet --no-clipboard)"
TOKEN=$(pass-cli get github --quiet --no-clipboard); curl -H "Authorization: $TOKEN" ...
#   ^ if any layer runs `set -x`, or a file-watcher captures the command, the token leaks

# ✅ Prefer exec — the value never becomes a shell variable or a transcript line
pass-cli exec --set TOKEN=github -- curl -H 'Authorization: Bearer '"$TOKEN" ...
#   (the child reads $TOKEN from its own env; pass-cli printed nothing)

If you genuinely must capture into a variable (a tool with no env-var path), pipe it directly into the consumer in the same command, never echo it, and never enable shell tracing in that shell.

Leak-trap checklist (before you run anything)

• Am I about to echo/print a secret, or interpolate it into a logged command? → use exec.
• Is set -x / xtrace active in this shell? → a get/substitution will dump the value. Disable it or use exec.
• Am I writing the secret into a .env* or any file a tool watches? → the harness echoes file changes; don't.
• Do I just need to see what's stored? → pass-cli list -q (names only).

If a secret value ever does reach the transcript: tell the user immediately so they can rotate it. The leak cannot be undone.