Let coding agents use your credentials without reading them.
Secret lets a coding agent run commands that need your credentials while the
values stay out of the conversation. The agent works with key names; the
secret CLI puts the selected value into the child program's environment and
replaces it with <redacted> in that program's output.
$ secret show ~/.secrets.env
API_TOKEN=<40 bytes>
$ secret run -f ~/.secrets.env --key API_TOKEN -- ./deploy.sh
deploying with token <redacted> ... ok (illustrative deploy output)It is three parts that work together:
| Part | What it does |
|---|---|
secret CLI |
Stores values (hidden prompt, private atomic writes), shows names with masked lengths, runs a program with selected keys and redacts loaded literal values from its stdout and stderr. |
| Names-only MCP server | secret mcp --store REF exposes four read-only tools (list, show, diff, health) over stdio for explicitly allowlisted stores. It never returns values, value hashes or lengths. |
| Guard hook and agent skill | A Claude Code and Codex plugin that denies known secret-reading tool calls (store and credential files, environment dumps, credential printers, clipboard reads, secret get and secret exec) and teaches the agent the safe workflow. |
Accident prevention, not a sandbox: see Security limits.
Install or update the Secret CLI to the latest release.
Linux/macOS:
curl -fsSL https://raw.githubusercontent.com/avhn/secret/v0.6.1/install.sh | shWindows PowerShell:
irm https://raw.githubusercontent.com/avhn/secret/v0.6.1/install.ps1 | iexNo GitHub account or gh is needed; rerunning updates the installation. See pins, paths and verification.
In your own terminal, stash a value at the hidden prompt. These are illustrative paths:
secret stash ~/.secrets.env API_TOKEN # you: hidden prompt, never argv or chat
secret list # store paths, never contents
secret show ~/.secrets.env # API_TOKEN=<40 bytes>
secret run -f ~/.secrets.env --key API_TOKEN -- ./deploy.sh # child gets the value, output is redactedThen ask your agent to "deploy with API_TOKEN from ~/.secrets.env". It needs only the store reference and the key name.
More that run and its siblings can do, all in usage:
- Select precisely:
--key(required),--optional-key, several-fstores (later wins). Only selected keys reach the child. - Environments and labels:
[env=dev]sections in a store, selected with--env devor--label name=value. - Private templates:
--template-filerenders{{KEY}}placeholders into a private 0600 file and passes its path inSECRET_TEMPLATE_FILE. - Clipboard:
secret clip FILE KEY [SECONDS]copies a value and clears it after 45 seconds unless you copied something else.
Default stores are plain KEY=VALUE files: ~/.secrets.env and
~/.secrets/*.secret. A bare NAME means ~/.secrets/NAME.secret. Other
backends are selected explicitly by reference and work with the same commands.
| Reference | Backend | Linux | macOS | Windows | Notes |
|---|---|---|---|---|---|
path, NAME, file:PATH |
dotenv-style file, private permissions | yes | yes | yes | Default; the only kind list discovers by default. usage |
keychain:NAME |
macOS Keychain | no | yes | no | SECRET_KEYCHAIN selects a keychain path. usage |
libsecret:NAME |
Secret Service through secret-tool |
yes | no | no | Needs an unlocked session. usage |
wincred:NAME |
Windows Credential Manager | no | no | yes | 2560-byte value limit. windows |
pass:NAME |
pass 1.7.4 with your GnuPG setup | yes | yes | no | You initialize the password store. pass |
age:NAME |
age-encrypted file, X25519 keys | yes | yes | no | Explicit --age-identity; create with age-init. age |
Keystore backends keep a names-only manifest under ~/.secrets, so list and
show read names without fetching a value.
1Password and Bitwarden. Copy items into a store with a human-run,
insert-only import through the vendor CLI (op or bw) that you have already
signed in. Explicit field mappings are required:
secret import --from op:ITEM_ID --into file:/absolute/team.secret --map password=API_TOKEN
secret import --from bw:ITEM_ID --into file:/absolute/team.secret --map login.password=API_TOKEN
secret import --from dotenv:/absolute/old.env --into file:/absolute/team.secretReading op:// references live, without importing, is planned: the
onepassword: backend exists in the source but is switched off with no runtime
override until a licensing review and isolated provider testing pass; see
its status. secret export copies records from one store
to a keystore or age store (for example file to Keychain); plaintext export
targets are refused.
If you are a coding agent reading this, the rules are short. The full version is the agent skill; setup is in docs/setup.md.
| You may run | Purpose |
|---|---|
secret list |
Default store paths, without opening them. |
secret show FILE |
Key names, masked lengths and labels. |
secret run -f FILE --key KEY -- CMD |
Run a command with the value in its environment and redacted output. |
secret clip FILE KEY |
Only when the user explicitly asks for the clipboard. |
MCP tools list, show, diff, health |
Names-only metadata for stores the human allowlisted. |
| Human only: never run it | Why |
|---|---|
secret get |
Prints a value to a terminal. |
secret exec |
Unfiltered run, for human-configured launchers. |
secret stash |
The human types the value at a hidden prompt. |
import, export, rotate, rename, delete, age-init, age-rekey |
Operator commands; require real terminals and hidden confirmation. |
- Use the exact store reference the human gave you. Do not search for, open,
cat,grepor patch store files, and do not print or transform values (noecho $KEY,env, base64). - Prefer stdin or header files over arguments, so a value does not appear in
the child's argv:
secret run -f FILE --key API_TOKEN -- bash -c 'printf "Authorization: Bearer %s\n" "$API_TOKEN" | curl -fsS -H @- URL' - Missing key: ask the human to run
secret stash FILE KEYin their own terminal. Never ask for a value in chat. - Denied by the guard: narrow the request or follow its hint. Do not disguise the
command, disable the hook or change permissions. The installed hooks also deny
newer subcommands such as
diff,doctor,auditandmcpfrom the shell.
Names-only MCP server. Register it with the installed executable's concrete absolute path and an exact human-approved store reference. Do not discover or read stores:
claude mcp add --transport stdio --scope user secret -- "/ABSOLUTE/INSTALL DIR/secret" mcp --store "file:/ABSOLUTE/STORE DIR/STORE.secret"Reconnect the client and verify list/show/diff/health. The server is off without
--store, has no network listener and cannot be widened by a request.
Setup covers Claude Code, Claude Desktop (MCPB bundle
or JSON), Codex, ChatGPT desktop, OpenCode, Cursor and VS Code, Windows
equivalents, and the MCP Registry name io.github.avhn/secret (see the
release status for the currently published record).
Guard hook and skill. Optional plugin for Claude Code:
/plugin marketplace add avhn/secret
/plugin install secret@secret
and for Codex:
codex plugin marketplace add avhn/secret
codex plugin add secret@secretThe plugin installs the Bash guard and the agent skill,
not an MCP registration. Codex requires explicit hook trust in /hooks,
including re-trust after changes. Also install the protective ripgrep config;
see plugin and manual-hook instructions.
Go hooks remain inactive; installation and synthetic tests do not prove host
fail-closed protection.
Launching other MCP servers with a credential. For a launcher you configure
yourself, exec supplies selected values without filtering the server's stdio.
It works on macOS, Linux and Windows. -f takes a plain store path, not file::
"/ABSOLUTE/INSTALL DIR/secret" exec -f "/ABSOLUTE/STORE DIR/.secrets.env" --key OPENPROJECT_API_TOKEN -- uvx openproject-ce-mcp@0.4.1This is not the names-only server or an agent retrieval route. Output is unfiltered and can disclose values. Review the server first; see client JSON, Windows paths and shutdown limits.
| Command | Who | What |
|---|---|---|
list, show |
agent or human | Store paths; key names with masked lengths (<stored> for keystores). --format=json is names-only. |
run |
agent or human | Child with selected keys, redacted stdout and stderr, optional --template-file. |
clip |
on human request | Clipboard copy with timed conditional clear. |
stash |
human | Hidden prompt or stdin; private atomic write. |
get, exec |
human | Print one value to a terminal; unfiltered child. |
import, export |
human operator | Insert-only transfer from dotenv, op, bw, or between stores; --dry-run. |
rotate, rename, delete |
human operator | Lifecycle of one exact record. |
age-init, age-rekey |
human operator | Create or rekey an encrypted store. |
diff, doctor, audit, completion |
human | Names-only comparison, diagnostics, opt-in audit log queries, completion candidates. |
mcp |
client launcher | Names-only stdio server. |
secret help prints the full reference. The site lists the same
tools and commands.
- The CLI supplies selected values to a child and redacts literal output. Redaction does not catch base64, URL encoding, substrings or other transformations.
- The guard is heuristic. It denies known secret-reading operations but cannot contain a determined agent, arbitrary child behavior or tools it never sees, including MCP search tools.
- Metadata can reveal key names, labels, paths and provider account IDs.
- Default file stores are plaintext at rest with private permissions; choose a
keystore or
age:store for encryption at rest. - No fail-closed host protection is claimed.
Treat this as one layer, not the boundary. Read the full threat model.
- Usage: stores, providers, labels, operator commands, templates
- Verify, update or roll back, with explicit Bash rollback at
compat/secret - Windows support and limits
- Security model and reporting
- CONTRIBUTING.md for synthetic tests and PR guidance, AGENTS.md for agent rules, ROADMAP.md for milestones
GPL-3.0-or-later, copyright Mert Dede.