CLI reference
keyshroud get <ENV_NAME | keyshroud://ref | bw://ref | source ref> print one value (for scripts; not for agents)
keyshroud run [--refs F]... [--only A,B] [--no-auth] [--no-mask] -- <cmd>
keyshroud inject [-i template] [-o out] [--force]
keyshroud redact < log.txt
keyshroud scan [paths...]
keyshroud env [--shell]
keyshroud scope [--only A,B_* | --clear] this directory's .keyshroud.json: which wired names it gets
keyshroud add --env NAME --item ITEM [--notes TEXT] [--target pi|omp|both] [--stdin|--dialog]
keyshroud import [--from F|-] [--out F] [--prefix P] [--only A,B] [--skip A,B] [--yes] [--replace] [--force]
keyshroud rotate --item ITEM [--stdin|--dialog]
keyshroud wire --env NAME --item ITEM [--target pi|omp|both] [--force]
keyshroud unwire --env NAME [--target pi|omp|both]
keyshroud list item references and the variables wired to them (names only)
keyshroud rm --item ITEM [--yes] delete an item and unwire it (dry run unless --yes)
keyshroud source the sources that are set up, and the vendor CLIs found
keyshroud source add vault [--addr URL] [--namespace NS] [--ca-file PEM] [--token | --role-id ID] [--stdin|--dialog]
keyshroud source add infisical --client-id ID [--addr URL] [--ca-file PEM] [--stdin|--dialog]
keyshroud source rm vault|infisical
keyshroud setup --email EMAIL [--server URL] [--confirm-unlock | --unattended] [--registered] (Vaultwarden)
keyshroud migrate [--item NAME]... [--refs F]... [--yes] (Vaultwarden)
keyshroud migrate --to local [--yes] (Vaultwarden -> local vault)
keyshroud unlock [--unattended | --stdin]
keyshroud rekey [--to keychain|secure-enclave|passphrase|dpapi] (in a terminal)
keyshroud backup [--out FILE] (in a terminal)
keyshroud restore FILE [--replace] [--yes] (in a terminal)
keyshroud status | lock | doctor
keyshroud mcp
keyshroud hook claude <session-start|post-tool-use>
keyshroud claude-setup --item ITEM [--settings PATH] [--ttl-ms N] [--force]
keyshroud claude-guard [--off] [--shell PATH] [--settings PATH]
keyshroud api-key --item ITEM
keyshroud link-cli [--dir DIR] [--force]
--item takes a name (stored in the default vault), keyshroud://Name or bw://Name; for wire also a
source reference such as vault://secret/app#password.
rm prints what it would do (delete a local item permanently, or move a bw item to the bw trash, and
which variables it unwires) until you add --yes. With --yes it needs a terminal, or
a Touch ID approval on a Mac when an agent runs it. It works on bw only with keyshroud's own agent
account, and refuses the item Claude Code's apiKeyHelper uses. .env.refs files that point at a
removed item then fail as unresolved.
run masks what the command prints, in a terminal too: several agents run their commands on a
pseudo-terminal, and what is shown there is what the agent reads. Before 0.13 a terminal was passed
through unmasked. Masking means the command writes into a pipe, so a program that needs the terminal
itself (psql, an editor, an agent's own interface) is started with --no-mask: it gets the
terminal, and nothing it prints is masked. The output is masked byte for byte: what is not text (an
archive, a database dump) comes out as it went in, so keyshroud run -- pg_dump -Fc db > db.dump is
safe. --mask is still accepted and changes nothing. exec is an alias of run.
A wired name that does not resolve is left out and named on stderr (unresolved (names only): …), and
the command still runs. A name you ask for with --only is one the command needs: when it does not
resolve, the command is not run, and run exits 3 (the vault could not be unlocked) or 4.
secrets_run with only does the same.
--refs F adds the names in a file of references (a .env.refs); give it more than once for several
files. Before 0.12.3 the flag was --env-file. That spelling still works, so scripts keep running,
but Node.js 20.6 and later reads a file named with --env-file itself, before keyshroud starts, and
keyshroud cannot check the file first: use --refs, above all with a file you did not write.
add and rotate read the value from a masked prompt that shows * per
character. Without a terminal (an agent's shell), they open a native hidden-input
dialog instead (osascript on macOS, zenity or kdialog on Linux, PowerShell on Windows), so the agent
can start the command and you only paste. Over SSH or without a display, pipe the
value with --stdin.
add refuses a name that is already wired to another item (exit 5), before it asks for the value:
rotate --item gives that item a new value, and unwire --env NAME frees the name for a new item.
import reads a .env (default ./.env), decides which lines are secrets (by name, such as
*_TOKEN or *_KEY, or by value, such as sk-… or a URL with a password), and prints a plan of
names only. No vault item and no .env.refs is written until you add --yes (reading the plan opens
a vault session as any command does, with the files that belong to one): it then creates one vault item per secret,
named <prefix> NAME (prefix defaults to the directory name), reads each value back to verify it,
and writes .env.refs (NAME=keyshroud://<prefix> NAME) with comments and non-secret lines kept. Re-running reuses items that already
hold the same value and stops on a conflicting one. --replace rewrites the source file in place
instead (atomically, no backup copy). Multiline values, ${VAR} expansion and duplicate keys are
rejected with the line number, never the value.
keyshroud import # dry run: which names would move
keyshroud import --yes # store them and write .env.refs
keyshroud run --refs .env.refs -- npm test
Exit codes: 0 ok · 2 usage · 3 vault locked or unavailable, or a source that did not accept
the sign-in · 4 secret missing or item name ambiguous · 5 refusing to overwrite existing state.
run exits with the child's code (or 3/4 before it starts, when a name given with --only does not
resolve; 126 when the command is there and cannot be run, 127 when it is not found).
References
| Reference | Resolves to |
|---|---|
keyshroud://GitHub token |
the value stored in the local vault |
keyshroud://GitHub token/notes |
its notes (id also works) |
!keyshroud get 'keyshroud://Item' |
the env.json / auth.json form keyshroud writes for local items |
bw://GitHub CLI token |
login password |
bw://GitHub CLI token/username |
login username (notes, uri, id also work) |
bw://Sentry/fields/dsn |
custom field dsn |
bw://AWS root/totp |
current TOTP code |
bw://a%2Fb |
item named a/b (keyshroud://a%2Fb alike) |
!bw get password 'Item' |
legacy auth.json form, still supported |
local://GitHub token |
the first spelling of keyshroud://, still read the same way |
vault://secret/myapp/db#password |
field password of the KV secret myapp/db on the mount secret/ (HashiCorp Vault, OpenBao) |
infisical://<project id>/prod/STRIPE_KEY |
the secret STRIPE_KEY of environment prod (a folder goes before the name) |
op://Engineering/Sentry/dsn |
what op read gives for it (1Password) |
awssecrets://prod/stripe#api_key |
key api_key of a JSON secret in AWS Secrets Manager (?region=eu-west-1 picks the region) |
awsssm:///prod/db/password |
the parameter /prod/db/password in AWS SSM Parameter Store, decrypted |
gcpsecrets://my-project/stripe-key |
the latest version in Google Cloud Secret Manager (?version=3 for another) |
azurekeyvault://my-vault/stripe-key |
the current version in Azure Key Vault (/<version> for another) |
!keyshroud get 'vault://secret/app#key' |
the env.json / auth.json form wire writes for a source reference |
Source references share one shape, <scheme>://<path>[?param=value][#key], with %23, %3F and %25
for a #, ? or % in the path; op:// is passed to op as it is written.
Item lookup is case-insensitive by name or exact by id. Duplicate names fail
closed (exit 4) instead of guessing; the local vault refuses to create one.
Configuration
| Variable | Default | |
|---|---|---|
KEYSHROUD_BACKEND |
the backend file |
local or bw: where new items go and which vault opens by default |
KEYSHROUD_VAULT_KEY |
per OS | key mode when the local vault is created: keychain, dpapi, passphrase or secure-enclave (Touch ID); anything else is an error |
KEYSHROUD_CACHE_TTL_MS |
3600000 |
in-memory Vaultwarden snapshot + session check lifetime, and how long a long-running process keeps a value read from a source; 0 disables |
KEYSHROUD_SESSION_TTL_MS |
1800000 |
how long an unlocked session lasts (Vaultwarden, or a passphrase or Touch ID vault) |
KEYSHROUD_LOCK_TIMER |
on | 0 skips the background timer (sessions then end on the next call) |
KEYSHROUD_CONFIG_DIR |
$XDG_CONFIG_HOME/keyshroud |
vault.json, env.json (wiring), sources.json (servers of the sources), backend, sessions, bw/ (after setup), guard/ (after claude-guard), master-password hash, redact index, audit log |
KEYSHROUD_KEYCHAIN_MASTER |
vaultwarden-master-password |
keychain service names (after setup: keyshroud-…) |
KEYSHROUD_KEYCHAIN_CLIENT_ID |
vaultwarden-api-client-id |
|
KEYSHROUD_KEYCHAIN_CLIENT_SECRET |
vaultwarden-api-client-secret |
|
KEYSHROUD_AUDIT |
on | 0 disables audit.jsonl |
KEYSHROUD_PLANNER_URL / _MODEL / _API_KEY |
unset | optional naming helper for /secret |