Back to docs

CLI Reference

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]

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

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"

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

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

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"

Copyright: (c) 2026 Alexa Eden.

License: MIT License

Contact: [email protected]

From the Blog