Install and sign in
Install the Rehearsal CLI, sign in to your account and choose the project a repository works on.
By the end of this page you will have the rehearsal command on your computer, signed in to your Rehearsal account and set up for the project your repository works on.
The CLI works in the same workspaces and projects you see in the app, and it acts as you. A command can do only what your role allows in that workspace, and the sign-in can narrow that further.
Install Link to Install
The CLI needs Node.js 24.12 or newer, which you can check with node --version. Then install the package with the tool you use:
npm install -g @rehearsal-labs/clipnpm add -g @rehearsal-labs/cli# Yarn 1. Yarn 2 and newer have no global install.yarn global add @rehearsal-labs/clibun add -g @rehearsal-labs/cliWhichever tool installs it, the CLI runs on Node.js and adds one command, rehearsal, to your terminal. To check that the install worked, ask the CLI for its version:
rehearsal --version1.3.0Help works offline and before you sign in. rehearsal help lists the groups of commands and a few to start with. rehearsal help do lists the commands of one group, and rehearsal <command> --help explains one command with its flags and examples. To update the CLI later, run the install command again.
Sign in Link to Sign in
The CLI signs in through your browser, so the terminal never sees your password. You approve the request on a page in Rehearsal, and the terminal picks up the sign-in from there.
Step 1: Run the login command
Terminal rehearsal loginYour browser opens a page called Connect to the CLI, and the terminal waits for your answer.
Step 2: Approve the request
The page lists what this terminal will be able to do and which workspaces it will reach. Press Approve. If you did not start this sign-in, press Deny instead.
Step 3: Go back to the terminal
The terminal says "You're signed in." and suggests a few commands to try. The approval link works for 10 minutes, so if it runs out, run
rehearsal loginagain.
On a machine without a browser Link to On a machine without a browser
On a server or in a remote shell, ask for the link instead of a browser window:
rehearsal login --no-browserOpen this link to approve the sign-in: https://app.rehearsal.dev/cli/approve?code=KXQ7M-4TR2PWaiting for approval.Open the link on any device where you are signed in to Rehearsal, such as your laptop or your phone, and approve it there. The terminal carries on once you do.
Approving always needs a person, so rehearsal login --json signs nobody in. It answers with the command that prints an approval link instead. A coding agent starts rehearsal login --no-browser and hands you the link, as What stays with you explains.
Choose what the CLI may do Link to Choose what the CLI may do
A sign-in carries scopes, which say what this computer may do: connect a local app (tunnel), read projects, tests and runs (testing:read), start paid runs and explorations and change how your projects are set up (testing:run), and connect your own computer (hosts). rehearsal login asks for all four. Repeat --scope to ask for less. A scope never adds to your role, so starting a run still needs Manage projects in the workspace. Configuration and environment describes each scope.
# Read onlyrehearsal login --scope testing:read# Read and run, with no local app and no computer of yoursrehearsal login --scope testing:read --scope testing:runGood to know
A new sign-in replaces the one before it on this computer, and ends any local connection the old one opened. When you add a scope, name every scope you still need in the same command.
Check who you are Link to Check who you are
rehearsal whoamiMaya Chen (maya@parcel.example.com)Signed in to https://api.rehearsal.dev until 2026-12-09T10:24:51.000ZThis sign-in may: Connect an app on this computer Read projects, tests, runs and evidence Start paid runs and explorations, and change how your projects are set upIn use here API https://api.rehearsal.dev (your sign-in) Workspace not chosen Project not chosen App not chosen Suite not chosen Settings file none. Run rehearsal init to choose.WorkspacesParcel 2f6e1c7a-8d4b-4e0a-9c55-3b1f0d7e6a21 tunnel testing:read testing:runA sign-in lasts 30 days. After that, commands tell you that you are not signed in, and rehearsal login starts a new one. rehearsal whoami also checks that the saved sign-in still works. With --json it lists every command this sign-in may use, for a script or a coding agent.
The CLI keeps the sign-in in ~/.config/rehearsal/credentials.json, or under $XDG_CONFIG_HOME when you set it. Only your user account may read that file, and the CLI refuses to use it if anyone else can.
Choose the project for a repository Link to Choose the project for a repository
Most commands work inside one workspace and one project. Rather than naming both on every command, save them once in the repository you work in. Run init there:
rehearsal initIt asks which workspace, which project and which app, and skips a question that has one answer. A script names them instead. The workspace takes its identifier, which workspaces list shows, and the project its slug or its name. Add --yes to replace what was saved before:
rehearsal init --workspace <workspace-id> --project parcel --yesinit writes rehearsal.config.json in the current folder:
{ "schemaVersion": 1, "workspaceId": "2f6e1c7a-8d4b-4e0a-9c55-3b1f0d7e6a21", "projectId": "parcel"}The file holds identifiers and the project's slug, never a sign-in, so you can commit it. Your teammates and CI jobs then use the same project. Each command looks for it in the current folder and the folders above, up to the root of the repository. A flag such as --project wins over the file for that one command. rehearsal whoami prints the workspace and project in use and where each one came from. Run init again to change them.
Before it finishes, init offers to add a short note to the repository's AGENTS.md, or to its CLAUDE.md when that is the file it has. The note tells a coding agent that the repository uses Rehearsal, and to check each change with rehearsal check. init writes it only if you say yes, or pass --agent-note yes. Then it prints how to add Rehearsal to Claude Code, Codex and Cursor.
Sign out Link to Sign out
rehearsal logoutRehearsal ends the sign-in, and then the CLI deletes the saved file. If Rehearsal cannot confirm the sign-out, the CLI keeps the file so you can run the command again. To remove the CLI as well, uninstall the package with the tool that installed it, such as npm uninstall -g @rehearsal-labs/cli.
Next steps Link to Next steps
- Test an app on your computerLet Rehearsal's browsers reach the app you run on localhost.
- Find and fix bugs with your coding agentGive Claude Code, Codex or Cursor the tools to explore and check fixes.
- Block a release that breaksRun saved tests from a script or a CI job.
- Sign-in commandsEvery flag of login, whoami and logout.