CLI

The rehearsal command does everything the console does, from a terminal or a script. It is part of the rehearsal-kit package. Commands print JSON, so you can pass the output to other tools.

pip install rehearsal-kit
rehearsal login

Without an installation, run any command through uvx: uvx --from rehearsal-kit rehearsal login.

The CLI uses the server and key that rehearsal login saved. The environment variables REHEARSAL_URL and REHEARSAL_API_KEY take precedence, which is what a CI job uses. When a command fails, the CLI prints the server's message and a hint: see Errors.

All commandsCopy Anchor Link

Start

Applications and worlds

Agents and evaluations

Data

AI assistants

Run your own server

Coming soon

Two options work everywhere: rehearsal --version prints the installed version, and --help after any command prints its arguments.

StartCopy Anchor Link

rehearsal loginCopy Anchor Link

Sign in: approve this terminal in your browser, or paste an API key.

The terminal shows a confirmation code and opens the console. Check that the browser shows the same code, then choose Approve. The terminal receives a key with "Build and evaluate" access and saves it for your user only. See Sign in and keys.

rehearsal login [--url <url>] [--with-key] [--no-browser]

rehearsal login --url https://rehearsal.example.com

Signing in to Rehearsal at https://rehearsal.example.com

Approve this sign-in in your browser:
  https://rehearsal.example.com/app/cli-login/?code=ZKCZ-BVBS

Confirmation code: ZKCZ-BVBS  (the browser shows the same code)

Waiting for approval (Ctrl+C to cancel)....

✓ Signed in to Acme (project default) at https://rehearsal.example.com.
  Saved to ~/.config/rehearsal/config.json (readable by you only). The CLI, the Python SDK and the MCP server use it.
  Next: rehearsal worlds list

rehearsal login --url https://rehearsal.example.com --with-key

With --with-key the terminal asks for a key and hides what you paste. Use it on a server or in CI, where no browser is at hand.

rehearsal whoamiCopy Anchor Link

Show the server, workspace and key this machine uses.

The key is shown by its prefix only.

rehearsal whoami

rehearsal whoami

Server:     https://rehearsal.example.com
Workspace:  Acme (project default)
Key:        rh_1a2b3c4d_…  access: write, evaluator
Signed in:  saved sign-in (~/.config/rehearsal/config.json)

rehearsal logoutCopy Anchor Link

Forget the saved sign-in on this machine.

This removes the saved key from this machine only. To disable the key everywhere, revoke it on the console's API keys page.

rehearsal logout

rehearsal logout

Signed out. The saved key is removed from this machine; revoke it on the console's API keys page to disable it everywhere.

Applications and worldsCopy Anchor Link

rehearsal appsCopy Anchor Link

Add, list and upload applications.

Arguments of rehearsal apps add:

Arguments of rehearsal apps upload:

rehearsal apps add helpdesk --git https://github.com/you/app --commit 0123456789abcdef0123456789abcdef01234567 --image app=you/app:1.4@sha256:<digest> --policies-file policies.txt

{
  "id": "app_da77a395b6852c5e",
  "project_id": "prj_7f4a9532b99af3d2",
  "name": "helpdesk",
  "connection_mode": "source",
  "source": {
    "kind": "git",
    "url": "https://github.com/you/app",
    "commit": "0123456789abcdef0123456789abcdef01234567"
  },
  "images": {
    "app": "you/app:1.4@sha256:..."
  },
  "policies": "...",
  "notes": "",
  "created_at": "2026-10-10T20:49:54.962887+00:00",
  "removed_at": null
}

rehearsal apps list

[
  {
    "id": "app_e184a0bb1120d4ce",
    "name": "gitea",
    "source": {
      "ref": "v28.1.0",
      "url": "https://github.com/go-gitea/gitea",
      "kind": "git",
      "commit": "4ebd5e319b6a9e629bfd7a04292a6fe85b08dee9"
    },
    "notes": "split=development; domain=code collaboration / issue tracking; license=MIT"
  }
]

rehearsal buildCopy Anchor Link

Compile an application into a world.

A build spends model budget and takes 1 to 3 hours. See Build a practice world.

rehearsal build <app_id> [--model <model>] [--budget <budget>] [--scenarios <scenarios>] [--watch]

rehearsal build <app_id> --budget 6 --watch

The command prints job_id, world_id, world_version_id and version, then one line for each event: the time, the event type and a summary.

rehearsal worldsCopy Anchor Link

List practice worlds, their jobs, re-checks and bundles.

validate spends model budget: it tries each job once with a live agent.

Arguments of rehearsal worlds bundle:

rehearsal worlds list

A workspace with no world prints []. Each world has a name, its application_id and its versions; each version has an id, a version number and a status.

rehearsal worlds scenarios <wv_id>

Each job is printed with its id, slug, family, split and status.

rehearsal jobsCopy Anchor Link

Follow and control builds and other long jobs.

retry restarts a failed or stopped job from its last saved step. Finished steps are not repeated.

rehearsal jobs show <job_id>

rehearsal jobs retry <job_id>

Agents and evaluationsCopy Anchor Link

rehearsal profilesCopy Anchor Link

List and create agent profiles (agent versions).

Arguments of rehearsal profiles create:

rehearsal profiles create support-agent --prompt-file instructions.txt

{
  "id": "prof_7f37a04a339513ca",
  "project_id": "prj_7f4a9532b99af3d2",
  "name": "support-agent",
  "version": 1,
  "spec": {
    "name": "support-agent",
    "version": 1,
    "driver": "llm",
    "system_prompt": "...",
    "tool_guidance": {},
    "model": null,
    "temperature": 0.2,
    "max_turns_per_actor": 25
  },
  "parent_id": null,
  "created_by": "user",
  "rationale": "",
  "created_at": "2026-10-10T20:49:24.980272+00:00"
}

rehearsal profiles list

Each profile is printed with its id, name, version and created_by.

rehearsal evalCopy Anchor Link

Evaluate agent profiles on a world version.

An evaluation spends model budget for each episode. Without --split or --repeats, every approved job runs twice. See Evaluate an agent.

rehearsal eval <wv_id> --profile <profile>... [--split <split>]... [--repeats <repeats>] [--budget <budget>] [--watch]

rehearsal eval <wv_id> --profile <profile_id> --split dev --repeats 2 --watch

The command prints run_id, job_id, episodes and shards, then one line for each event, then the summary of the run. Use Rehearsal in CI shows the summary's shape.

rehearsal runsCopy Anchor Link

Follow runs and read their episodes.

rehearsal runs episodes <run_id>

Each episode is printed with its id, scenario, split, profile, status, reward and termination.

rehearsal runs episode <episode_id>

rehearsal runs show run_doesnotexist

Error (404): Run run_doesnotexist not found
Check the id: list what exists with 'rehearsal apps list', 'worlds list', 'profiles list' or 'runs show'.

rehearsal compareCopy Anchor Link

Compare agents within a run, or two runs on one world version.

rehearsal compare <run_a> [<run_b>]

rehearsal compare <run_a> <run_b>

rehearsal improveCopy Anchor Link

Propose a revised agent profile from train/dev failures.

This spends a small amount of model budget. It reads only failed train and dev episodes. See Improve an agent.

rehearsal improve <profile_id> <run_id>

rehearsal improve <profile_id> <run_id>

The command prints a job_id. Follow it with rehearsal jobs show <job_id>.

DataCopy Anchor Link

rehearsal exportCopy Anchor Link

Export verified trajectories as a dataset.

rehearsal export <run_ids>... [--split <split>]...

rehearsal export <run_id> --split train

The command prints a job. The dataset then appears in rehearsal artifacts list.

rehearsal artifactsCopy Anchor Link

List and download exported files.

Arguments of rehearsal artifacts download:

rehearsal artifacts list

rehearsal artifacts download <artifact_id> dataset.jsonl

rehearsal export-exampleCopy Anchor Link

Write examples/<app>/ from a published world version and its runs.

rehearsal export-example <wv_id>

rehearsal export-example <wv_id>

rehearsal export-replayCopy Anchor Link

Save a job's or run's recorded events (already redacted) as a replay file.

rehearsal export-replay <stream> <dest> [--episode <episode>]

rehearsal export-replay <run_id> replay.json

AI assistantsCopy Anchor Link

rehearsal mcpCopy Anchor Link

Run the MCP server for AI assistants (stdio; uses your rehearsal login).

AI assistants start this command themselves. See AI assistants.

rehearsal mcp

rehearsal mcp

The server talks over standard input and output, so it prints nothing in a terminal. It needs the mcp extra: pip install 'rehearsal-kit[mcp]'.

rehearsal skillCopy Anchor Link

Install the Rehearsal skill for Claude Code and other agents.

rehearsal skill <action> [--dir <dir>]

rehearsal skill install --dir ~/.claude/skills

Run your own serverCopy Anchor Link

These commands run on the server, not against it. They need the server extra: pip install 'rehearsal-kit[server]'.

rehearsal serveCopy Anchor Link

Self-hosted only Run the API and console.

rehearsal serve [--host <host>] [--port <port>]

rehearsal serve --host 127.0.0.1 --port 7800

Rehearsal API on http://127.0.0.1:7800, database 127.0.0.1

rehearsal workerCopy Anchor Link

Self-hosted only Run a job worker.

Builds and evaluations run only while a worker is running. See Install with Docker Compose.

rehearsal worker [--kinds <kinds>] [--once]

rehearsal worker --kinds world_build

Without --kinds, the worker takes every kind of work: world_build, world_validate, evaluation, improvement, dataset_export and bundle_export.

rehearsal upCopy Anchor Link

Self-hosted only Apply database migrations; starts a local database in Docker only when no cloud database is set.

On a server whose REHEARSAL_DATABASE_URL points at another machine, this only applies migrations.

rehearsal up

rehearsal up

rehearsal migrateCopy Anchor Link

Self-hosted only Apply database migrations.

rehearsal migrate

rehearsal migrate

rehearsal bootstrapCopy Anchor Link

Self-hosted only Create an organisation, project, and admin API key.

Run it once on a new server. The key is shown once: save it.

rehearsal bootstrap [--org <org>] [--project <project>]

rehearsal bootstrap --org Acme --project default

project: prj_7f4a9532b99af3d2
admin API key (shown once): rh_1a2b3c4d_...
export REHEARSAL_API_KEY=rh_1a2b3c4d_...

rehearsal usersCopy Anchor Link

Self-hosted only Console accounts (runs on the server).

The console needs a person's account. This command creates one in the project you name.

Arguments of rehearsal users add:

rehearsal users add you@example.com --project <project_id>

Password (10+ characters): 
Repeat: 
you@example.com can sign in to the console as owner of project prj_7f4a9532b99af3d2.

rehearsal openapiCopy Anchor Link

Self-hosted only Print the OpenAPI document.

rehearsal openapi

rehearsal openapi > openapi.json

rehearsal pricesCopy Anchor Link

Self-hosted only Model prices from every source, for the configured model chains.

rehearsal prices

rehearsal prices

For each model chain, the command prints the price the server charges at, with its source and date, and the range that other hosts charge.

Coming soonCopy Anchor Link

rehearsal trainCopy Anchor Link

Coming soon Train a model on a world with reinforcement learning.

Not built yet. The command prints a message that says so and exits.

rehearsal train <wv_id> [--base-model <base_model>] [--rounds <rounds>] [--rollouts <rollouts>] [--serve-url <serve_url>]

rehearsal train <wv_id>

Training a model on your practice worlds (reinforcement learning) is coming soon. Every episode already ends with a verified score from the application's database; today you can export verified episodes as a dataset with `rehearsal export`, and improve an agent's instructions with `rehearsal improve`.

rehearsal run-bundleCopy Anchor Link

Coming soon Start a world from an exported bundle on your own machine.

Not built yet. The command prints a message that says so and exits.

rehearsal run-bundle <bundle>

rehearsal run-bundle world.tar

Starting a world from a bundle on your own machine is coming soon. Today, evaluate the published world through the server: rehearsal eval <world_version_id> --profile <agent_id>.