Rima Local Runner

The Rima local runner lets a developer run saved Rima tests against a local app, staging app, or private network URL while keeping the deployed Rima dashboard as the source of truth.

Example:

rima run login-flow --base-url http://localhost:3000 --remote-url https://example.com

The runner downloads the saved test from Rima, rewrites recorded URLs such as https://example.com/login to http://localhost:3000/login, runs the test in a real browser on your machine, writes logs to ~/.rima/logs, and uploads the run summary plus screenshots, traces, and videos back to Rima.

Install

npm install --global @rimatest/local-runner
rima --help

Install for development

cd cli
npm install
npm link

The command becomes available as:

rima --help

Connect to Rima

Run:

rima login

Press Enter when prompted. Rima opens in your browser; sign in normally and approve the CLI connection. The CLI connects to:

https://rimatest.app

For local backend testing, override the app URL:

rima login --api-url http://localhost:4000

Pro and Business workspaces can also use an owner-approved device code when CLI device access has been granted:

rima --login --device-code

Enter the short-lived code when prompted.

Select a workspace and project

Quick setup:

rima --workspace "Acme" --project "Checkout"

Step-by-step setup:

rima select workspace
rima select project
rima select test

When a selector opens, use the arrow keys and press Enter.

rima select test asks for workspace, then project, then test. The test picker includes All, and choosing any option runs immediately.

Short commands are still available. Singular workspace/project commands select and save defaults. Plural commands list. rima test runs a test:

rima workspace   # choose a workspace
rima project     # choose a project
rima test        # choose and run a test, or choose All

rima workspaces  # list workspaces
rima projects    # list projects
rima tests       # list tests

List commands show names by default. Add --verbose to see IDs and extra details:

rima workspaces --verbose
rima projects --verbose
rima tests --verbose

IDs still work when names are ambiguous:

rima workspace org_abc123
rima project 1718900000000-a1b2c3

For one-off commands, pass the workspace and project without saving defaults:

rima tests --workspace "Acme" --project "Checkout"
rima test --workspace "Acme" --project "Checkout" login-flow --base-url http://localhost:3000

List tests

rima tests

Run all tests locally

Start your app first:

npm run dev

Then run one test:

rima test login-flow --base-url http://localhost:3000 --remote-url https://example.com

To pick from a list, including All:

rima test --base-url http://localhost:3000 --remote-url https://example.com

To run every enabled test directly:

rima test --all --base-url http://localhost:3000 --remote-url https://example.com

Run one test

Use the test name, slug, or ID:

rima test login-flow --base-url http://localhost:3000 --remote-url https://example.com

URL rewriting

When tests are recorded on production, the first step and URL validations often point at the deployed site. The runner rewrites:

• page.goto("https://example.com/dashboard")
• URL validations such as url_equals and url_contains
• absolute request URLs to the recorded origin
• absolute URLs found inside recorded test snippets

to:

http://localhost:3000/dashboard

If the runner cannot infer the recorded origin, pass it explicitly:

rima run --base-url http://localhost:3000 --remote-url https://example.com

Logs and local files

Logs are written as JSON lines:

~/.rima/logs/rima-cli-YYYY-MM-DD.log

Run summaries, traces, videos, and failure screenshots are written to:

~/.rima/runs/<run-id>/

By default, the CLI records a video of the run and uploads the run summary, failure screenshots, the video, and a trace. Pass --no-video to skip video recording, or --no-trace to skip trace capture.

Useful options

rima run --headed
rima run --no-video
rima run --no-trace
rima run --stop-on-failure
rima run --no-upload
rima run --environment staging --base-url https://staging.example.com

Authentication

The CLI opens Rima in the browser for normal sign-in and one-click approval. It stores the resulting device session in ~/.rima/config.json. The dashboard can revoke connected devices.

Expose localhost with a tunnel

Install the Rima CLI, log in, then run:

rima tunnel

No additional software installation or network configuration is required.

The CLI asks for a workspace and local port. Starter receives a temporary address, Pro reuses the stable workspace address, and Business can choose the workspace or personal/device address.

Non-interactive examples:

rima tunnel 4200 --workspace "Acme"
rima tunnel --port 4200 --workspace "Acme" --owner workspace
rima tunnel --port 4200 --workspace "Acme" --owner personal

Keep the command running while the public address is needed. Press Ctrl+C to stop it.