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 start	Full interactive setup: auth, Chromium, plugin, environment, skills. Run this first.
ranger login	Re-authenticate without running full setup again.
ranger status	Show everything: version, org, plugin status, skills, environments.
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 start

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

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

If you skip any step, you can run it individually later.

Environments

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

Command	What it does
ranger add env <name>	Add a new environment. Opens a browser for you to log in.
ranger use <name>	Switch which environment is active.
ranger env ls	List all environments with their URLs and status.
ranger env update <name>	Re-capture authentication for an existing environment.

Adding an environment with --ci creates an encrypted auth file that’s safe to commit to git. See Managing Environments for details.

Environment Config

Fine-tune browser behavior per environment.

Command	What it does
ranger config set <env> <key> <value>	Set a config value.
ranger config get <env> <key>	Read a config value.
ranger config list <env>	Show all config for an environment.
ranger config unset <env> <key>	Remove a config value.

Supported keys: headless (true/false), userAgent, storageState, header.<name> (custom HTTP headers).

ranger config set local headless true
ranger config set ci header.Authorization '${AUTH_TOKEN}'

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

Features

Features are the core unit of work in Ranger. Each feature has a name, description, and a checklist of items to verify in the browser.

Command	What it does
ranger feature create "<name>"	Create a new feature. Use -c for checklist items, -d for description.
ranger feature list	List features. Use --current-branch to filter by your git branch.
ranger feature show	Show the active feature’s status and checklist.
ranger feature resume <id>	Set a feature as active and start its session.
ranger feature add-checklist-item "<desc>"	Add a checklist item to the active feature.
ranger feature get-feedback	Show unaddressed reviewer comments across all items.
ranger feature sessions	List all sessions (iterations) for the active feature.
ranger feature conclude-session	End the current session, even if items are incomplete.

Creating a Feature

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

Features auto-detect your git repo and branch. The feature becomes active immediately.

Resuming Work

At the start of a session, check for existing features:

ranger feature list --current-branch
ranger feature resume feat_abc123

Verification

ranger verify-feature spawns a browser agent to test your checklist items.

ranger verify-feature

The CLI prompts you to select which checklist item 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:

• --item <N>: skip the selection prompt, verify item N directly (1-based)
• --task "<description>": override what the agent does (defaults to the checklist item’s description)
• --start-path /settings: start the agent on a specific page instead of the base URL
• --env <name>: use a specific environment instead of the active one

Authentication

Command	What it does
ranger auth encrypt <env>	Encrypt an environment’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 features).

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.