# Command line

> Choose commands and flags to set up, run and inspect your tests.

Source: https://rehearsal.dev/retest/docs/reference/cli

Use the command line to prepare your project, choose tests and read a saved run. This page lists every command and flag; [Running tests](https://rehearsal.dev/retest/docs/essentials/running-tests.md) explains the usual workflow.

## Commands

| Command | What it does |
| --- | --- |
| `retest init [options]` | Write a config, example test and test tsconfig. |
| `retest doctor [options]` | Check the configured targets, app servers and environment secrets. |
| `retest install <engine...>` | Install the named pinned builds. |
| `retest install --list [options]` | List pinned builds and their local cache state. |
| `retest licences [engine]` | List builds with licence notices, or print one engine's notices. |
| `retest list [files...] [options]` | Load test declarations without opening a browser. |
| `retest run [files...] [options]` | Run selected tests and write a new run folder. |
| `retest inspect <run-folder> [options]` | Read results and steps without running tests again. |
| `retest report <run-folder>` | Write or replace the folder's HTML report. |
| `retest help [command]` | Show general help or the named command's help. |

`retest --help` and `retest -h` show general help. Add either flag after a command for its help. `retest --version` and `retest -v` print the installed version. Calling `retest` without a command prints help and exits 2.

Value options accept `--name value` or `--name=value`. Flags take no value. Unknown options, missing values and repeated options are errors, except where a table explicitly allows repetition.

## Create a project

`init` writes the starter files, adds test scripts to `package.json` and adds `.retest/` to `.gitignore`. It leaves existing starter files in place and prints an install command without installing packages.

```sh
npx retest init --app web=http://localhost:3000 --browser chrome --yes
```

This chooses the app and browser without questions. Without a terminal, or when a coding agent is detected, `init` needs `--app` or `--yes`; otherwise it exits 2 and writes nothing. An existing config skips the questions.

| Option | Meaning and default |
| --- | --- |
| `--app <name=url>` | App name and base URL. The defaults are web and http://localhost:3000. |
| `--start <command>` | App startup command. A detected dev or start script is offered interactively, or accepted with --yes. |
| `--browser <name>` | chromium, chrome or edge. Otherwise use the first available Chrome, Edge or Chromium, falling back to Chrome. |
| `--ci github` | Also write a GitHub Actions workflow. No workflow by default. |
| `--yes` | Use defaults for unanswered questions. |

## Check the setup

`retest doctor` loads the config, checks environment secrets and app readiness, and starts and stops configured app servers when needed. It launches and closes only Chromium-family browser targets. Firefox and WebKit are checked from their files; Electron's executable and app are checked without starting them. Native targets receive prerequisite checks. No test runs and nothing is downloaded.

| Option | Meaning and default |
| --- | --- |
| `--config <path>` | Config file, defaulting to retest.config.ts in the working directory. |

## Install pinned builds

`install` accepts chromium, firefox, webkit, electron, webdriveragent, mac2 and media. The native executor names are webdriveragent for iOS and mac2 for macOS. Available pins depend on the machine; use the list command before requesting a build.

```sh
npx retest install --list
npx retest install chromium
```

The second command downloads Chromium. Native executors build from local checkouts at pinned commits. The media process builds from the shipped Rust crate and needs Rust 1.88 or later and ffmpeg. [Browsers](https://rehearsal.dev/retest/docs/platforms/browsers.md) lists supported browser builds.

| Option | Meaning |
| --- | --- |
| `--list` | Inspect pins and the cache without downloading. Takes no engine names. |
| `--verify` | With --list, verify the files of installed builds. |
| `--json` | With --list, print one JSON document. |
| `--media-binary <path>` | For install media alone, use a prebuilt binary only if its exact build has a pinned checksum. |
| `--media-mirror <url>` | For install media alone, fetch a pinned prebuilt binary from this mirror. Checksums still apply. |
| `--offline` | For install media alone, build with cargo --offline using cached pinned crates. |

No prebuilt media binary has a pinned checksum in this release, so `--media-binary` and `--media-mirror` currently refuse the request. Use the source build with `retest install media`.

`RETEST_DOWNLOAD_MIRROR` chooses a mirror for pinned browser downloads. It preserves checksum checks and refuses credentials, queries or fragments in the mirror address. `retest licences [engine]` reads local or bundled licence notices and downloads nothing; it has no command-specific flags.

## Choose tests

`run` and `list` share the following selection options. With a config and no files, they discover `.retest.ts` files under the working directory. Without a config, name the files explicitly.

| Option | What it selects |
| --- | --- |
| `--config <path>` | Use this config instead of retest.config.ts in the working directory. |
| `--grep <text>` | Full titles containing the text, or matching /pattern/flags. The g and y regular expression flags are refused. |
| `--tag <expression>` | Tags combined with and, or, not and parentheses. |
| `--target <app=name>` | Tests using this app target. Repeat for other apps. Requires a config. |
| `--last-failed` | Variants the last run did not pass, read from .retest/last-run.json. |
| `file:line` | The test, group or parameterised test declared on that line. |
| `file:line#row` | One row of test.for, numbered from 1. |

```sh
npx retest list --tag "smoke and not slow"
npx retest run tests/task.retest.ts --grep "saves a task"
```

Filters combine, so a test must match each one. Required setups still run. `test.only` narrows the run before these filters; `list` shows both focused and unfocused declarations. `run` exits 2 when it selects nothing or only skipped tests. `list` can list skipped declarations successfully.

## Run tests

`retest run` uses the selected config and writes `.retest/runs/<time>` unless you choose an output folder. Its additional options control the runtime and report.

| Option | Meaning and default |
| --- | --- |
| `--browser <path>` | Chromium or Chrome executable for a run without a config. Refused beside --config or an existing default config. |
| `--base-url <url>` | A plain URL replaces the default app's base URL. With a config, app=url replaces a named app's URL; repeat for other apps. |
| `--reporter <name>` | human, agent, jsonl or html. Defaults to human, or agent when a coding agent is detected. |
| `--output <dir>` | New or empty run folder. Default: .retest/runs/\<time>. A non-empty folder is refused. |
| `--timeouts <list>` | Override budgets as name=milliseconds pairs separated by commas. |
| `--workers <n>` | Files running at once. Default: half the available cores, rounded down, at least 1. |
| `--browsers <n>` | Browser processes per target. Default: one per three active workers, rounded up, bounded by the target's work. |
| `--playwright` | Resolve @playwright/test to Retest's compatibility API. Without files, discover .spec files. |
| `--allow-only` | Allow focused tests when the CI environment would otherwise refuse them. |
| `--update-screenshots` | Write each compared screenshot baseline and pass those comparisons. The report counts baselines written. |
| `--headed` | Request visible browser windows. This mode has not been verified. |
| `--agent` | Choose the coding-agent report. |
| `--no-agent` | Disable automatic coding-agent reporting. |

`human` prints the terminal report; `agent` prints a shorter report with commands to investigate. `jsonl` writes only event lines to stdout. `html` prints the human report and writes `report.html` when the run ends. Conflicting reporter flags are refused.

Budget defaults in milliseconds are collection 10000, setup 60000, action 10000, navigation 30000, assertion 5000, test 60000 and cleanup 10000. [Configuration options](https://rehearsal.dev/retest/docs/reference/config.md) explains their scope. Recording is configured in the file; there is no recording flag.

## List declarations

`retest list` takes the shared selection options and `--json`. It prints source lines, tags, locks, apps and target variants without starting a browser. JSON output is one document with `schemaVersion: 1` and `files`; it has no published JSON Schema.

## Read a saved run

`inspect` reads one run folder. When `result.json` is missing, it reconstructs an incomplete result from the events. Its exit code describes whether it could read the folder, rather than whether the recorded tests passed.

| Option | Meaning |
| --- | --- |
| `--json` | Print the run result, or a test report when --test is present. |
| `--test <id>` | Show one test's steps and evidence. Use its full id, including file and group names. |
| `--target <app=name>` | With --test, choose one recorded variant. Repeat for other apps. |

```sh
npx retest inspect .retest/runs/<time> --test "tests/task.retest.ts > saves a task" --json
npx retest report .retest/runs/<time>
```

The first command returns that test, its events and available diagnostics. The second writes a portable `report.html` from the saved run, replacing an earlier report. `report` has no command-specific flags.

## Exit codes

For `run`, 0 means the selected work passed, 1 means a test failed, 2 means the run could not check everything, and 130 or 143 means interruption. See [Results and exit codes](https://rehearsal.dev/retest/docs/reference/results.md) for precedence and mixed results. Other commands return 0 on success and 2 when they cannot complete their task. `init`, `doctor`, `install` and `list` can also return 130 or 143 when interrupted.

## Next steps

- [Configuration options](https://rehearsal.dev/retest/docs/reference/config.md): Look up targets, budgets and evidence settings.
- [Results and exit codes](https://rehearsal.dev/retest/docs/reference/results.md): Interpret test outcomes and command failures.
- [Run folder and events](https://rehearsal.dev/retest/docs/reference/run-folder.md): Read the files and event records a run leaves.