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.

Non-interactive mode

AI coding agents can call ranger setup non-interactively:

Flag	Description
--scope user|project	Install scope for plugin/skills (defaults to user).
--url <url>	Base URL for profile setup. A browser still opens for auth.
--force	Skip URL reachability check.
--skip-chromium	Skip Chromium installation.
--allow-insecure-localhost	Allow localhost content in deployed environments (micro frontends).

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

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

Authentication

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

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.