ctrlrun command reads the policy in the working directory (ctrlrun.yaml, or the
file $CTRLRUN_CONFIG names) and the store beside it, .ctrlrun/state.db, unless
--store-url or $CTRLRUN_STORE_URL names another. A command that reads evidence creates
nothing and migrates nothing. Each section below is the command’s own --help, verbatim.
ctrlrun
Usage: ctrlrun [OPTIONS] COMMAND [ARGS]...
CTRLRun — the execution safety layer for AI agents.
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
approve Grant a pending approval request.
delegate Create a delegated grant beneath an existing one.
demo Run the five scenarios, in process, with no network.
deny Refuse a pending approval request.
effects Show the logical effects this store knows about.
gateway Front an MCP server, applying this directory's policy to...
init Write a starter ctrlrun.yaml and create .ctrlrun/.
inspect Show one action's whole history: proposal, decision,...
mcp-operator Answer approvals from an MCP client, over loopback...
receipts Show the receipts this store holds.
resolve Say what actually happened to an effect with an unknown...
revoke Revoke a delegation, and with it every delegation beneath it.
stats Count what this store's receipts say, from the local store...
verify Run the declared guarantees against this configuration...
ctrlrun init
Usage: ctrlrun init [OPTIONS]
Write a starter ctrlrun.yaml and create .ctrlrun/.
Options:
--help Show this message and exit.
ctrlrun demo
Usage: ctrlrun demo [OPTIONS]
Run the five scenarios, in process, with no network.
Options:
--help Show this message and exit.
ctrlrun approve
Usage: ctrlrun approve [OPTIONS] REQUEST_ID
Grant a pending approval request.
Options:
--store-url TEXT The store to open. Default: $CTRLRUN_STORE_URL, else the
SQLite database beside the policy (.ctrlrun/state.db, or
wherever $CTRLRUN_STATE points).
--help Show this message and exit.
ctrlrun deny
Usage: ctrlrun deny [OPTIONS] REQUEST_ID
Refuse a pending approval request.
Options:
--store-url TEXT The store to open. Default: $CTRLRUN_STORE_URL, else the
SQLite database beside the policy (.ctrlrun/state.db, or
wherever $CTRLRUN_STATE points).
--help Show this message and exit.
ctrlrun receipts
Usage: ctrlrun receipts [OPTIONS]
Show the receipts this store holds.
Options:
--last INTEGER RANGE Show only the last N. [x>=1]
--json Print the portable receipt JSON.
--verify-chain Check the receipt chain and report every break by seq
and by name.
--control ID Show only receipts citing this control id (SPEC-v0.6
§7.3).
--store-url TEXT The store to open. Default: $CTRLRUN_STORE_URL, else the
SQLite database beside the policy (.ctrlrun/state.db, or
wherever $CTRLRUN_STATE points).
--help Show this message and exit.
ctrlrun effects
Usage: ctrlrun effects [OPTIONS]
Show the logical effects this store knows about.
Options:
--state [new|reserved|executing|committed|failed|ambiguous]
Show only effects in this state.
--store-url TEXT The store to open. Default:
$CTRLRUN_STORE_URL, else the SQLite database
beside the policy (.ctrlrun/state.db, or
wherever $CTRLRUN_STATE points).
--help Show this message and exit.
ctrlrun resolve
Usage: ctrlrun resolve [OPTIONS] EFFECT_KEY
Say what actually happened to an effect with an unknown outcome.
Options:
--committed The effect did happen at the remote.
--failed The effect provably did not happen.
--store-url TEXT The store to open. Default: $CTRLRUN_STORE_URL, else the
SQLite database beside the policy (.ctrlrun/state.db, or
wherever $CTRLRUN_STATE points).
--help Show this message and exit.
ctrlrun inspect
Usage: ctrlrun inspect [OPTIONS] ACTION_ID
Show one action's whole history: proposal, decision, approval, effect,
receipt.
Options:
--json Emit one JSON object instead.
--store-url TEXT The store to open. Default: $CTRLRUN_STORE_URL, else the
SQLite database beside the policy (.ctrlrun/state.db, or
wherever $CTRLRUN_STATE points).
--help Show this message and exit.
ctrlrun stats
Usage: ctrlrun stats [OPTIONS]
Count what this store's receipts say, from the local store and nothing else.
No network, no aggregation service, no upload: this reads the SQLite file the
process it is diagnosing has been writing (SPEC-v0.3 §6.4).
Options:
--since TEXT Count only receipts finished at or after this: an ISO-8601
timestamp with an offset, or <n>m / <n>h / <n>d.
--json Emit one JSON object instead.
--store-url TEXT The store to open. Default: $CTRLRUN_STORE_URL, else the
SQLite database beside the policy (.ctrlrun/state.db, or
wherever $CTRLRUN_STATE points).
--help Show this message and exit.
ctrlrun verify
Usage: ctrlrun verify [OPTIONS]
Run the declared guarantees against this configuration (SPEC-v0.4).
Every scenario runs against a scratch store created and destroyed for the run.
The store an agent is using is not opened, not read and not created.
Exit codes: 0 every applicable guarantee passed and at least one was
applicable; 1 a guarantee FAILED; 2 the configuration was refused or is
unusable — which includes `mode: observe` and a configuration in which nothing
could be exercised; 3 an internal error in verify itself.
Options:
--authority FILE A standalone authority document, as `ctrlrun gateway
--authority` takes.
--json Emit one ctrlrun.verify/v1 document.
--junit FILE Also write a JUnit XML file for CI.
--only TEXT Comma-separated guarantee ids, e.g. G1,G3.
--store-url TEXT The backend to grade against: 'sqlite' (the default) or a
postgresql:// URL. Verify runs in a scratch store it creates
there and never opens yours.
--help Show this message and exit.
ctrlrun delegate
Usage: ctrlrun delegate [OPTIONS]
Create a delegated grant beneath an existing one.
`--as` is an **assertion**, not an authentication: it supplies the creating
principal for SPEC-v0.3 §5.3 rule 4, and it is free text typed by whoever runs
the command. The record keeps `created_via="cli"` so a reader of the evidence
can tell an act from an assertion. An agent name containing '/' cannot be
written here, because `--as a/b` would otherwise be ambiguous between the
agent `a/b` acting alone and the agent `a` acting for `b`.
Options:
--parent TEXT The grant or delegation being narrowed. [required]
--file FILE A one-grant YAML document, with the keys of SPEC-v0.3 §4.2
minus 'id'. [required]
--as TEXT The delegating principal: AGENT or AGENT/USER. Split on the
first '/'. [required]
--json Emit one JSON object instead.
--help Show this message and exit.
ctrlrun revoke
Usage: ctrlrun revoke [OPTIONS] DELEGATION_ID
Revoke a delegation, and with it every delegation beneath it.
Transitive by structure and not reversible: there is no `unrevoke`, because
the operation whose safety matters is the one taken in a hurry (SPEC-v0.3
§5.7). Revoking an already-revoked delegation is idempotent and exits 0.
Options:
--by TEXT Who revoked it. [default: cli:local]
--help Show this message and exit.
ctrlrun mcp-operator
Usage: ctrlrun mcp-operator [OPTIONS]
Answer approvals from an MCP client, over loopback (SPEC-mcp-operator.md).
There is no --principal and no --allow-remote, and both absences are load-
bearing: a static principal cannot attribute an answer to a person (§3.1), and
a server whose read tools answer without a credential must not be the one that
opens a port (§2.1).
Options:
--listen TEXT HOST:PORT. [default: 127.0.0.1:8901]
--path TEXT The MCP endpoint path. [default: /mcp]
--principal-header TEXT Take the approver's agent from this header,
set by a proxy that authenticates them.
--user-header TEXT Take the approver's name from this header.
Required with --principal-header (SPEC-mcp-
operator §3.2).
--environment TEXT The deployment this console reads. Default:
$CTRLRUN_ENVIRONMENT, else the policy
document, else production (SPEC-v0.3 §2.5).
--max-body-bytes INTEGER [default: 1048576]
--allow-origin TEXT Repeatable.
--authority FILE Load the authority: section from a separate
YAML document (SPEC-v0.3 §8.3).
--identity-jwt Verify a bearer JWT (ctrlrun[identity]).
--identity-jwt-jwks-url TEXT Fetch keys from this JWKS (HTTPS).
--identity-jwt-public-key FILE A PEM public key file.
--identity-jwt-secret-file FILE
Read the HS* shared secret from here. Never a
flag value.
--identity-jwt-algorithms TEXT Repeatable, required. There is no default and
no wildcard.
--identity-jwt-issuer TEXT Matched exactly. Required.
--identity-jwt-audience TEXT Matched by membership. Required.
--identity-jwt-token-type TEXT Required. The token's typ, e.g. at+jwt. Pass
"" for "this issuer sets no typ".
--identity-jwt-header TEXT [default: authorization]
--identity-jwt-agent-claim TEXT
[default: sub]
--identity-jwt-user-claim TEXT Which claim names the human. Required with
--identity-jwt (SPEC-mcp-operator §3.2).
--identity-jwt-claim TEXT Repeatable: which verified claims reach the
receipt. An allow-list.
--identity-jwt-leeway FLOAT [default: 60.0]
--identity-jwt-jwks-min-refresh FLOAT
[default: 30.0]
--identity-jwt-http-timeout FLOAT
[default: 5.0]
--store-url TEXT The store to open. Default:
$CTRLRUN_STORE_URL, else the SQLite database
beside the policy (.ctrlrun/state.db, or
wherever $CTRLRUN_STATE points).
--help Show this message and exit.
ctrlrun gateway
Usage: ctrlrun gateway [OPTIONS]
Front an MCP server, applying this directory's policy to every tools/call.
Options:
--upstream TEXT The MCP server this gateway fronts.
[required]
--alias TEXT Names the upstream in 'mcp.<alias>.<tool>'.
[required]
--listen TEXT HOST:PORT. [default: 127.0.0.1:8900]
--path TEXT The MCP endpoint path. [default: /mcp]
--principal TEXT A fixed agent name, for one tenant.
--principal-header TEXT Take the agent from this header.
--user-header TEXT Take principal.user from this header.
--environment TEXT The deployment this gateway acts in. Default:
$CTRLRUN_ENVIRONMENT, else the policy
document, else production (SPEC-v0.3 §2.5).
--upstream-timeout FLOAT [default: 30.0]
--max-body-bytes INTEGER [default: 1048576]
--allow-origin TEXT Repeatable.
--allow-remote Permit a non-loopback --listen.
--public-url TEXT Where the gateway is reachable, for
respond_to.
--webhook-url TEXT Notify this endpoint on APPROVAL_REQUESTED.
--webhook-secret-file FILE Read the shared secret from here instead of
$CTRLRUN_WEBHOOK_SECRET.
--allow-insecure-webhook Permit an http:// webhook url, loopback only.
--authority FILE Load the authority: section from a separate
YAML document (SPEC-v0.3 §8.3).
--identity-jwt Verify a bearer JWT (ctrlrun[identity]).
--identity-jwt-jwks-url TEXT Fetch keys from this JWKS (HTTPS).
--identity-jwt-public-key FILE A PEM public key file.
--identity-jwt-secret-file FILE
Read the HS* shared secret from here. Never a
flag value: a secret on a command line is in
every process listing on the host.
--identity-jwt-algorithms TEXT Repeatable, required. There is no default and
no wildcard.
--identity-jwt-issuer TEXT Matched exactly. Required.
--identity-jwt-audience TEXT Matched by membership. Required.
--identity-jwt-token-type TEXT Required. The token's typ, e.g. at+jwt. Pass
"" for "this issuer sets no typ".
--identity-jwt-header TEXT [default: authorization]
--identity-jwt-agent-claim TEXT
[default: sub]
--identity-jwt-user-claim TEXT Which claim is principal.user.
--identity-jwt-claim TEXT Repeatable: which verified claims reach the
receipt. An allow-list.
--identity-jwt-leeway FLOAT [default: 60.0]
--identity-jwt-jwks-min-refresh FLOAT
[default: 30.0]
--identity-jwt-http-timeout FLOAT
Bounds the JWKS fetch. Deliberately not
--upstream-timeout: the fetch runs on the
request thread before any decision, so the two
must not be one knob. [default: 5.0]
--otel Export one span per action (ctrlrun[otel]).
--otel-arguments Include argument values as span attributes.
Off by default: arguments carry customer
identifiers and amounts, and a trace backend
is not the receipt store.
--help Show this message and exit.
Next
- Exit codes: what each command’s exit status means.
- Resolve an AMBIGUOUS effect:
effects,resolveandinspectin use. - Get started · Why.