secret
Health Uyari
- License — License: GPL-3.0
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 9 GitHub stars
Code Basarisiz
- rm -rf — Recursive force deletion command in .github/workflows/ci.yml
- rm -rf — Recursive force deletion command in .github/workflows/host-hooks.yml
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
Let coding agents use your credentials without reading them

Secret
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; thesecret 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
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 | sh
Windows PowerShell:
irm https://raw.githubusercontent.com/avhn/secret/v0.6.1/install.ps1 | iex
No GitHub account or gh is needed; rerunning updates the installation.
See pins, paths and verification.
Quick start
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 redacted
Then 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.
Where values can live
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 andshow 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.secret
Reading op:// references live, without importing, is planned: theonepassword: 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.
For agents
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 asdiff,doctor,auditandmcpfrom the shell.
Connect your agent
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@secret
The 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 [email protected]
This 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 overview
| 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.
Security limits
- 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 orage: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.
More
- 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
License
GPL-3.0-or-later, copyright Mert Dede.
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi