Ranger Feature Review CLI

Ranger brings automated QA to agentic development. The CLI sets up your project so your AI coding agent can verify UI features in a real browser, and your team can review the results on a shared dashboard.

https://docs.ranger.net/getting-started/quickstart/

Getting Started

1. Install

npm install -g @ranger-testing/ranger-cli

2. Set Up Your Project

From your project root (must be a git repo):

ranger setup

This walks you through everything interactively:

• Authentication -- opens your browser to log in (credentials stored in OS Keychain)
• Chromium -- installs the browser used for verification
• Plugin -- installs the Claude Code plugin (you choose user-level or project-level)
• Profile -- prompts for your app's URL, opens a browser to capture a session for the verification agent
• Skills -- installs markdown files that teach Claude the Ranger workflow

For CI, pass a token directly: ranger setup [token]. See RANGER_CLI_TOKEN env var for non-interactive use.

3. Use Ranger in Claude Code

/ranger:enable

Ask Claude to build a UI feature. Ranger handles the rest: creating a feature review, verifying it in the browser, and sharing a review link when it's done.

How It Works

1. Claude creates a feature review with scenarios describing what to verify
2. Claude implements the code
3. Claude runs ranger go -- a browser agent tests the feature review scenarios against your running app
4. If something's broken, Claude fixes it and re-verifies
5. Once verified, you review the evidence (screenshots, video) on the dashboard
6. Leave comments or approve -- like a GitHub PR, but for UI

Commands

Setup

| Command | Description | | --------------- | ------------------------------------------------------------------- | | ranger setup | Full interactive setup (auth, browser, plugin, skills, profile) | | ranger login | Re-authenticate without running full setup | | ranger status | Show version, org, plugin, skills, and profile status | | ranger update | Update CLI to latest version and refresh skills | | ranger clean | Remove all Ranger artifacts from the project |

Profiles

A profile tells Ranger where your app runs and how to log in. Run ranger profile add <name> once — a browser opens, you log in, Ranger saves the session for every subsequent run. Convention is one profile per account; the CLI suggests git config user.email as a default name.

| Command | Description | | ------------------------------------- | ----------------------------------------------------- | | ranger profile add <name> | Add a profile (opens a browser for login). Use --safe-mode if the browser crashes. | | ranger profile use <name> | Switch active profile | | ranger profile ls | List all profiles |

For CI / background agents and other setup options, see https://docs.ranger.net/main/concepts/profiles.

Deprecated: ranger profile update, ranger profile encrypt-auth, and ranger profile migrate exit non-zero with a redirect. Run ranger profile add <name> to set up a fresh profile. See https://docs.ranger.net/main/concepts/profiles for setup options.

Feature Reviews

| Command | Description | | --------------------------- | -------------------------------------------------------------- | | ranger create "<name>" | Create a feature review (-d for description, -c for scenarios) | | ranger list | List feature reviews (--current-branch to filter by branch) | | ranger show | Show active feature review status and scenarios | | ranger resume <id> | Set a feature review as active and start its session | | ranger add-scenario "<desc>" | Add a scenario to the active feature review | | ranger get-review | Show unaddressed reviewer comments | | ranger report [id] | Generate PR description markdown with screenshots | | ranger delete | Soft delete the active feature review | | ranger restore <id> | Restore a soft-deleted feature review |

Verification

| Command | Description | | ------------ | ------------------------------------ | | ranger go | Verify a scenario in the browser |

Options: --scenario <N> (scenario index), --notes "<desc>" (override notes), --start-path /path (start URL), --base-url <url> (override profile base URL), --profile <name>, --model <model>, --headed (force headed browser for this run only).

Env vars:

• RANGER_TEST_USERNAME / RANGER_TEST_PASSWORD — for automated login. The fastest path for CI / background agents. Works for any login flow we can run deterministically (username/password, SSO, OAuth, MFA, passkeys, magic links) — set up per-app with our team. Talk to us.
• RANGER_PROFILE — pin a profile (lower precedence than --profile).
• RANGER_BASE_URL / RANGER_START_PATH — analogues of --base-url / --start-path.

You can set a default verify model in .ranger/config.json:

{
  "model": "claude-opus-5"
}

Config

Fine-tune browser behavior for a profile. Settings apply per cwd, so different checkouts of the same repo can have different overrides.

| Command | Description | | --------------------------------------------------- | ------------------------------ | | ranger profile config set <profile> <key> <value> | Set a config value | | ranger profile config get <profile> <key> | Read a config value | | ranger profile config list <profile> | Show all config for a profile | | ranger profile config unset <profile> <key> | Remove a config value | | ranger profile config reset <profile> | Clear all overrides (cloud only) |

Keys: baseUrl, headless, userAgent, storageState, allowInsecureLocalhost, headers.<name>, setupHeaders.<name>. Environment variables (e.g., ${AUTH_TOKEN}) are resolved at runtime.

Plugin

ranger setup installs the Claude Code plugin automatically. To install manually:

claude plugin marketplace add ranger-testing/trailhead
claude plugin install ranger@trailhead --scope user

Troubleshooting

"No active profile" -- Run ranger profile use <profile-name>, or set RANGER_PROFILE=<name> for the session.

Authentication expired -- Run ranger profile add <name> to refresh. (For automated login, re-run ranger go with RANGER_TEST_USERNAME / RANGER_TEST_PASSWORD set.)

Browser crashes during profile setup -- On some macOS + Chrome combinations, the browser may crash during authentication. Run ranger profile add <name> --safe-mode to disable browser features that trigger the crash.

"No active feature review" -- Run ranger list then ranger resume <id>.

Daily warning about legacy .ranger/ paths -- Existing sessions in those paths still work as a fallback, but new sessions are managed for you. Run ranger profile add <name> to set up a fresh profile, then delete the legacy dirs to silence the warning. See https://docs.ranger.net/main/concepts/profiles.

Run ranger status to see everything at a glance.