CLI Overview

The Ranger CLI (@ranger-testing/ranger-cli) is the primary tool for setting up, managing, and running Ranger in your project. Install it globally:

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

This page covers all commands at a human-readable level. Your AI coding agent has its own detailed skill docs, so you don’t need to memorize flags.

Setup

Command	What it does
ranger setup	Full interactive setup: auth, Chromium, plugin, profile, skills. Run this first.
ranger login	Re-authenticate without running full setup again.
ranger status	Show everything: version, org, plugin status, skills, profiles.
ranger update	Update the CLI to the latest version and refresh installed skills.
ranger clean	Remove all Ranger artifacts from the project (nuclear option).

ranger setup

The recommended way to get started. Run it in your project root (should be a git repo for feature review tracking) and it walks you through:

1. Browser-based authentication (or pass a token for CI: ranger setup [token])
2. Chromium installation for browser verification
3. Claude Code plugin installation
4. Profile setup (your app’s URL + login)
5. Skill installation

If you skip any step, you can run it individually later — each phase is also available as a subcommand.

Subcommands

Command	What it does
ranger setup	Full interactive setup (default).
ranger setup all	Explicit full setup — same as bare ranger setup.
ranger setup deps	Install Chromium only. No auth, no git repo required. Use --with-deps for OS packages.
ranger setup login	Authenticate only. Use --token <t> or --mcp for non-interactive auth.
ranger setup skills	Install Claude Code plugin and skills only. Use --scope user|project, --opencode.
ranger setup profiles	Set up a local browser profile only. Use --url, --force, --allow-insecure-localhost.

Non-interactive mode

Individual subcommands are the preferred way to script setup in containers and CI:

# Docker build time — no auth needed
ranger setup deps --with-deps

# Runtime — auth and skills
ranger setup login --token $RANGER_CLI_TOKEN
ranger setup skills --scope user

The full ranger setup command also accepts flags for non-interactive use:

Flag	Description
--scope user|project	Install scope for plugin, skills, and profile (defaults to user). user keeps everything in your home directory; project stores in the repo.
--url <url>	Base URL for profile setup. A browser still opens for auth.
--force	Skip URL reachability check.
--skip-chromium	Skip Chromium installation.
--skip-auth	Skip authentication — install deps only. Useful for container/CI image builds where auth happens at runtime.
--with-deps	Install OS-level dependencies for Chromium (apt packages for Debian/Ubuntu). Pair with --skip-auth for container builds.
--allow-insecure-localhost	Allow localhost content in deployed environments (micro frontends).
--mcp-bootstrap	Bootstrap auth via an MCP auth server instead of browser login. Used by managed agent platforms and MCP-compatible tools.

ranger setup $TOKEN --scope project --url http://localhost:3000

Headless / Scripted Setup

For Docker containers and CI images, use subcommands to separate build-time deps from runtime auth:

# Dockerfile (build time)
RUN npm install -g @ranger-testing/ranger-cli
RUN ranger setup deps --with-deps

# Runtime startup script
ranger setup login --token $RANGER_CLI_TOKEN    # or: ranger setup login --mcp
ranger setup skills --scope user
ranger profile use preview

Authenticating the Ranger CLI to Ranger

Interactive (laptops, developer machines)

ranger setup opens a browser for login. The CLI manages token refresh automatically. If your session expires, run ranger login to re-authenticate.

CI and scripted environments

Pass an API token from your Ranger Dashboard:

ranger setup <token>

Or set the RANGER_CLI_TOKEN environment variable — the CLI reads it automatically.

MCP authentication

The CLI can authenticate via MCP, which may be useful in non-interactive environments where you would like the Ranger CLI to act on a real user’s behalf:

ranger setup --mcp-bootstrap

Set RANGER_MCP_AUTH_URL to point at your platform’s MCP proxy if applicable. Contact us for setup guidance.

Logging the CLI into your App (Profiles)

CLI auth (above) identifies you to the Ranger API. Separately, the browser agent needs to log in to your app so it can verify features. This is handled by Profiles — when you run ranger profile add, you log in to your app in a browser, and Ranger saves the session cookies.

Command	What it does
ranger profile encrypt-auth <profile>	Encrypt a profile’s auth.json for safe git storage (CI use).

See Managing Profiles for full details on login instructions.

Profiles

Profiles tell Ranger how to access your application: the URL, authentication cookies, and browser settings.

Command	What it does
ranger profile add <name>	Add a new profile. Opens a browser for you to log in. Supports --url, --force, --ci, --skip-auth, --cdp-endpoint, --allow-insecure-localhost, --safe-mode, --setup-header, --scope user|project.
ranger profile use <name>	Switch which profile is active.
ranger profile ls	List all profiles with their URLs and status.
ranger profile update <name>	Re-capture authentication for an existing profile. Supports --allow-insecure-localhost.
ranger profile encrypt-auth <name>	Encrypt auth.json for safe git storage (CI use).

Adding a profile with --ci creates an encrypted auth file that’s safe to commit to git. Use --cdp-endpoint to connect to an Electron app or existing browser via Chrome DevTools Protocol instead of a URL. See Managing Profiles for details.

Profile Config

Fine-tune browser behavior per profile.

Command	What it does
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.

Supported keys: headless (true/false), allowInsecureLocalhost (true/false), safeMode (true/false, disables browser features like Bluetooth that can cause crashes on some systems), userAgent, storageState, cdpEndpoint, loginInstructions, header.<name> (custom HTTP headers sent with every request), setupHeader.<name> (HTTP headers sent only during profile setup auth — see below).

ranger profile config set local headless true
ranger profile config set local allowInsecureLocalhost true
ranger profile config set ci header.Authorization '${AUTH_TOKEN}'
ranger profile config set my-electron-app cdpEndpoint http://localhost:9222
ranger profile config set local setupHeader.x-bypass-turnstile 'a1b2c3d4...'

Environment variables like ${AUTH_TOKEN} are resolved at runtime.

Setup-Only Headers

Some apps require a custom HTTP header to bypass login protection (e.g. Cloudflare Turnstile) during initial setup, but that header causes problems if sent on every request during test runs (e.g. CORS failures with third-party services).

Use setupHeader.<name> to set headers that are only sent during the ranger profile add auth browser session:

# Via config (applied on next profile add)
ranger profile config set local setupHeader.x-bypass-turnstile 'a1b2c3d4...'

# Or inline during profile creation
ranger profile add local --url https://app.example.com --setup-header "x-bypass-turnstile: a1b2c3d4..."

These headers are persisted in the profile and reused when you re-add or overwrite the profile. They are not sent during ranger go verification runs.

Custom Login Instructions

If your app uses short-lived cookies or tokens that expire before Ranger can use them, you can provide custom login instructions instead of relying on saved auth state. Set loginInstructions to tell the Ranger agent how to authenticate before each verification run:

ranger profile config set local loginInstructions "Navigate to http://localhost:3000/api/debug-auth?email=test@example.com. Copy the token from the JSON response. Run in the browser console: localStorage.setItem('auth_token', '<the-token>'). Refresh the page."

The agent will follow these instructions as a mandatory first step before every verification. This works with any auth mechanism — local debug endpoints, API keys, token injection, etc. Environment variables are supported:

ranger profile config set local loginInstructions "Navigate to ${BASE_URL}/api/debug-auth?email=${TEST_USER_EMAIL} to obtain a session token."

Feature Reviews

Feature reviews are the core unit of work in Ranger. Each feature review has a name, description, and scenarios to verify in the browser.

Command	What it does
ranger create "<name>"	Create a new feature review. Use -c for scenarios, -d for description.
ranger list	List feature reviews. Use --current-branch to filter by your git branch.
ranger show	Show the active feature review’s 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 across all scenarios.
ranger report [id]	Generate PR description markdown with screenshots. Use --json for structured output.
ranger delete	Soft delete the active feature review.
ranger restore <id>	Restore a soft-deleted feature review.

Creating a Feature Review

ranger create "Dark Mode Toggle" \
  -d "Add dark mode support to settings page" \
  -c "User opens settings, toggles dark mode, and the page switches themes"

Feature reviews auto-detect your git repo and branch. The feature review becomes active immediately.

Resuming Work

At the start of a session, check for existing feature reviews:

ranger list --current-branch
ranger resume feat_abc123

Generating Reports

ranger report generates a PR description from the active feature review’s verified scenarios, including screenshots.

ranger report
ranger report feat_abc123

By default, output is markdown. Use --json for structured output that other tools can consume:

ranger report --json

The JSON output contains the feature review dashboard URL and an array of scenarios:

{
  "url": "https://dashboard.ranger.net/features/feat_...",
  "scenarios": [
    {
      "description": "string",
      "result": "verified | incomplete | blocked | in_progress | pending | approved | cancelled | superseded | closed",
      "rationale": "string | null",
      "steps": [
        {
          "description": "string",
          "screenshot": "string (URL) | null",
          "is_key_step": true
        }
      ]
    }
  ]
}

result reflects the scenario’s verification status. rationale is the agent’s response or the reason for a blocked/incomplete/cancelled status. Each step includes a screenshot URL when available; is_key_step marks the most important moments.

Use --exclude to omit specific scenarios by number (1-based):

ranger report --exclude 2 4

Verification

ranger go spawns a browser agent to test your scenarios.

ranger go

The CLI prompts you to select which scenario to verify. The browser agent navigates your app, interacts with the UI, takes screenshots, and returns a verdict (verified, partial, blocked, or failed).

Common options:

• --scenario <N>: skip the selection prompt, verify scenario N directly (1-based)
• --notes "<description>": override what the agent does (defaults to the scenario description)
• --start-path /settings: start the agent on a specific page instead of the base URL
• --profile <name>: use a specific profile instead of the active one
• --headed: force a headed browser for this run only (does not change profile config)

In Claude Code

These aren’t CLI commands. They’re slash commands inside Claude Code:

Command	What it does
/ranger:enable	Enable Ranger hooks for this session and branch.
/ranger:disable	Disable Ranger hooks.
/ranger	Invoke the Ranger skill (create, verify, or manage feature reviews).

Ranger stays enabled on your branch across sessions (except on main/master, where it’s session-only). You only need to enable once per branch.