keyshroud

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

Edit this page on GitHub · Markdown