This is the map of the kovra CLI. Each command runs through the same
policy decision; run kovra <command> --help for its
exact flags and arguments.
| Command |
What it does |
kovra init |
Initialize the vault registry and master key. Creates a key only when the keyring has none; over a vault that already holds sealed records it takes --force and your approval. |
kovra setup |
Onboard the current repo: ensure the vault, register the MCP server in .mcp.json, insert the conventions block in CLAUDE.md, install the credential gate’s hooks in .claude/settings.local.json (the Read denials in .claude/settings.json), and register kovrad at login (macOS). --dry-run previews. |
kovrad is kovra’s per-user service; it runs the credential gate. On macOS it starts at login and is listed as kovrad under System Settings → General → Login Items → Allow in the Background. If you turn it off there, it does not start at login, and kovra starts it only when needed, without restarting it if it dies; kovra daemon status and kovra doctor remind you, and tell that switch apart from a registration that failed, which kovra daemon install repairs.
| Command |
What it does |
kovra daemon status |
Show whether kovrad is running: pid, version, uptime, connections and the gate’s counters. |
kovra daemon start |
Start kovrad if it is not running (and restart one of another version). |
kovra daemon stop |
Stop kovrad. |
kovra daemon install |
Register kovrad to run at login and restart it if it dies (macOS); it returns once kovrad answers. |
kovra daemon uninstall |
Stop kovrad and remove that registration; kovra setup then leaves it off until kovra daemon install. |
| Command |
What it does |
kovra add <coord> |
Create a secret (value via hidden prompt or --stdin; never argv). Creating one in a project vault (--project) over a critical global secret takes your approval, as add, set, generate, keygen, import, intake fulfill and unpack all do. --description writes the usage note agents read (at most 500 characters); --mint-only marks a master credential that should only mint scoped child tokens (literals and references). |
kovra set <coord> |
Update a secret’s value, keeping its note and its mint-only mark. Overwriting a high or inject-only one takes your approval. |
kovra edit <coord> |
Edit metadata (sensitivity / description / reference / --mint-only true|false); lowering sensitivity is a guarded downgrade. On a critical secret, one edit can’t change both sensitivity and reference. The CLI is the only place that unmarks a mint-only secret or changes its note; an agent can only mark one. |
kovra rm <coord> |
Delete a secret. A high or inject-only one takes your approval (Touch ID, or your login password). |
kovra list |
List secrets — metadata only, never values. high, inject-only and prod values show no fingerprint (—). The mode shows mint-only for a marked secret, and the note column its usage note. |
kovra show <coord> |
Reveal one value to stdout (high needs bioProve; inject-only never). A mint-only secret comes with kovra’s warning on stderr. |
kovra generate <coord> |
Generate a random value server-side; never printed. |
kovra import <coord> --from op://… |
Copy a value from 1Password into the vault as a literal. |
The agent-initiated flow: an agent (or you) queues a request to create a secret —
naming only the coordinate, never a value — and a human fulfils it out-of-band, so the
value never passes through the agent’s context. See kovra over MCP.
| Command |
What it does |
kovra intake request <coord> |
Queue a request to create a secret (--sensitivity, --description; no value here). |
kovra intake list |
List the pending secret-creation requests. |
kovra intake fulfill <id> |
Supply the value for a request and seal it (--stdin / --clipboard / --window; a high or prod creation confirms). Over a secret that already exists it rotates it, and always asks for your approval. |
kovra intake cancel <id> |
Drop a pending request without fulfilling it. |
On macOS, the kovra-menulet menu-bar app lists pending requests and opens the native
fulfilment window for you.
| Command |
What it does |
kovra mcp |
Serve kovra’s MCP server over stdio. Your agent starts it from .mcp.json, which kovra setup writes; you don’t run it by hand. Scope from KOVRA_MCP_OPERATIONS, KOVRA_MCP_ENVIRONMENTS and KOVRA_MCP_PROJECTS. See kovra over MCP. |
| Command |
What it does |
kovra run --env <e> -- <cmd> |
Resolve an .env.refs and run a command with values injected into the child process. --allow allowlists an executable (by its resolved path) for high/prod for this run, with your approval — asked only when the run actually delivers such a value. A run that delivers high/prod gets a sanitized environment (fixed PATH, no code-loading variables). A run that injects a mint-only secret writes a warning to kovra’s stderr — the coordinate, kovra’s advice and the note — before the child starts (with --stdio too), and still runs. |
kovra allow add / rm / list |
Manage the executor allowlist — the reviewed programs that may receive a high/prod value. It is sealed under the vault key, so only kovra writes it; add takes your approval. Each entry pins the program’s content (an edit un-allowlists it; list marks it changed since it was approved); generic interpreters and launchers (sh, bash, env, python, node, make, npm, docker, …) are refused. |
kovra run --stdio -- <cmd> |
Same, but inherit stdin/stdout/stderr into the child (alias --interactive) — needed to wrap interactive processes and stdio MCP servers. Output isn’t captured, so no masking; the secret is still injected via the environment only and the high/prod gates still run. |
| Command |
What it does |
kovra code <coord> |
Print the current TOTP code (never the seed). Gated as a reveal: an inject-only enrollment never shows a code, and a prod code asked from an agent’s session is refused (I14); from your own shell it asks for your approval. |
kovra keygen <coord> |
Generate and custody an asymmetric keypair (private half never on disk). |
kovra pubkey <coord> |
Print a keypair’s OpenSSH public key (free). |
kovra sign <coord> [file] |
Sign a file, or stdin, with the private key; the signature goes to stdout. A high, inject-only or prod key asks you, and the approval shows the SHA-256 of the signed data and, on the Mac, the document itself (see What a signature approval shows). --reason "<text>" says what the signature is for, in one line of at most 200 characters; the approval shows it as the requester’s text, which kovra does not verify, and the audit records it. A reason that is empty, longer, or has a line break, a control, format, bidi, combining or invisible character, or a space other than the plain one is refused with exit code 2, before anything is asked. |
kovra verify <coord> [file] |
Verify a signature (--signature <file>) with the public key, also of a public-only entry (free). |
kovra encrypt / decrypt |
Encrypt to / decrypt with an ed25519 keypair. |
kovra ssh-add <coord> |
Load a custodied key into the running ssh-agent, in memory only. Refuses high, inject-only and prod keys — those sign only through kovra ssh-agent. |
kovra ssh-agent |
Run kovra as a governed ssh-agent (signs in memory; high/prod confirm per signature, and the dialog names the requesting process and what is signed). |
| Command |
What it does |
kovra add <coord> --reference azure-kv://… |
Store a pointer to Azure Key Vault. |
kovra add <coord> --reference aws-sm://… |
Store a pointer to AWS Secrets Manager. |
References resolve at runtime under your own identity. See
Cloud references.
| Command |
What it does |
kovra preflight <operation> … |
Answers, before an operation runs, whether it would ask you, where (the Mac, the paired phone, or only the phone over SSH) and why. It never asks, never prints a value and never contacts the phone; --json prints the same fields. See Preflight. kovra preflight sign <coord> --reason "<text>" checks the reason as kovra sign does and refuses it the same way (exit code 2). |
| Command |
What it does |
kovra phone pair |
Pair the kovra Mobile app on your iPhone (coming soon, not published yet): prints a QR and, once the phone answers, the 6-digit code both screens share, and keeps the pairing once you approve it at the Mac. --relay <url> picks another relay. |
kovra phone status |
Show the paired phone, its relay and whether notifications are on or muted. |
kovra phone forget |
Forget the paired phone, approved at the Mac. |
See Approve from your iPhone.
| Command |
What it does |
kovra license status |
Show the license: state, plan, lease and grace, and whether updates are allowed. --json for the menu-bar app. |
kovra license activate |
Activate this Mac with the code Kaeus sent you (hidden prompt, or --stdin; never an argument). |
kovra license refresh |
Renew the license now (kovrad renews it on its own). |
kovra license deactivate |
Release this Mac’s seat in the license (activating again needs a new code); approved at this Mac only. |
A license never keeps you from your secrets; it only gates updates. See The Free license.
| Command |
What it does |
kovra confirm <text> |
Request an attended human confirmation (exit 0 if approved) — for a host/app to gate its own action. The approval introduces the text as the calling program’s: A program — not kovra — asks you to approve. |
kovra approve [id] |
Development builds and platforms other than macOS: approve/deny a request of the file broker. On a Mac every approval is in kovra’s review window, and an agent cannot approve: inside a Claude Code session it refuses. |
| Command |
What it does |
kovra ui |
Bring up the on-demand loopback admin UI. On macOS it opens in a native window by default; --browser opens it in the system browser instead (--no-open also implies browser mode and only prints the URL; refused on macOS, where the printed URL never carries the session token); --window forces the native window; --persistent keeps it up and locks on idle instead of shutting down. |
| Command |
What it does |
kovra scaffold |
Scan source for env-var references and propose an .env.refs (reads names only, never values). |
kovra doctor (lint) |
Validate a project’s secret config; coordinates + status only, never a value. Exits non-zero on a hard finding. Without ./.env.refs it checks no contract, prints its notes on this Mac (PATH, kovrad, notifications, license) and exits 0; with --refs <file>, a missing file is an error, so a hook or CI step that must validate the contract passes --refs. |
kovra hooks |
Manage git hooks that keep secrets out of commits. |
kovra audit |
Query the audit trail — coordinates, truncated fingerprints, timestamps, origin; never a value. |
kovra key export / import |
Back up / restore the vault master key (disaster recovery). export is approved with biometrics only when the Mac has Touch ID; import restores only a key that opens the vault’s records. |
