MCP tools and CLI commands

Names-only MCP tools

MCP is off until explicitly allowlisted with secret mcp --store REF [--store REF ...]. Every tool is annotated read-only. No tool mutates stores or returns values, value hashes or lengths; there are no resources, prompts or network listeners. Requests cannot expand the configured allowlist. Results are one JSON text content item.

listRead-only

List names and labels in explicitly allowlisted stores.Parameters: none.Returns: version and stores, each with reference, backend and records of key, labels, present and an optional provider account.

showRead-only

Show names-only metadata for one allowlisted store.Parameters: reference (string), selectors (object of label name to string value).Required: reference. A reference outside the allowlist fails with Store is not allowlisted.

diffRead-only

Compare selected names, labels, presence and backend only.Parameters: left (string), right (string), left_selectors, right_selectors (objects of label name to string value).Required: left, right. There is no value equality, hash, size or changed field.

healthRead-only

Report configured metadata service readiness, not host protection.Parameters: none.Returns: version (metadata schema), status (ready) and stores (count). Not provider availability, value validity or hook protection.

Unknown arguments are rejected rather than ignored, so an unexpected field cannot imply scoping. Metadata can still reveal key names, labels, presence, backend, references, paths and provider account IDs to the client, its model and its logs.

Everyday CLI

Stores use KEY=VALUE lines: ~/.secrets.env and ~/.secrets/*.secret by default (SECRETS_ENV and SECRETS_DIR override them). --env dev means --label env=dev; repeat --label name=value to select multiple labels.

secret list

Prints store paths, never contents. --backend age lists age stores; --format=json emits names-only metadata.

secret show [FILE ...]

Lists keys with masked byte lengths, such as API_TOKEN=<40 bytes>, or <stored> for keystore stores.

secret stash FILE KEY

Reads a value from a hidden prompt or stdin and writes it with a private atomic replacement.

secret run -f FILE --key KEY -- CMD

Exports only the selected keys to the child and replaces every loaded value with <redacted> in its output. --optional-key marks optional keys; --template-file renders a private file for the child.

secret clip FILE KEY [SECONDS]

Copies a value and clears the clipboard after 45 seconds unless you have copied something else since. Agents use it only when you ask for the clipboard.

secret version, secret --version

Prints the release, for example secret 0.6.0 (go).

secret help

The full reference, including exit statuses.

Human-only commands

The guard denies these to agents.

secret get FILE KEY

Prints a value, and only to a terminal.

secret exec -f FILE --key KEY -- CMD

run without redaction, for interactive tools and MCP server launchers that need byte-exact stdio.

Operator commands

Operators require both stdin and stdout terminals before store access, then exact hidden confirmation of every target, key and label identity. There is no --yes, piped confirmation or operator JSON. Invoke them directly in your own terminal, never through agent tools.

secret import --from SOURCE --into REF

Insert-only import from dotenv:ABS_PATH, op:ID or bw:ID; op and bw imports require explicit --map FIELD=KEY mappings. --dry-run lists names and conflicts only.

secret export --from REF --to TARGET --on-conflict=fail

Insert-only export to a different keystore destination. Without selectors only unlabeled records qualify.

secret rotate REF KEY

Reads the new value hidden, never in argv.

secret rename REF OLD NEW

Renames the exact record identified by its lifecycle labels.

secret delete REF KEY

Deletes the exact record identified by its lifecycle labels.

secret age-init, secret age-rekey

Create an explicit age:NAME encrypted store (create-only) or rekey it after verifying the new identity. Linux and macOS only.

Metadata and diagnostics

These expose only metadata, never values, hashes or lengths. The installed hooks conservatively deny new subcommands to agents, including names-only ones; this feature grants no hook exception.

secret diff REF [REF]

Compares names, labels, presence and backend between stores or label sets.

secret doctor [REF ...]

Reports tracked recovery candidates and manual verification guidance, not a complete orphan inventory or installed-host trust.

secret completion

Emits literal candidates, not shell code, and reads only explicit -f scopes.

secret audit --directory ABS_PATH

Queries names-only audit events. Audit is off unless an operator receives --audit-dir ABS_PATH.

secret mcp --store REF [--store REF ...]

Starts the names-only stdio server above for exactly the listed references.

Store references

• Bare names and paths use file stores; file:PATH forces a literal file path.
• keychain:NAME uses the macOS Keychain and libsecret:NAME the Linux Secret Service. Their manifests hold only key names, labels and random account identifiers.
• pass:NAME uses optional pass on Linux and macOS.
• wincred:NAME uses native Windows Credential Manager.
• age:NAME explicitly selects an encrypted store; defaults never discover it, and value commands need --age-identity FILE.

Full details are in docs/usage.md. See setup to register the MCP server and security for limits.

Protocol details

• Newline-delimited JSON-RPC over stdio. The server identifies as secret-metadata version 1 and answers protocol 2025-06-18, or 2024-11-05 and 2025-03-26 when the client requests them.
• Input frames are bounded to 64 KiB and responses to 4 MiB. Batches and duplicate JSON keys are rejected.
• Error messages never echo input, parser diagnostics, store errors, argv or provider stderr.
• Up to 64 distinct --store references per server; file references must be absolute.