Command reference

← README · related: Policies · Importing · MCP · Configuration

Values are always read from a TTY (no echo) or piped stdin — never passed as arguments.

An empty read is refused on every write path (set, rotate, and import --overwrite). The case this exists for is a pipe whose producer failed:

vault-cli read prod/key | arca set PRODKEY    # producer fails, prints nothing…

Without the guard, stdin closes empty, arca reports success, and the stored value is gone — the store keeps only the current value, so there is no undo. Pass --allow-empty when you genuinely mean to store nothing. Whitespace is a value, not an absence: a single space is stored, while "", a bare newline, and CRLF are refused.

The per-secret policy flags (--no-print, --require-approval, --canary, --require-grant, --rate) are documented in Policies.

Disabling a secret (fast, reversible kill switch)

disable NAME is the quickest way to take a secret out of service without losing it: the value and all metadata stay in the store, but every access path — get, exec, inject, env, and the MCP tools, including a capability handle minted before you disabled it — refuses it until you enable it again. Handles are made inert rather than revoked, so undoing a false alarm restores the pre-incident state exactly instead of forcing you to re-issue every handle you had handed out. It's a dedicated flag, independent of expiry, so a disabled secret shows as DISABLED in show / [disabled] in ls, the audit log records the disable/enable intent, and — unlike before 0.6.3 — enabling it keeps any real expiry the secret was carrying (disable/enable no longer touch expires_at).

arca disable GITHUB_TOKEN     # suspend it everywhere, keep the value + any expiry
arca enable  GITHUB_TOKEN     # bring it back (a real expiry, if any, is preserved)

Upgrade note: secrets disabled by an arca before 0.6.3 were suspended by stamping expires_at to now, so they read as EXPIRED (not DISABLED); clear that with rotate / set --expires-at.

This is a local kill switch, not revocation. Disabling stops arca from handing the value out; it does nothing to a copy that already leaked. On a suspected compromise, revoke the token at its issuer first (GitHub, AWS, …), then disable or rotate it here.

Note: env skips any secret it can't release — disabled/expired and --require-grant — instead of failing, so one suspended secret never blanks out eval "$(arca env)".

Accepting a recipient set (recipients pin)

arca records the recipient set each machine has been shown, in recipients.pin under that machine's state dir. The file never syncs: it is this machine's memory of what it expects, and a baseline that travelled with the store would be controlled by whoever controls the store.

Adding a recipient here is already guarded by an operator prompt. A recipient added on another machine and pulled in by sync is not, so the store can arrive carrying a key nobody here was ever shown. When that happens arca warns on every load and doctor raises its readership check to HIGH and names the key. Review it with arca who-can-read, then either:

• arca recipients pin to accept the current set as expected (prompts on the terminal, listing the keys that are not yet accepted, and records op=recipients-pin in the audit log), or
• arca recipients rm KEY to drop it.

The warning repeats until you do one or the other. Loading the store never accepts a key by itself, because a warning that silenced itself would report an injected key exactly once.

The baseline is established silently the first time a store is loaded, so a key that was already present at that point is accepted without comment. Reviewing arca who-can-read once, on a store that predates this check, is the way to close that gap.

Removing a recipient (recipients rm)

recipients rm KEY drops an age recipient (e.g. an ex-teammate's key) and re-encrypts every secret to the remaining keys in the same step, so the current store immediately stops being decryptable by the removed key. Use --no-reencrypt to defer the re-wrap to a later arca reencrypt.

Re-encryption is not revocation of what was already read. The removed key can still decrypt any copy it already had — local clones, backups, and every prior version of the store in git history. recipients rm prints this warning and lists the secrets to rotate. To truly deny the removed holder a secret, rotate its value (arca rotate NAME) so the old ciphertext decrypts to a dead value — and, as always, revoke the underlying credential at its issuer.