npm package: @ranger-testing/ranger-cli
Description: 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.
Latest version: 2.5.0

# 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

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

### 2. Set Up Your Project

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

```bash
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 login session
- **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](https://dashboard.ranger.net)
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

| Command                               | Description                                           |
| ------------------------------------- | ----------------------------------------------------- |
| `ranger profile add <name>`           | Add a browser profile (opens browser to capture auth). Use `--safe-mode` if the browser crashes. |
| `ranger profile use <name>`           | Switch active profile                                 |
| `ranger profile ls`                   | List all profiles                                     |
| `ranger profile update <name>`        | Re-capture auth for a profile                         |
| `ranger profile encrypt-auth <name>`  | Encrypt auth.json for safe git storage (CI)           |

### 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), `--profile <name>`, `--model <model>`, `--headed` (force headed browser for this run only).

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

```json
{
  "model": "claude-opus-4-6"
}
```

### Config

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

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

## Plugin

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

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

## Troubleshooting

**"No active profile"** -- Run `ranger profile use <profile-name>`.

**Authentication expired** -- Run `ranger profile update <profile-name>` to re-capture.

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

Run `ranger status` to see everything at a glance.