Complete reference for all CBrowser commands.

Global Options

These options work with all commands:

Option	Description
`--headless` / `--no-headless`	Run with/without visible browser (default: headless)
`--browser <name>`	Browser engine: `chromium`, `firefox`, `webkit`
`--timeout <ms>`	Default timeout in milliseconds
`--persistent`	Keep browser context between commands
`--help`	Show help for command
`--version`	Show version

Accessibility Options

These options make output accessible for screen readers, CI pipelines, and scripts:

Option	Description
`--no-color`	Disable all ANSI color codes in output
`--plain`	Disable emoji, box-drawing, and unicode decorations
`--json-output`	Output structured JSON instead of human-readable text

CBrowser also respects the NO_COLOR environment variable (no-color.org standard). Set it to any non-empty value to suppress color output.

Examples:

# Screen reader-friendly output (no emoji, no box-drawing)
npx cbrowser doctor --plain

# Machine-readable JSON (for scripts and CI)
npx cbrowser doctor --json-output

# Pipe-friendly (no color codes)
NO_COLOR=1 npx cbrowser navigate "https://example.com"

Diagnostics

doctor

Check your environment with pass/fail for each dependency.

npx cbrowser doctor [options]

Checks:

Node.js version (>= 18 required)
Playwright Chromium installation
Anthropic API Key (warns if missing, not required for basic commands)
Data directory writability

Examples:

npx cbrowser doctor
npx cbrowser doctor --plain
npx cbrowser doctor --json-output

status

Show environment status: data directories, browsers, config, and heal cache.

npx cbrowser status

Navigation

navigate

Navigate to a URL and take a screenshot.

npx cbrowser navigate <url> [options]

Option	Description
`--screenshot <path>`	Save screenshot to path
`--wait <ms>`	Wait after load
`--device <name>`	Emulate device

Examples:

npx cbrowser navigate "https://example.com"
npx cbrowser navigate "https://example.com" --device iphone-15
npx cbrowser navigate "https://example.com" --screenshot home.png

Interaction

smart-click

Click an element using AI-powered selector healing.

npx cbrowser smart-click <selector> [options]

Option	Description
`--url <url>`	Navigate to URL first
`--max-retries <n>`	Maximum retry attempts (default: 3)
`--force`	Bypass safety checks (red zone)

Examples:

npx cbrowser smart-click "Login"
npx cbrowser smart-click "Add to Cart" --url "https://shop.com/product"
npx cbrowser smart-click "Delete Account" --force

fill

Fill a form field.

npx cbrowser fill <selector> <value> [options]

Examples:

npx cbrowser fill "email" "[email protected]"
npx cbrowser fill "password field" "secret123"

click

Basic click (no retry/healing).

npx cbrowser click <selector> [options]

keyboard

Send a key sequence: chords, key names, and literal text in one command.

npx cbrowser keyboard <token> [token...] [options]

Option	Description
`--selector <sel>`	Focus this element first
`--delay <ms>`	Delay between steps (default: 50)
`--hold <mod>`	Hold a modifier across the whole sequence
`--repeat <n>`	Repeat the whole sequence n times
`--text`	Treat every token as literal text (for `+` in text)

Each token is classified before it is sent. A token with modifiers is a chord (Control+A). A known key name is that key (Enter, Tab, ArrowLeft). Anything else is typed as literal text. Unknown key names are rejected, not typed:

Error: unknown modifier "NotAKey" in chord "NotAKey+Control"
  Valid modifiers: Control, Shift, Alt, Meta, ControlOrMeta
  To type this as literal text, use --text.

For a single key use press. For a single string use type.

Examples:

npx cbrowser keyboard "Control+A" "Delete" "Hello world"
npx cbrowser keyboard "ArrowRight" --repeat 5 --hold Shift
npx cbrowser keyboard "Tab" "Tab" "Enter" --selector "#email" --delay 120

Assertions

assert

Natural language assertion.

npx cbrowser assert <assertion> [options]

Option	Description
`--url <url>`	Navigate to URL first

Supported assertions:

"page contains 'text'" - Check page content
"title contains 'text'" - Check page title
"title is 'text'" - Exact title match
"url contains 'path'" - Check URL
"'selector' exists" - Check element exists
"N buttons" - Count elements

Examples:

npx cbrowser assert "page contains 'Welcome'" --url "https://example.com"
npx cbrowser assert "title contains 'Dashboard'"
npx cbrowser assert "5 buttons"

Testing

test-suite

Run natural language test suite.

npx cbrowser test-suite <file> [options]
npx cbrowser test-suite --inline <tests>

Option	Description
`--inline <tests>`	Run inline tests (semicolon-separated)
`--continue-on-failure`	Don't stop on first failure
`--output <path>`	Save JSON report
`--html`	Generate HTML report
`--persona <name>`	Run as persona
`--capture`	Record the run to GIF/WebP/video
`--capture-fps <n>`	Capture frame rate (default: 10)
`--capture-format <list>`	Formats: `gif`, `webp`, `webm`, `mp4` (default: gif)
`--capture-out <dir>`	Capture output directory

The four --capture flags work on both the file form and --inline. They record pixels — see Screen Capture below. They are not record, which records actions for test generation.

Examples:

npx cbrowser test-suite tests.txt
npx cbrowser test-suite tests.txt --continue-on-failure --html
npx cbrowser test-suite --inline "go to https://example.com ; verify title contains Example"
npx cbrowser test-suite tests.txt --capture --capture-fps 8 --capture-out ./run-video

A captured run prints its capture summary after the results table:

🎥 Capture: 7 frames over 661ms (10.6 fps)
   Manifest: ./run-video/manifest.json
   GIF: ./run-video/test-suite-inline-suite-1784492265526.gif

repair-tests

AI-powered test repair.

npx cbrowser repair-tests <file> [options]

Option	Description
`--auto-apply`	Automatically apply fixes
`--verify`	Run repaired tests to confirm
`--output <path>`	Save repaired tests to file

Examples:

npx cbrowser repair-tests broken-tests.txt
npx cbrowser repair-tests tests.txt --auto-apply --verify
npx cbrowser repair-tests tests.txt --auto-apply --output fixed.txt

flaky-check

Detect flaky tests.

npx cbrowser flaky-check <file> [options]

Option	Description
`--runs <n>`	Number of runs (default: 5)
`--threshold <n>`	Flakiness threshold % (default: 20)
`--delay <ms>`	Delay between runs (default: 500)
`--output <path>`	Save JSON report

Examples:

npx cbrowser flaky-check tests.txt
npx cbrowser flaky-check tests.txt --runs 10 --threshold 25
npx cbrowser flaky-check tests.txt --output flaky-report.json

generate-tests

Generate test scenarios by analyzing a page.

npx cbrowser generate-tests <url> [options]

Option	Description
`--format <type>`	Output format: `cbrowser`, `playwright`
`--output <path>`	Save to file

Examples:

npx cbrowser generate-tests "https://example.com"
npx cbrowser generate-tests "https://example.com" --format playwright --output tests.spec.ts

record

Record your interactions and generate a test from them. This records actions, not pixels — for video, use capture (see Screen Capture).

npx cbrowser record <subcommand> [options]

Subcommand	Description
`start`	Start recording interactions (`--url <url>` to navigate first)
`stop`	Stop recording and show actions
`save <name>`	Save recorded test
`list`	List saved recordings
`generate <name>`	Generate Playwright test code

Examples:

npx cbrowser record start --url "https://example.com"
npx cbrowser record stop
npx cbrowser record save "checkout-flow"
npx cbrowser record generate "checkout-flow"

Personas

compare-personas

Run journey with multiple personas and compare.

npx cbrowser compare-personas [options]

Option	Description
`--start <url>`	Starting URL (required)
`--goal <text>`	Goal to achieve (required)
`--personas <list>`	Comma-separated persona names
`--output <path>`	Save JSON report
`--html`	Generate HTML report

Examples:

npx cbrowser compare-personas \
  --start "https://example.com" \
  --goal "Complete signup" \
  --personas power-user,first-timer,elderly-user

explore

Run autonomous exploration as a persona. Heuristic-based, free, no API key required.

npx cbrowser explore <persona> [options]

Option	Description
`--start <url>`	Starting URL (required)
`--goal <text>`	Goal to achieve (required)

Examples:

npx cbrowser explore "first-timer" \
  --start "https://example.com" \
  --goal "Find contact information"

persona

Manage personas.

npx cbrowser persona <subcommand> [options]

Subcommand	Description
`list`	List all personas
`show <name>`	Show persona details
`create <description>`	Create from description
`create-manual`	Create with prompts
`export <name>`	Export to JSON
`import <file>`	Import from JSON
`delete <name>`	Delete custom persona

Examples:

npx cbrowser persona list
npx cbrowser persona create "elderly grandmother new to computers" --name grandma
npx cbrowser persona export elderly-user > elderly.json

Sessions

session

Manage browser sessions.

npx cbrowser session <subcommand> [options]

Subcommand	Description
`save <name>`	Save current session
`load <name>`	Load saved session
`list`	List saved sessions
`delete <name>`	Delete session

Examples:

npx cbrowser session save "logged-in" --url "https://example.com"
npx cbrowser session load "logged-in"
npx cbrowser session list

Analysis

analyze

Analyze page structure.

npx cbrowser analyze <url>

Example:

npx cbrowser analyze "https://example.com"

Output:

📊 Page Analysis:
   Title: Example Domain
   Forms: 1
     - form#login (3 fields)
       🔐 Login form detected
   Buttons: 5
   Links: 12
   Has Login: ✅
   Has Search: ❌
   Has Navigation: ✅

perf

Performance metrics and Core Web Vitals.

npx cbrowser perf <url> [options]

Option	Description
`--budget-lcp <ms>`	LCP budget
`--budget-fid <ms>`	FID budget
`--budget-cls <score>`	CLS budget

Examples:

npx cbrowser perf "https://example.com"
npx cbrowser perf "https://example.com" --budget-lcp 2500 --budget-cls 0.1

Self-Healing

heal stats

Show selector cache statistics.

npx cbrowser heal stats

heal clear

Clear selector cache.

npx cbrowser heal clear

Screenshots

screenshot

Take screenshot of current page.

npx cbrowser screenshot [path] [options]

Option	Description
`--url <url>`	Navigate to URL first
`--full-page`	Capture full scrollable page
`--element <selector>`	Capture specific element

Examples:

npx cbrowser screenshot --url "https://example.com"
npx cbrowser screenshot home.png --url "https://example.com" --full-page

Screen Capture

capture records pixels over time — the screen as a GIF, WebP, or video, plus a JSON manifest describing every frame.

capture is not record. They are separate commands that solve different problems and share no output format:

Command	Records	Output
`capture`	Pixels over time	GIF / WebP / WebM / MP4, JPEG frames, `manifest.json`
`record`	User actions (clicks, fills, navigations)	Saved recording, generated Playwright test code

If you want a video of the page, use capture. If you want a test generated from what you did, use record.

capture start

Start capturing the screen.

npx cbrowser capture start <url> [options]

Option	Description
`--fps <n>`	Target frames per second (default: 10)
`--duration <5s>`	Auto-stop after this long (`5s`, `2m`, `1500ms`)
`--viewport <WxH>`	Viewport size, e.g. `1280x720` (accepts a comma-separated list)
`--region <x,y,w,h>`	Capture a fixed region instead of the viewport
`--element <selector>`	Track an element; the crop follows it as it moves
`--element-padding <n>`	Expand the element box by n CSS px per side
`--device <name>`	Device preset, e.g. `iphone-15`
`--format <list>`	`gif`, `webp`, `webm`, `mp4` (default: gif)
`--quality <1-100>`	JPEG quality of captured frames (default: 80)
`--max-frames <n>`	Stop retaining frames after n (default: 3000)
`--contact-sheet`	Also write one JPEG summarising the whole capture
`--after <event>`	Start on `load`, `domcontentloaded`, or `networkidle`
`--after-element <sel>`	Start when the element is present and visible
`--after-delay <500ms>`	Extra delay after the start trigger
`--until-element <sel>`	Stop when the element appears
`--until-element-gone <sel>`	Stop when the element disappears
`--until-idle <800ms>`	Stop after this long with no visual change
`--timeout <30s>`	Trigger wait budget (default: 30s)
`--out <dir>`	Output directory (default: `~/.cbrowser/videos/<session>/<name>`)
`--name <slug>`	Capture name

Device presets for --device: iphone-15, iphone-15-pro-max, pixel-8, pixel-8-pro, samsung-galaxy-s24, ipad-pro-12, ipad-air, desktop-1080p, desktop-1440p, mobile, tablet, desktop. A name outside this list is rejected and the valid list is printed.

Examples:

npx cbrowser capture start "https://example.com" --duration 3s
npx cbrowser capture start "https://example.com" --duration 5s --format gif,webp --contact-sheet
npx cbrowser capture start "https://example.com" --element "#hero" --element-padding 20 --duration 3s
npx cbrowser capture start "https://example.com" --device iphone-15 --until-idle 800ms

Output:

🎥 Capturing via CDP screencast
  Output: ./capture
  Duration: 3000ms (auto-stops)

✓ Capture stopped
  Stop trigger: duration
  Frames: 32 (10.5 fps actual vs 10 requested)
  Duration: 3062ms
  Manifest: ./capture/manifest.json
  GIF: ./capture/demo1.gif

The output directory holds the encoded artifacts, a frames/ directory of JPEGs (0000.jpg, 0001.jpg, …), and manifest.json. The manifest records the target and actual frame rate, the capture target, the start and stop triggers, change points, frame gaps, and — per frame — its timestamp, file path, crop box, and similarity to the previous frame.

capture stop

Stop the running screen capture.

npx cbrowser capture stop

A capture is stopped from the process that started it. With nothing running, capture stop says so rather than hanging:

No active capture. A capture is stopped from the process that started it.

capture status

Show the running capture, or the most recent one if none is running.

npx cbrowser capture status

Output reports the name, start time, frame count, capture method, artifact paths, and the manifest path.

Start and stop triggers

A capture does not have to be timed. --after, --after-element, and --after-delay decide when recording begins; --duration, --until-element, --until-element-gone, and --until-idle decide when it ends.

# Start once the hero is on screen, stop once the spinner is gone
npx cbrowser capture start "https://example.com" \
  --after-element "#hero" --after-delay 200ms \
  --until-element-gone ".spinner"

# Stop after 800ms with no visual change
npx cbrowser capture start "https://example.com" --until-idle 800ms

--timeout bounds the wait for any trigger (default: 30s). A trigger that never fires is not a silent hang — the capture stops, the manifest and the encoded artifacts are still written, and the process exits non-zero so CI sees a failure while you still get the footage:

✗ Capture trigger timed out
  Stop trigger: element-appears:#never-appears-xyz (timed out after 4000ms)
  Frames: 16 (3.9 fps actual vs 10 requested)
  Duration: 4091ms
  Frame gaps: 1 (largest 2866ms - the page was not repainting)
  Manifest: ./capture/manifest.json
  GIF: ./capture/tout.gif

Capturing a test run or journey

test-suite and cognitive-journey can record themselves with the same four flags. This is capture running underneath them — pixels, not actions.

Option	Description
`--capture`	Record the run to GIF/WebP/video
`--capture-fps <n>`	Capture frame rate (default: 10)
`--capture-format <list>`	Formats: `gif`, `webp`, `webm`, `mp4` (default: gif)
`--capture-out <dir>`	Capture output directory

Examples:

npx cbrowser test-suite tests.txt --capture --capture-out ./run-video
npx cbrowser test-suite --inline "go to https://example.com ; verify title contains Example" --capture

npx cbrowser cognitive-journey \
  --start "https://example.com" \
  --goal "Complete signup" \
  --persona first-timer \
  --capture --capture-format gif,webm --capture-out ./journey-video

Capture limits

Read these before you trust a capture.

Capture is event-driven, not a fixed-rate sampler. The screencast only emits a frame when the page repaints, so --fps is a ceiling. An animating page over 3s gave 32 frames at 10.5 actual fps against 10 requested; a static page over the same 3s gave 4.
Still stretches are reported, not padded. Instead of duplicating frames, the manifest records a frame gap and the CLI prints it: Frame gaps: 1 (largest 3025ms - the page was not repainting).
mp4 needs a full ffmpeg. Playwright's bundled binary is a stripped WebM/VP8-only build. Install a full ffmpeg and set CBROWSER_FFMPEG_PATH, or use --format webm. When one format fails to encode, the formats that did encode are still written and the process exits non-zero.
An open-ended capture needs the daemon. Without --duration or a stop trigger, capture start refuses and tells you to run cbrowser daemon start or bound the capture. Bounded captures run fine with no daemon. In-process captures also carry a 10-minute safety cap that applies only when no --duration was given.
A multi-size --viewport runs sequential captures, each into its own subdirectory named for the size, with the size appended to the slug and its own manifest.json. It needs --duration or a stop trigger so each run can end on its own.

MCP Server

mcp-server

Start MCP server for Claude Desktop.

npx cbrowser mcp-server

See MCP Server for integration details.

Device Emulation

device

Manage device emulation.

npx cbrowser device <subcommand>

Subcommand	Description
`list`	List available devices
`set <name>`	Set default device

Built-in devices:

iphone-15, iphone-15-pro, iphone-14
pixel-7, pixel-8, samsung-s23
ipad-pro-12, ipad-mini
desktop-1080p, desktop-1440p, desktop-4k

Extraction

extract

Extract data from page.

npx cbrowser extract <what> [options]

Option	Description
`--url <url>`	Navigate to URL first
`--format <type>`	Output: `json`, `csv`, `text`

Examples:

npx cbrowser extract "all product names" --url "https://shop.com" --format json
npx cbrowser extract "the main article text" --url "https://blog.com"

Scripting

evaluate

Run JavaScript in the page and print the result. eval is an alias with the identical flag set.

npx cbrowser evaluate "<js>" [options]

Option	Description
`--file <path>`	Read the script from a file instead of argv
`--arg <json>`	Argument for the script (repeatable, JSON-typed)
`--json`	Always print JSON
`--raw`	Print the raw value, unquoted
`--wait-for <selector>`	Wait for the selector before evaluating
`--expect-truthy`	Exit 1 when the result is falsy (CI assertion)

Pass a function expression when you want arguments. Each --arg is parsed as JSON and handed to the function in order, so a string argument needs its own quotes inside the shell quotes: --arg '"nav"'.

Examples:

npx cbrowser evaluate "document.title"
npx cbrowser evaluate "(sel) => !!document.querySelector(sel)" --arg '"nav"'
npx cbrowser evaluate --file check.js --arg '"#main"' --expect-truthy
npx cbrowser evaluate "document.querySelectorAll('img').length" --wait-for "main"

By default a string prints unquoted and an object prints as indented JSON:

{
  "a": 1,
  "b": [
    2,
    3
  ]
}

--json always prints JSON, so "hello" keeps its quotes. --raw prints the value as a plain string, so an object becomes [object Object].

--expect-truthy turns the command into an assertion: exit 0 on a truthy result, exit 1 on a falsy one, with the reason on stderr.

false
✗ Expected a truthy result, got false

Copyright: (c) 2026 Alexa Eden.

License: MIT License

Contact: [email protected]

CLI Reference

Global Options

Accessibility Options

Diagnostics

doctor

status

Navigation

navigate

Interaction

smart-click

fill

click

keyboard

Assertions

assert

Testing

test-suite

repair-tests

flaky-check

generate-tests

record

Personas

compare-personas

explore

persona

Sessions

session

Analysis

analyze

perf

Self-Healing

heal stats

heal clear

Screenshots

screenshot

Screen Capture

capture start

capture stop

capture status

Start and stop triggers

Capturing a test run or journey

Capture limits

MCP Server

mcp-server

Device Emulation

device

Extraction

extract

Scripting

evaluate

From the Blog