> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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, 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: main [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 every...
  init      Write a starter ctrlrun.yaml and create .ctrlrun/.
  inspect   Show one action's whole history: proposal, decision, approval,...
  receipts  Show the receipts this store holds.
  resolve   Say what actually happened to an effect with an unknown outcome.
  revoke    Revoke a delegation, and with it every delegation beneath it.
  stats     Count what this store's receipts say, from the local store and...
  verify    Run the declared guarantees against this configuration...
```

## ctrlrun init

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

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

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

## ctrlrun demo

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

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

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

## ctrlrun approve

```text theme={null}
Usage: main 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: main 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: main 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: main 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: main 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: main 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: main 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: main 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  Reserved; v0.4 accepts 'sqlite'.
  --help            Show this message and exit.
```

## ctrlrun delegate

```text theme={null}
Usage: main 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: main 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 gateway

```text theme={null}
Usage: main 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](/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)