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. Pass --scope (user|project, defaults to user) for plugin/skills and --url for profile setup. Use --force to skip the URL reachability check and --skip-chromium to skip browser installation.

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

If --url is provided, a browser still opens for auth. Agents should background this and notify the user.

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.
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.
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), userAgent, storageState, cdpEndpoint, loginInstructions, header.<name> (custom HTTP headers).

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

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

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

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.