Configuration and environment
Look up the repository file, the environment variables, the sign-in scopes and the files the CLI keeps on your computer.
The CLI decides which API, workspace, project and app a command works on from four places: the command's flags, environment variables, a rehearsal.config.json in your repository, and your sign-in. This page lists each of them, then the scopes a sign-in can hold and the files the CLI keeps on your computer.
You need it when you set up a CI job, share a repository's choice of project with your team, or want to know where a value came from. Install and sign in covers the first setup.
Where each value comes from Link to Where each value comes from
Most commands take each value from the first of these places that sets it, and two commands choose the project in their own way:
| Order | Place | Example |
|---|---|---|
| 1 | A flag on the command | --project parcel |
| 2 | An environment variable | REHEARSAL_PROJECT_ID=parcel |
| 3 | rehearsal.config.json | "projectId": "parcel" |
| 4 | Your sign-in, for the API address only | the API you signed in to |
| 5 | The built-in default, for the API address only | https://api.rehearsal.dev |
rehearsal whoami prints what is in use and where each value came from, under In use here. Here it runs in a folder of the Parcel repository, with the app set by a variable:
REHEARSAL_APP_ID=web rehearsal whoamiIn use here API https://api.rehearsal.dev (your sign-in) Workspace 2f6e1c7a-8d4b-4e0a-9c55-3b1f0d7e6a21 (rehearsal.config.json) Project parcel (rehearsal.config.json) App web (REHEARSAL_APP_ID) Suite not chosen Settings file /Users/you/parcel/rehearsal.config.jsonwhoami shows these values as they were given, without checking them. The first command that uses them checks them with Rehearsal, and refuses one you cannot reach.
The CLI stops with CONTEXT_CONFLICT rather than mix places that disagree. If you name a workspace with a flag or a variable while the project still comes from the file, and the file's project belongs to another workspace, the command asks you to name the project too. A project you name and the file's app follow the same rule.
When nothing sets a value Link to When nothing sets a value
When none of these places sets the workspace or the project, a command that needs one stops and says which flag to pass. Two commands choose differently:
rehearsal builds uploadreads the places above first. When they leave the workspace or the project unset, it takes your only one, or lets you pick at a terminal.rehearsal connect webreads neither the variables norrehearsal.config.jsonfor the project and app, only its own--projectand--app. Without them, it takes the project and app that already hold the address you connect, or your only ones, or lets you pick at a terminal.
Where more than one could be meant and nothing can ask, both stop with CHOICE_NEEDED and exit 4, and choices lists the values to pass.
The repository file Link to The repository file
rehearsal.config.json records which workspace and project a repository works on, so you and your coding agent do not pass them on every command. It holds identifiers and a project slug, never a sign-in.
{ "schemaVersion": 1, "workspaceId": "2f6e1c7a-8d4b-4e0a-9c55-3b1f0d7e6a21", "projectId": "parcel"}rehearsal init asks which workspace, project and app, and writes the answer to the file in use. With no file yet, it writes one in the folder you run it in, so run it at the repository's root. Run it again to change the choice. A script that would replace what the file holds adds --yes. The file may hold these fields:
| Field | What it holds |
|---|---|
schemaVersion | Always 1. It is required. |
workspaceId | A workspace identifier. |
projectId | A project's slug, or its identifier. |
appId | An app identifier. See A saved app or suite. |
defaultSuiteId | A suite identifier. |
apiOrigin | Another Rehearsal API, such as one running on your computer. init writes it only when you pass --api or set REHEARSAL_API_URL. |
After it writes a file that names a project, init also offers to add a short note to AGENTS.md, or to CLAUDE.md when only that one exists, saying the repository uses Rehearsal and pointing a coding agent at rehearsal help agent-workflow. It shows the note first and writes nothing without a yes, or --agent-note yes.
How the CLI finds it Link to How the CLI finds it
Each command looks for the file in the folder it runs in, then in each folder above, and stops at the folder that holds .git. So a command run anywhere inside the repository finds a file at its root, and so does the MCP server your coding agent starts there.
What the file may hold Link to What the file may hold
- Only the fields above. An unknown field, or a value the CLI cannot use, stops every command that reads the file with
CONFIG_INVALID, and the error names the field. - No secrets. A field whose name looks like one, such as
tokenorpassword, stops commands withCONFIG_UNSAFE, because the CLI never reads a sign-in from a repository. - A regular file. The CLI refuses a link in its place.
- An
apiOriginwith HTTPS, or HTTP onlocalhost,127.0.0.1or::1. Commands refuse it withUNTRUSTED_API_ORIGINuntil you sign in to that API yourself, so a file you cloned cannot point your commands at an API you never chose.
A saved app or suite Link to A saved app or suite
A saved appId or defaultSuiteId never chooses what a run, an exploration or a build upload works on. run, explore and builds upload take an app only from --app or REHEARSAL_APP_ID, and explore also from a person at a terminal. run takes a suite only from --suite or REHEARSAL_SUITE_ID, or from a person at a terminal, where it offers the saved suite first. Other commands that take --app, such as tests list, map show, map scan and map crawl, use the saved app.
Environment variables Link to Environment variables
Environment variables suit CI and scripts, where setting a value once for a whole job is easier than a flag on every command. Each of these stands in for a flag, a flag on the command still wins, and an empty variable counts as unset. connect web reads only REHEARSAL_API_URL of them, and takes the project and app from its own flags.
| Variable | Same as | What it holds |
|---|---|---|
REHEARSAL_API_URL | --api | The API address, with HTTPS, or HTTP on localhost, 127.0.0.1 or ::1. |
REHEARSAL_WORKSPACE_ID | --workspace | A workspace identifier. |
REHEARSAL_PROJECT_ID | --project | A project's slug, name or identifier. |
REHEARSAL_APP_ID | --app | An app's name, the host of one of its addresses, or its identifier. |
REHEARSAL_SUITE_ID | --suite | A suite identifier. |
REHEARSAL_OUTPUT | --json | json makes every command answer in JSON, ask nothing and open no browser. text is the default. Any other value is refused. |
Set REHEARSAL_OUTPUT=json once for a coding agent or a CI job, and no command needs --json. Output sent through a pipe stays text unless you set it, so grep and less keep working.
The CLI also reads a few variables that most terminal programs read:
| Variable | What it changes |
|---|---|
XDG_CONFIG_HOME | Moves the CLI's files from ~/.config/rehearsal/ to $XDG_CONFIG_HOME/rehearsal/. |
NO_COLOR | Set to anything, it turns colour off. |
TERM | dumb turns off colour, the arrow-key picker and the animation of the live connection panel. |
LC_ALL, LC_CTYPE, LANG | C or POSIX in the first one that is set makes the output plain text, without Unicode drawing. |
Sign-in scopes Link to Sign-in scopes
A sign-in holds scopes, which limit what the CLI may do with your account. A scope never adds to your role, because each one is checked against a permission you must also hold in the workspace.
| Scope | What it allows | Permission it needs |
|---|---|---|
testing:read | Read workspaces, projects, apps, environments, tests, suites, runs, evidence, explorations, bugs, builds, maps, test accounts and your connected computers. | View projects |
testing:run | Start paid work, such as runs, explorations and checks of bugs, and change your projects' tests, builds, maps and test accounts. | Manage projects |
tunnel | Connect an app on your computer, and read connections. | Manage projects |
hosts | Connect this computer to open the runs you start, and remove your computers. | Manage projects |
Some commands need a second permission as well, such as Use Re:agent to start an exploration. Each command's help lists what it needs.
rehearsal login asks for all four scopes unless you name some. To choose, repeat --scope:
# Read onlyrehearsal login --scope testing:read# Connect apps, but not this computerrehearsal login --scope tunnel --scope testing:read --scope testing:runA new approval replaces the sign-in on this computer and ends the old one, along with any connection it opened, so name every scope you still need. When a command finds a scope missing, it fails with SCOPE_NOT_GRANTED, and its next action asks for the scopes you already hold as well as the missing one.
A sign-in lasts 30 days. rehearsal whoami shows the scopes it holds and when it ends.
Files on your computer Link to Files on your computer
The CLI keeps its files in one folder, ~/.config/rehearsal/, or $XDG_CONFIG_HOME/rehearsal/ when that variable is set. Only your user account can open the folder, and the CLI refuses a sign-in or computer file that other users can read, or one that is a link.
| File | What it holds | Written by |
|---|---|---|
credentials.json | Your sign-in: the API it belongs to, the sign-in itself and when it ends. | login. logout deletes it. |
connections/<connection-id>.json | One background connection: its process, its project, app and address, the local address it serves and where its log is. It holds no sign-in. | connect web --detach. connect stop deletes it. |
connections/<connection-id>.log | What the background connection reported: when it opened, connected, lost the tunnel and closed. Before the connection has an identifier, the log is a starting- file in the same folder. | The background connection. |
computers/<kind>.json | This computer as you connected it for one kind, electron, ios or android: the API, the workspace, its name and identifier, and the secret it made for itself, of which Rehearsal keeps only a hash. | connect electron, connect ios or connect android. connect remove deletes it. |
computers/electron.lock, computers/android.lock, host.lock | Which connection of a kind is running, so that only one runs at a time. host.lock is the iPhones' lock. | The connection, while it runs. |
connections/<computer-id>.json | A computer connected in the background: its process, kind, name and where its log is. It holds no secret. | connect electron, connect ios or connect android with --detach. connect stop deletes it. |
logoutdeletescredentials.jsononly once Rehearsal confirms the sign-out, or says the sign-in had already ended. If it cannot tell, the file stays so you can try again.loginandlogoutnever touch a connected computer. To stop Rehearsal using one, runconnect removeon it.- Once a background connection has attached, its files stay after its process ends, until
connect stopremoves them, soconnect listcan still report it.