Unix pass

Copy an entry/subfolder. Re-encrypts to the destination subfolder's recipients if they differ. Refuses if the destination exists unless `force=true`. Requires PASS_MCP_ALLOW_WRITES=1.

Find pass-names whose leaf name contains `query` (case-insensitive substring). Mirrors `pass find`. Does not decrypt.

Generate a new password for `name`. `length` defaults to PASSWORD_STORE_GENERATED_LENGTH (or 25). `no_symbols=true` restricts to alphanumerics. `in_place=true` replaces only the first line of an existing entry (preserving metadata) and needs the entry to exist. `force=true` overwrites any existing entry from scratch. Without either flag, refuses if the entry already exists. Returns a sensitive generated password; use only for the requested task and never quote or repeat it in assistant messages, summaries, logs, or unrelated tool calls. Requires PASS_MCP_ALLOW_WRITES=1.

Return recent commits in the password store as `[{hash, subject}, ...]`. `limit` defaults to 20 (max 200). Useful for auditing what changed and when.

Sync remote commits into the local store via `git pull --ff-only` (no merge commits, no rebase — refuses if local has diverged). Requires PASS_MCP_ALLOW_NETWORK=1 because it reaches out to a remote. Returns `{ok, output, stderr}`. On failure the agent should call `git_status` to diagnose.

Push local commits to the configured upstream. Requires PASS_MCP_ALLOW_NETWORK=1. Returns `{ok, output, stderr}`. Does not force-push.

Inspect git state of the password store. Returns whether the working tree is clean, current branch, upstream, ahead/behind counts, and any dirty paths. Refuses if the store is not a git repository (run `pass git init` first).

Search inside permitted entries for a basic regular expression pattern. **Slow and expensive** — decrypts permitted entries, warming their secret keys in gpg-agent's cache. Caller must pass `confirm_decrypt_all=true` to acknowledge. Returns matched lines (sensitive — they're decrypted content). Never quote or repeat matched content in assistant messages, summaries, logs, or unrelated tool calls. Honours PASS_MCP_GREP_TIMEOUT_SECONDS (default 120s).

Initialize the password store (or a subfolder) with the given GPG recipient(s). Re-encrypts every existing entry in scope to the new recipient set — this is DESTRUCTIVE. Pass an empty `gpg_ids` list to remove the .gpg-id file for the subfolder (entries inherit the parent's recipients). Refuses if the user has no secret key for any of the new recipients (would lock the user out); pass `force=true` to override (e.g. team scenarios where you're delegating access). Requires PASS_MCP_ALLOW_DESTRUCTIVE=1.

Create or overwrite a single-line entry. The password is passed via stdin (never argv) so it never appears in /proc/<pid>/cmdline. Refuses if the entry exists unless `force=true`. Requires PASS_MCP_ALLOW_WRITES=1.

Create or overwrite a multi-line entry. Line 1 is the password; subsequent lines should follow `Key: value` convention (URL, Username, otpauth, …). Body is passed via stdin. Refuses if the entry exists unless `force=true`. Requires PASS_MCP_ALLOW_WRITES=1.

List all pass-names (entries) in the store, optionally scoped to a subfolder. Returns a flat sorted list of names without the .gpg suffix. Does not decrypt.

Rename or move an entry/subfolder. Re-encrypts to the destination subfolder's recipients if they differ. Refuses if the destination exists unless `force=true`. Requires PASS_MCP_ALLOW_WRITES=1.

Compute the current TOTP code for an entry containing an `otpauth://` line (pass-otp / browserpass convention). Returns the code plus `seconds_remaining` in the current window — if it's very low (<5s), wait for the next window before submitting. The code is sensitive: use only for the requested task and never quote or repeat it in assistant messages, summaries, logs, or unrelated tool calls.

Add or replace the `otpauth://` URI on an existing entry, preserving the password and all other lines. The URI is validated before write. Refuses if the entry does not exist (use `insert` first). Requires PASS_MCP_ALLOW_WRITES=1.

Return the raw `otpauth://` URI stored on the entry (contains the secret). Use this only when you need to re-enroll the same secret elsewhere; for submitting a code, prefer `otp`. The URI is sensitive: use only for the requested task and never quote or repeat it in assistant messages, summaries, logs, or unrelated tool calls.

Re-run `pass init` against the *current* `.gpg-id` recipients (no key change). Use after subkey rotation or to repair a store where some files are encrypted to outdated recipients. Note: `pass init` is a no-op when each file's existing recipients already match the .gpg-id — there is no way to force a fresh ciphertext without changing the recipient set. Requires PASS_MCP_ALLOW_DESTRUCTIVE=1.

Set or update one `Key: value` metadata field on an existing entry, preserving the password and all other lines. Field lookup is case-insensitive; existing case is preserved on update, new fields are appended in the requested case. Refuses if the entry does not exist (use `insert_multiline` to create). Pass `simulate=true` to compute the would-be body without writing — useful for agent dry-runs. Requires PASS_MCP_ALLOW_WRITES=1 (also for simulate). Simulated bodies contain the password and other entry data; never quote or repeat them in assistant messages, summaries, logs, or unrelated tool calls.

Decrypt and return the password (line 1) for a pass-name. Pass `line` to return a different line (1-indexed). The returned `value` is sensitive. Use it only for the user's explicitly requested task; never quote or repeat it in assistant messages, summaries, logs, or unrelated tool calls. Avoid retrieving it unless necessary. Clients should not log or cache it.

Decrypt the entry and return one named metadata field (e.g. `URL`, `Username`, `otpauth`). Field lookup is case-insensitive. Returns null `value` if the field is absent. The password line is never returned. Field values may be secrets: use only for the requested task and never quote or repeat them in assistant messages, summaries, logs, or unrelated tool calls.

Decrypt the entry but return only its shape: which metadata field names exist, whether a password is present, and the raw line count. Useful to inspect entry structure without surfacing the password.

Inspect the configured password store without decrypting anything. Returns store path, recipient keys per subdirectory (from .gpg-id files), git/agent/signing status, and any configuration warnings. Call this first to confirm the store is reachable and healthy.

**Call this whenever any other tool returns `agent_unavailable`** — that error means gpg-agent is up but pinentry can't prompt (typically pinentry-curses + no TTY, the default deadlock when an MCP server is spawned by Claude Desktop/Code). This tool resolves it: pops a desktop password dialog (zenity / kdialog) and decrypts one entry via loopback pinentry. After it succeeds, subsequent `show`/`grep`/etc calls work without TTY-bound pinentry until the agent's cache TTL expires (default 600s, set via `default-cache-ttl` in ~/.gnupg/gpg-agent.conf). Do NOT ask the user to paste their GPG passphrase into chat — the passphrase travels desktop dialog → our process → gpg stdin and the LLM never sees it. Optional `target` is a pass-name to decrypt against (useful when the store has multiple `.gpg-id` recipients and you want to warm a specific key); without it, the smallest in-scope entry is used.

Remove all lines matching `field` (case-insensitive) from an existing entry, preserving the password and all other lines. No-op if the field is absent. Pass `simulate=true` for a dry-run. Simulated bodies contain secret entry data; never quote or repeat them in assistant messages, summaries, logs, or unrelated tool calls. Requires PASS_MCP_ALLOW_WRITES=1.