---
title: CLI overview and exit codes
description: Every reeval command, the flags they share, run references and exit codes.
---
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reeval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

The `reeval` CLI ships with the package. Run it with `npx reeval`, or `pnpm reeval` in a pnpm project.
Once installed, `re` is the same command, for typing; `npx re` fetches an unrelated package, so
scripts and docs say `reeval`.

```bash
npx reeval run --dry-run
```

## Commands

| Command | What it does | Page |
|---|---|---|
| `reeval init [dir]` | Scaffold a config, an environment, an eval in it and profiles | [reeval init](/reference/cli/init) |
| `reeval doctor` | Check Node, the config, Docker, images, keys, egress and `.gitignore` | [reeval doctor](/reference/cli/doctor) |
| `reeval run [filter...]` | Plan and run evals | [reeval run](/reference/cli/run) |
| `reeval record [run...]` | Copy scratch runs into the history folder | [reeval record](/reference/cli/record) |
| `reeval history`, `reeval show`, `reeval compare`, `reeval checkout` | Read and compare recorded runs | [reeval history, show, compare](/reference/cli/history) |
| `reeval query [sql \| view]` | Read-only SQL across runs | [reeval query](/reference/cli/query) |
| `reeval mcp` | Serve the history to other agents over MCP | [reeval mcp](/reference/cli/mcp) |
| `reeval studio`, `reeval studio build` | The web studio, live or as a static site | [reeval studio](/reference/cli/studio) |
| `reeval image build`, `reeval clean` | Build sandbox images; remove local debug data | [reeval image build, reeval clean](/reference/cli/image-clean) |
| `reeval report [run]` | Collect a redacted bug report, then file it as an issue | [reeval report](/reference/cli/report) |

`reeval --help` prints the full help and exits 0; `reeval <command> --help` prints that command's. `reeval` with no command prints it and exits 2. `reeval --version` prints the version.

A command takes only its own flags, after its name, plus the shared flags below anywhere. Another command's flag, a missing value or an extra argument exits 2:

```text
reeval: --port isn't an option of reeval run. Run reeval --help.
reeval: reeval show takes at most 1 argument (got latest extra)
```

## Shared flags

<Property name="--config" type="string" optional>
  The config file every command reads, relative to the current directory. Without it, reeval uses the nearest `reeval.config.ts` (or `.mts`, `.cts`, `.js`, `.mjs`, `.cjs`, or a `reeval.yaml` or `reeval.yml`) in the current directory or above: see [Loading](/reference/config#loading). An explicit path that doesn't exist fails with `Config file not found`. `reeval run` and `reeval image build` fail if none is found (`No reeval.config.ts … here or above. Run reeval init.`); other commands then use their defaults in the current directory.

  The file can live outside your project, such as `/tmp/reeval.images.config.ts`. Its imports of `{{ pkg }}` and its subpaths resolve to the reeval that runs it, so it needs no `node_modules` beside it. Its directory is still the project root: `include`, relative paths, `.env.local` and `.reeval/` resolve against it.
</Property>

<Property name="-h, --help" type="boolean" optional>
  Print the help and exit 0. After a command, it prints only that command's help: `reeval image build --help` shows the `image build` block and the shared options. `reeval image --help` lists its subcommands.
</Property>

[//]: # (generated:cli-help:footer)

```text
Runs are latest, latest~N, a run id (or unique prefix), or a git SHA prefix.
Options: --config <path> (default: the nearest reeval.config.ts, or .mts, .cts, .js, .mjs, .cjs,
or reeval.yaml, in the current directory or above)
Exit codes: 0 passed, 1 failed, 2 usage/config error, 3 infra error, 130 interrupted (Ctrl-C),
143 terminated (SIGTERM)
```

[//]: # (/generated:cli-help:footer)

## Run references

| Reference | Means |
|---|---|
| `latest` | The newest run (the default) |
| `latest~N` | N runs before the newest |
| `20260926T170558Z_bd6205e_ada-lovelace_sycz` | A full run id |
| `20260926T1705` | A unique prefix of a run id |
| `bd6205e` | A git SHA prefix of 4+ characters: the newest run at that commit |

Commands that take a `[run]` accept any of these, and search recorded runs and unrecorded scratch runs.

`reeval run --resume` is different: omitted and `latest` mean the newest **resumable** run (Stopped staging, or an `interrupted` or `budget` scratch), not assembled `latest`. See [Resume a stopped run](/reference/cli/run#resume-a-stopped-run).

A run id is `<UTC start>_<short sha>_<author>_<random>`. The author is `git config user.name` as a slug, or `ci` in CI.

## Exit codes

[//]: # (generated:exit-codes)

| Code | Name |
|---|---|
| 0 | `ok` |
| 1 | `failed` |
| 2 | `usage` |
| 3 | `infra` |
| 130 | `interrupted` |
| 143 | `terminated` |

[//]: # (/generated:exit-codes)

| Code | When |
|---|---|
| 0 | Every gated cell passed. Failing controls under `compare.gate: 'variants'` don't count. Also `--dry-run`, and `reeval compare` without `--fail-on-regression`. |
| 1 | A gated attempt failed, an error happened outside any attempt (an eval file's stray rejection, a worker that died), `reeval doctor` found a problem, a variant fell below its `minLift`, `budget.duration` stopped the run, or `reeval compare --fail-on-regression` found a regression, or a failing new or can't-compare eval. |
| 2 | A usage, config or credentials error. That includes an unknown command, flag, option or profile, a filter or tag that matches no eval, a plan over `budget.attempts` without `--force`, `.only` in CI, Docker not running, a missing image, a bad run reference and a refused record. None of these writes a run. |
| 3 | An infrastructure error (sandbox, harness or setup step) and no failures. A run with both a failure and an infra error exits 1. Also an error nothing caught, in reeval or in code your config runs: reeval prints `reeval: <message>`, with secrets masked, and stops without writing a run. Either way reeval suggests [`reeval report`](/reference/cli/report) on stderr. |
| 130 | Interrupted with Ctrl-C (`SIGINT`). Sandboxes are destroyed and the run is saved as `interrupted`. A second signal forces the exit. |
| 143 | Terminated with `SIGTERM` (`docker stop`, a cancelled CI job), the conventional 128 + 15. Otherwise the same as 130: sandboxes are destroyed, the run is saved as `interrupted`, and a second signal forces the exit. |

A real exit 2, from a filter that matches nothing:

```text
reeval: No evals matched evals/hello.eval.ts, evals/preferences.eval.ts, evals/skill.eval.ts with filter "nope"
```

## Related

- [Environment variables](/reference/env-vars): the variables that stand in for flags
- [Errors](/reference/errors): common messages and their fixes
- [Output modes](/concepts/output): what `reeval run` prints and when