Is the vault initialised/unlocked, how many credentials, approval mode, etc.

ALWAYS THE FIRST STEP when anything needs credentials — a login, an API call, a CLI or DB that needs auth, a 2FA code, or the user asking for a password/token/key. Pass whatever you have: a URL, hostname, name, alias or phrase ("https://ci.example.com/job/x", "jenkins", "prod db", "aws sg"). Returns ranked matches, metadata only (secrets hidden), and flags ambiguous when you should ask the user which one.

List every stored credential (metadata only — names, types, usernames, URLs, aliases, tags, policies). Use this to answer "what creds / passwords / logins / keys do you have?". Optionally filter by type or tag.

Get one credential by id, name, alias or URL. With reveal=true the raw secret values are returned (subject to its policy — may pop an approval dialog for the user). Always give a short purpose when revealing. Prefer http_request/run_with_credential over revealing.

Store a new credential. Keys the agent can later look it up by: name, aliases, urls (full URLs, bare hosts, or wildcards like *.corp.com), and tags.

secret_source (how the main secret is obtained — prefer ones that keep it out of the chat):
  prompt    (default) user types it into a secure macOS dialog
  clipboard read from clipboard, then clear it (user copies it first)
  file      read from `secret_file` (great for SSH keys / service-account JSON)
  generate  create a strong random password/passphrase
  value     use `secret` as given (only if the user already pasted it in chat)
  none      no main secret (e.g. only extra_secrets / notes)
`secret_field` overrides the field name (default depends on type: password/token/key/...).
`extra_secrets` e.g. {"totp_secret": "JBSW..."} or {"api_secret": "..."}.
`fields` = non-secret extras, e.g. {"host": "db.internal", "port": "5432", "region": "ap-south-1"}.
policy: open | confirm | sealed | strict (default from config).

Modify a credential. Only the arguments you pass change. To change the main secret use secret_source (prompt / clipboard / file / generate / value) — the previous value is kept in version history for rollback. Loosening the policy requires the user's approval. Use add_urls/add_aliases whenever you learn a new way the user refers to this credential.

Move a credential to the trash (recoverable with restore_credential).

Restore a credential from the trash.

List soft-deleted credentials.

Permanently destroy a trashed credential. Always requires the user's approval.

Previous versions of a credential's secrets (values hidden) for auditing / rollback.

Restore a credential's username+secrets to an earlier version (current one is kept in history).

Make an HTTP request authenticated with a stored credential, without exposing the secret. auth: auto (basic for user+password/user+token e.g. Jenkins; bearer for bare tokens), basic, bearer, none, header:, query:. Placeholders {{km.password}}, {{km.username}}, {{km.token}}, {{km.}} are substituted in url/headers/body. Only hosts registered on the credential are allowed (anti-exfiltration guard). Response body is scrubbed of the secret.

Run a bash command with the credential injected as environment variables; stdout/stderr are scrubbed of the secret (and its base64/url/hex encodings). Always set: KM_NAME, KM_USERNAME, KM_SECRET (main secret), KM_ for every secret and field (KM_PASSWORD, KM_TOKEN, KM_KEY, KM_HOST...), KM_URL, KM_BASIC_AUTH. Type extras — aws: AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN/AWS_REGION; database: PGHOST/PGPORT/PGUSER/PGPASSWORD/PGDATABASE/MYSQL_PWD; ssh_key: KM_KEY_FILE (temp 0600 file, shredded after) + GIT_SSH_COMMAND. env maps extra var names to fields, e.g. {"JENKINS_TOKEN": "token"} or templates {"CREDS": "{{km.username}}:{{km.password}}"}. stdin also supports {{km.*}} placeholders. Example: curl -su "$KM_USERNAME:$KM_TOKEN" https://ci.example.com/api/json

Current 2FA/TOTP code for a credential that has a totp_secret (plus seconds remaining).

Copy a secret (default: main secret; or 'username', 'totp', any field) to the macOS clipboard for the human to paste. Auto-clears after N seconds. The agent never sees it.

Generate a strong password or diceware-style passphrase. With store_in (a credential ref) it is written straight into that credential (old value kept in history) and NOT returned — use this for rotation so the new secret never enters the chat.

Audit the vault: weak, reused, expired/expiring, stale, unused and (optionally) breached passwords via HaveIBeenPwned k-anonymity (only 5 hash chars leave the machine). Graded A–F.

Recent vault activity (who revealed/used/changed what, when). Optionally for one credential.

Lock the vault now (removes the key from the keychain). Unlocking needs the user.

Unlock the vault by asking the user for the master passphrase in a secure dialog (the passphrase never passes through the agent).

Cancel every time-boxed 'Allow for …' approval, so the next reveal asks again.

The supported credential types and the main secret field of each.