Third-party API keys in pass and Vault
Checked against CLI 0.88.0. A third-party API key (Runway, Heroku, OpenRouter,
a GitHub token) lives in two places. The local pass store is the GPG-encrypted
copy on the machine where the key was issued. Vault is the account-scoped copy
that other machines, hosts and agents retrieve. Both hold the same bytes. The
key is typed once, into pass; every other copy is piped from there. It never
appears in a command argument, in shell history, in command output, in a Memo
or in an agent transcript.
Naming
| Store | Name | Example |
|---|---|---|
pass | <service>; the first line is the secret, later lines are memos | runway |
| Vault entry | <owner>/cli/<service>/api-key | alice/cli/runway/api-key |
Vault --env | the variable the service's own tooling reads | RUNWAYML_API_SECRET |
<owner>/cli/<service>/… groups every key that a CLI, SDK or agent plugin
reads under one prefix, so dl vault list -p alice/cli audits all of
them and one prefix policy can cover them. Use a different leaf when a service
issues more than one kind of credential (alice/cli/gh/github-token). Entries
saved earlier under <owner>/env/<VARIABLE> keep working; move them to the
convention when they are next rotated.
--env is saved metadata, not a second copy of the secret: vault get --to-envs uses it as the exported variable name. Without it the export is the
last path segment uppercased (API_KEY), which no tool reads.
Store the key
vault add takes the value only from stdin or from a masked prompt; there is
no value flag. --stdin is exact: a trailing newline would be stored and later
exported inside the variable, which is why the pipe strips it.
The write prints metadata and a request ID and no secret. Keep the ID. After a
timeout or an uncertain response, repeat the identical pipe with
--request-id <id>, or look the write up with
dl vault write-status --request-id <id>; see
Vault write recovery.
Rotate the key
Rotate the local copy first, then replace the Vault entry against its current
revision. vault add replaces an existing entry only with --if-match.
Load the key
Keep vault get inside eval "$(…)" or a $(…) assignment. Without
--to-envs it prints the raw value to stdout, which belongs in a pipe or an
assignment and never in a terminal, a log or an agent transcript.
--env-prefix <prefix> prepends a string to every exported name when a tool
expects namespaced variables.
Runway
The official Claude Code plugin runway-api (3.0.0, claude-plugins-official)
reads the key from two variables: its Python scripts read RUNWAYML_API_SECRET
and its runway-api.mjs helper reads RUNWAY_SKILLS_API_SECRET. Save the
entry with --env RUNWAYML_API_SECRET and export both names with the
two-selector get above. The variables hold the same key; there is one entry.
vault import --pass is reserved
dl vault import lists a --pass flag, but it is reserved: ordinary
pass entry import is not implemented and the command rejects it. Only --ssh
and --pass-otp import. The pipe above is the supported path from pass to
Vault for an API key, one entry per command. The two stores are kept in step by
hand: after pass insert -f, repeat the pipe with --if-match.
Rules
- The value is never a command argument.
vault addhas none; do not wrap it in a helper or an alias that takes one. - Metadata is safe to print (
vault show,vault list, write receipts); values are not (vault get,pass show). - One entry per key, named
<owner>/cli/<service>/api-key, with--envset to the variable the tool reads. Add a second name at retrieval time with anALIAS=pathselector, not with a second entry. - Keep the request ID until the write is confirmed; it contains no secret.