Use Rehearsal from your coding agent

A coding agent can use Rehearsal through the CLI. It runs your saved tests and reads where a test stopped. Then it fixes your app and runs the same tests again.

The agent works through the CLI and its JSON output, and nothing else. Rehearsal has no MCP server. The CLI cannot create or change tests. You do that in the app, with Re:agent.

What an agent can do #Link to What an agent can do

The agent adds --json to each command except rehearsal connect, which has no JSON form.

You still do three things yourself. You approve the sign-in, you create and change tests in the app, and you decide when a test should change because the page changed on purpose.

Set it up #Link to Set it up

1. 1

   Step 1: Install the CLI and log in

   $ npm install -g @rehearsal-labs/cli$ rehearsal login

   Your agent can sign in for you. It runs rehearsal login --no-browser and gives you the link, and you approve the sign-in in your browser.

2. 2

   Step 2: Point the repository at your project

   $ rehearsal init --workspace <workspace-id> --project parcel

   Say yes when init offers a note for coding agents. It adds the note to AGENTS.md, or to CLAUDE.md when the repository has only that file.

   <!-- rehearsal:start -->## RehearsalThis repository is tested by Rehearsal. The project is parcel.Run `rehearsal help agent-workflow` first. It says what each command takes,what it returns and what every exit status means.<!-- rehearsal:end -->

   If your agent reads its instructions from another file, copy the note there.

3. 3

   Step 3: Start your agent in the repository

   The note sends the agent to rehearsal help agent-workflow. That page is written for agents. It covers signing in, keeping your app connected, finding tests, starting and following runs, reading failures and running again.

Which agents #Link to Which agents

Any agent that can run commands in your terminal can use the CLI, such as Claude Code, Codex, OpenCode or Cursor. In the app, open the project menu and choose Terminal and coding agents. Under Coding agent, the card gives you one sentence to paste:

Run my Rehearsal tests against http://localhost:3000 and fix what fails, starting with `rehearsal help agent-workflow`.

The sentence can be short because the manual carries the steps. From it, your agent learns to sign in, connect your app and run the tests.

An example session #Link to An example session

You tell your agent: "The checkout test fails on my branch. Find out why, fix it, and show me a run that passes." Your app runs on your computer, connected in another terminal. The agent runs:

# Learn the workflow and find the test$ rehearsal help agent-workflow$ rehearsal tests list --json$ rehearsal environments list --app web --json# Run it against the local app and wait$ rehearsal runs start --test <test-id> --environment local \  --idempotency-key fix-checkout-1 --json$ rehearsal runs wait <run-id> --timeout 10m --json# Look at the step where it stopped$ rehearsal runs artifacts download <run-id> --artifact <artifact-id> \  --output ./rehearsal-evidence --json# After the fix, run the same test again and compare$ rehearsal runs rerun <run-id> --idempotency-key fix-checkout-2 --json$ rehearsal runs wait <new-run-id> --timeout 10m --json$ rehearsal runs compare <run-id> <new-run-id> --json

• The first wait exits 1, and data.verdict is failed.
• In data.run.failures, failedStepLabel names the step, such as "Check the order confirmation". expected, error and evidence say what the test wanted, what it met, and which screenshot shows it.
• The agent changes your code. The rerun checks the same test version at the same address.
• The comparison reads fixed for that test, and the second wait exits 0.

JSON output shows the whole answer of a failed run.

Before your agent starts runs #Link to Before your agent starts runs

• Each run your agent starts counts towards your plan, like any other run.
• Ask it to keep one key for each run it means to start. Repeating a request with the same key never starts a second run.
• When the CLI answers AUTH_REQUIRED, the agent needs you. It runs rehearsal login --no-browser in the background and gives you the link to approve.
• For each failure, the agent should tell you the step, what it expected and what the page showed. A test that looks wrong comes to you.

What the CLI does not do #Link to What the CLI does not do

• It has no MCP server. Agents use the commands and their JSON.
• It cannot create, edit or approve tests.
• Signing in needs a person with a browser.
• rehearsal connect holds its terminal open and has no JSON form. Your agent runs it in the background and leaves it running while the tests run.

Next steps #Link to Next steps

• Run tests from the terminal yourself first, to see what your agent sees.
• Read the Command reference for every flag.