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:

OrderPlaceExample
1A flag on the command--project parcel
2An environment variableREHEARSAL_PROJECT_ID=parcel
3rehearsal.config.json"projectId": "parcel"
4Your sign-in, for the API address onlythe API you signed in to
5The built-in default, for the API address onlyhttps://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:

Terminal
REHEARSAL_APP_ID=web rehearsal whoami
Output
In 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.json

whoami 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 upload reads 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 web reads neither the variables nor rehearsal.config.json for the project and app, only its own --project and --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.

rehearsal.config.json
{  "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:

FieldWhat it holds
schemaVersionAlways 1. It is required.
workspaceIdA workspace identifier.
projectIdA project's slug, or its identifier.
appIdAn app identifier. See A saved app or suite.
defaultSuiteIdA suite identifier.
apiOriginAnother 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 token or password, stops commands with CONFIG_UNSAFE, because the CLI never reads a sign-in from a repository.
  • A regular file. The CLI refuses a link in its place.
  • An apiOrigin with HTTPS, or HTTP on localhost, 127.0.0.1 or ::1. Commands refuse it with UNTRUSTED_API_ORIGIN until 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.

VariableSame asWhat it holds
REHEARSAL_API_URL--apiThe API address, with HTTPS, or HTTP on localhost, 127.0.0.1 or ::1.
REHEARSAL_WORKSPACE_ID--workspaceA workspace identifier.
REHEARSAL_PROJECT_ID--projectA project's slug, name or identifier.
REHEARSAL_APP_ID--appAn app's name, the host of one of its addresses, or its identifier.
REHEARSAL_SUITE_ID--suiteA suite identifier.
REHEARSAL_OUTPUT--jsonjson 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:

VariableWhat it changes
XDG_CONFIG_HOMEMoves the CLI's files from ~/.config/rehearsal/ to $XDG_CONFIG_HOME/rehearsal/.
NO_COLORSet to anything, it turns colour off.
TERMdumb turns off colour, the arrow-key picker and the animation of the live connection panel.
LC_ALL, LC_CTYPE, LANGC 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.

ScopeWhat it allowsPermission it needs
testing:readRead workspaces, projects, apps, environments, tests, suites, runs, evidence, explorations, bugs, builds, maps, test accounts and your connected computers.View projects
testing:runStart paid work, such as runs, explorations and checks of bugs, and change your projects' tests, builds, maps and test accounts.Manage projects
tunnelConnect an app on your computer, and read connections.Manage projects
hostsConnect 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:

Terminal
# Read onlyrehearsal login --scope testing:read# Connect apps, but not this computerrehearsal login --scope tunnel --scope testing:read --scope testing:run

A 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.

FileWhat it holdsWritten by
credentials.jsonYour sign-in: the API it belongs to, the sign-in itself and when it ends.login. logout deletes it.
connections/<connection-id>.jsonOne 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>.logWhat 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>.jsonThis 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.lockWhich 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>.jsonA 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.
  • logout deletes credentials.json only 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.
  • login and logout never touch a connected computer. To stop Rehearsal using one, run connect remove on it.
  • Once a background connection has attached, its files stay after its process ends, until connect stop removes them, so connect list can still report it.