> ## Documentation Index
> Fetch the complete documentation index at: https://ctrlrun.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Every ctrlrun command and option, from the command's own help text: init, demo, approve, deny, receipts, effects, resolve, inspect, stats, scan, verify.

The `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

```text theme={null}
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.
  scan          Report the consequential call sites and policy entries...
  stats         Count what this store's receipts say, from the local store...
  verify        Run the declared guarantees against this configuration...
```

## ctrlrun init

```text theme={null}
Usage: ctrlrun init [OPTIONS]

  Write a starter ctrlrun.yaml and create .ctrlrun/.

Options:
  --help  Show this message and exit.
```

## ctrlrun demo

```text theme={null}
Usage: ctrlrun demo [OPTIONS]

  Run the five scenarios, in process, with no network.

Options:
  --help  Show this message and exit.
```

## ctrlrun approve

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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.
```

## ctrlrun scan

```text theme={null}
Usage: ctrlrun scan [OPTIONS]

  Report the consequential call sites and policy entries nothing is covering.

  Reads Python source and a policy document as text. It never imports the tree,
  never builds an action, never resolves a principal and never opens a store
  (SPEC-scan §2.1, §9.2).

  It is a finder and not a proof. Every run prints what it could not look at,
  and a clean scan means nothing was found where it looked.

  Exit codes: 0 nothing was found; 1 something was, including a suppressed
  finding or a call whose name could not be resolved; 2 the scan could not run.

Options:
  --path DIRECTORY   The tree to read. Defaults to the working directory.
  --policy FILE      The policy to read. Defaults to ctrlrun.yaml beside the
                     tree, if there is one.
  --exclude TEXT     A glob, relative to the tree, not to read. Repeatable.
  --vocabulary TEXT  A file of verbs, one per line, replacing the built-in list.
                     With no value, print the list in force and exit.
  --json             Emit one ctrlrun.scan/v1 document.
  --help             Show this message and exit.
```

## Next

* [Exit codes](/reference/exit-codes): what each command's exit status means.
* [Resolve an AMBIGUOUS effect](/guides/resolve-an-ambiguous-effect): `effects`, `resolve` and `inspect` in use.
* [Get started](/get-started/quickstart) · [Why](/why).


## Related topics

- [Python API](/reference/api/index.md)
- [Exit codes](/reference/exit-codes.md)
- [Authority YAML reference](/reference/authority-yaml.md)
- [banner](/reference/api/banner.md)
- [Decision](/reference/api/Decision.md)