Run tests from the terminal

The CLI runs the tests you saved in Rehearsal. The tests run on Rehearsal's servers, and the terminal follows them. You create and change tests in the app, with Re:agent.

You need the CLI signed in. Starting a run needs Manage projects. Reading runs needs View projects.

Choose a project once #Link to Choose a project once

Most commands work inside one workspace and one project. Save both in your repository, so you do not type them each time.

$ rehearsal workspaces list$ rehearsal projects list --workspace <workspace-id>$ rehearsal init --workspace <workspace-id> --project parcel

init writes rehearsal.config.json in the current folder. It holds identifiers and the project's slug, never a sign-in.

{  "schemaVersion": 1,  "workspaceId": "2f6e1c7a-8d4b-4e0a-9c55-3b1f0d7e6a21",  "projectId": "parcel"}

• Commands read the file from the current folder or any folder above it, up to the repository root.
• A flag, such as --project, wins over the file for that one command.
• rehearsal context show prints what is in use and where each value came from.
• init also offers to add a short note to AGENTS.md, so a coding agent knows this repository uses Rehearsal.

Find the tests #Link to Find the tests

$ rehearsal tests list$ rehearsal suites list

Each test shows its status and its readiness. Readiness says what a run would do with the test today. Only a ready test gets checked. The run lists any other test it was given as not ready.

Start a run #Link to Start a run

Rehearsal never picks the tests for you. Name them in one of three ways:

# Some tests, up to 200$ rehearsal runs start --test <test-id> --test <test-id># One suite$ rehearsal runs start --suite <suite-id># Every approved test of one app$ rehearsal runs start --app web

--test and --suite take identifiers from the lists above. --app also takes the app's name or the host of one of its addresses.

Run #42 is queued with 2 tests.Identifier  7c1f0a9e-3b52-4d18-a6e4-5f2d9b8c0e13Report      https://app.rehearsal.dev/parcel/projects/0b8d4e6f-1a2c-4f3e-9d7b-6c5a4e3f2d1b/results/42Key         9b4e1d7c-2a6f-4c8e-b3d5-7f1a9c2e4b6d  Wait for a verdict: rehearsal runs wait 7c1f0a9e-3b52-4d18-a6e4-5f2d9b8c0e13 --timeout 60s --json

The command returns as soon as Rehearsal records the run. A queued run has not passed anything yet, so wait for it.

Choose where each app runs #Link to Choose where each app runs

Each app in a run is tested at one address. An app with one address needs nothing. For an app with several, name one with --environment:

$ rehearsal environments list --app web$ rehearsal runs start --app web --environment staging

--environment takes a kind, such as production, staging, preview or local. It also takes a computer's name or an address identifier. Repeat it once for each app in the run.

• Leave it out for an app with several addresses, and nothing starts. The CLI answers SELECTION_REQUIRED and lists the addresses to choose from.
• Name a local address that nothing is connected to, and nothing starts. The CLI answers ENVIRONMENT_OFFLINE. Connect the app first.

Ask again safely #Link to Ask again safely

Each run request carries a key. In a terminal, the CLI makes one for you. Before it sends the request, it prints the arguments that repeat it with the same key.

From a script, or with --json, pass your own key with --idempotency-key. Use 8 to 200 characters, such as a build number.

$ rehearsal runs start --suite <suite-id> --idempotency-key build-1842 --json

Wait for the result #Link to Wait for the result

$ rehearsal runs wait 42 --timeout 10m

A run is named by its identifier or by the number the app shows. runs wait checks the run until it ends or the time is up. It waits 60 seconds unless you say otherwise, and 1 hour at most.

Run #42 failed: a test failedIdentifier        7c1f0a9e-3b52-4d18-a6e4-5f2d9b8c0e13Address           https://parcel.example.comSelected          2Passed            1Failed            1Needs review      0Without a result  0Time in tests     38sStarted           2026-09-23T10:14:05.000ZFinished          2026-09-23T10:15:02.000ZReport            https://app.rehearsal.dev/parcel/projects/0b8d4e6f-1a2c-4f3e-9d7b-6c5a4e3f2d1b/results/42What failed  Check out a cart (5b0e2c4d-7f91-4a3b-8e6d-2c1f0a9b8e77)    step 4: Check the order confirmation    expected: The confirmation page shows an order number.    saw: expect(locator).toBeVisible() failed Locator: getByRole('heading', { name: 'Order confirmed' }) Expected: visible Timeo…    error: expect(locator).toBeVisible() failed Locator: getByRole('heading', { name: 'Order confirmed' }) Expected: visible Timeout: 10000ms Error: element(s) not found    screenshot of the step 4: 1f9c3e5a-7b2d-4f6e-8a0c-2d4f6b8e0a1c    video of the whole test: 6e8a0c2e-4f6b-4d8f-a0c2-e4f6b8d0a2c4    trace of the whole test: 4b6d8f0a-2c4e-4a6b-9d8f-0a2c4e6b8d0f

Below that, the CLI prints the commands that list and download the evidence.

The exit status says how the run ended: 0 when every selected test passed, 1 when a test failed. A script can stop on anything but 0. JSON output lists every code.

Read a run #Link to Read a run

$ rehearsal runs list --status failed$ rehearsal runs get 42$ rehearsal runs open 42

runs get prints the run as it stands. runs open opens the same run in the app, in your browser.

Download evidence #Link to Download evidence

$ rehearsal runs artifacts list 42$ rehearsal runs artifacts download 42 --artifact <artifact-id> --output ./evidence

• A run keeps screenshots of each test's steps, a video and a Playwright trace.
• --output takes a folder or a file name. In a folder, the file keeps its own name.
• The CLI replaces a file that is already there only with --force.

Open a trace with Playwright to step through the test: npx playwright show-trace trace.zip.

Run again and compare #Link to Run again and compare

$ rehearsal runs rerun 42$ rehearsal runs compare 42 43

Run #42 failed against run #43 passedfixed  Check out a cart       5b0e2c4d-7f91-4a3b-8e6d-2c1f0a9b8e77  failed to passedsame   Apply a discount code  8e7d6c5b-4a39-4281-9f0e-d1c2b3a4f5e6  passed to passed

• runs rerun runs the same test versions again, at the same addresses. To test somewhere else, start a new run instead.
• runs compare lines up the tests of two runs, oldest first. A test reads fixed only if it failed before, passes now, and ran the same version at the same address.

Next steps #Link to Next steps

• Read the JSON output to use these commands from a script.
• Let your coding agent run the tests and read the failures.
• See every flag in the Command reference.