Preflight — will this ask you?

kovra preflight answers one question before an operation runs: will it ask the person, where, and why? Agents use it instead of guessing, so they stop telling you that something “will ask for Touch ID” when it will not.

It is a dry run in the strict sense: it never asks you, never contacts the phone or the relay, never materializes a reference, never writes, and never prints a value or a fingerprint. It decides with the same function the real operation uses, so the answer matches what would happen. It is advice, not permission: a level, the pairing or the session may change before the operation, which decides again.

On the command line

~ % kovra preflight run --env prod -- ./deploy.sh
run: asks for your approval
  where: Touch ID at the Mac
  secrets that make the run reviewed:
    API_TOKEN ← prod/app/token (prod, high)

The answer is one of: free (no approval), free_and_notify (no approval, kovra shows a notification), approval (it asks you), refused (refused before anything is asked) or unaddressable (MCP only). --json prints the same fields. It exits 0 whenever it answered, whatever the answer; it exits non-zero only when it could not answer (a malformed coordinate, no vault, an unreadable .env.refs, or, for phone-forget and license-deactivate, which read kovrad first, a kovrad that does not respond).

Where it would ask is one of: Touch ID, or your login password, at the Mac; the Mac or the paired phone (kovra Mobile, coming soon; the first answer wins); only the paired phone, where no prompt can be shown here (over SSH); the Mac only (the master key, pairing and releasing); or denied, when no prompt can be shown and no phone is paired. It reads only what is known locally, so it cannot tell whether the phone is muted, and says so. Why is given when the operation is refused (for example an inject-only secret that show will never reveal, or a prod secret asked for from an agent’s session).

It covers twenty-one operations: run, show, code, add, set, generate, keygen, import, edit, rm, package, unpack, sign, decrypt, ssh-add, key-export, phone-pair, phone-forget, intake-fulfill <id>, init --force and license-deactivate (the release of this Mac’s license, asked at the Mac only). Each takes the operation’s own arguments, never a value. It opens the vault like kovra list does, so it needs the same key the operation needs.

It answers as the operation would for whoever runs it: inside an agent’s session, kovra preflight show of a prod secret and kovra preflight code of a prod TOTP are refused, just like the real commands.

Over MCP

The preflight tool answers the same for the tools that may ask: inject_run, reveal, set, generate, delete and edit_metadata. It works under the session’s scope: a coordinate outside the scope, or an operation the scope does not permit, is unaddressable, with no metadata. A reveal that would need you is refused, as the tool refuses it. It never names your phone; it says “the paired phone”. The conventions block kovra setup writes tells agents to ask preflight before telling you something will ask for approval. See MCP tool reference.