> ## 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.

# Exit codes

> What each ctrlrun command's exit status means: 0 done, 1 a refusal or a failed guarantee, 2 a usage error or an unusable configuration.

Every `ctrlrun` command exits 0 when it did what it was asked, 1 when CTRLRun refused
(a `CTRLRunError`, printed as one line), and 2 on a usage error. `ctrlrun verify` adds a third
code for its own failure, because a verifier that crashed must not look like one that refused.

## Every command

| Code | Meaning                                   | Examples                                                                                                                                                                                    |
| ---- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`  | the command did what it was asked         | a grant written, a receipt printed, a revocation applied (revoking an already-revoked delegation is idempotent and exits 0)                                                                 |
| `1`  | CTRLRun refused, and said why on one line | `resolve` on an effect that is not `AMBIGUOUS`; `approve` on a request that expired; `delegate` beyond the parent's grant; a `--store-url` naming a database this binary does not recognise |
| `2`  | the command line was wrong                | a missing argument, an unknown option, `resolve` without exactly one of `--committed` and `--failed`                                                                                        |

A refusal is the command's exit code and its last line. Nothing is retried on the operator's
behalf and nothing is written on a refusal.

## `ctrlrun verify`

| Code | Meaning                                                                                                                               |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `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                                                                                                    |

Not applicable never changes the code by itself, and zero applicable guarantees is exit 2, never
0: `0/0` reported as success is the same false green as `8/8` with five N/As. A partial run
(`--only`) writes no badge. The GitHub Action fails the job on any code but 0 and carries the
code through as an output.

## `ctrlrun gateway`

The gateway runs until it is stopped. It exits 2 before listening when its configuration is
refused: a non-loopback `--listen` without `--allow-remote`, an `http://` webhook without
`--allow-insecure-webhook`, a JWT option set without the identity extra, or a policy that will
not load.

## Next

* [CLI reference](/reference/cli).
* [Errors](/reference/errors): the exception behind each exit 1.
* [Verify in CI](/guides/verify-in-ci) · [Get started](/get-started/quickstart) · [Why](/why).


## Related topics

- [ctrlrun verify](/verify.md)
- [CLI reference](/reference/cli.md)
- [Verify in CI](/guides/verify-in-ci.md)
- [Run verify in GitHub Actions](/cookbook/verify-in-github-actions.md)
- [Roadmap](/ROADMAP.md)