# Command Reference

Complete reference for all agent-browser commands. For quick start and common patterns, see SKILL.md.

## Navigation

```bash
agent-browser open <url>      # Navigate to URL (aliases: goto, navigate)
                              # Supports: https://, http://, file://, about:, data://
                              # Auto-prepends https:// if no protocol given
agent-browser back            # Go back
agent-browser forward         # Go forward
agent-browser reload          # Reload page
agent-browser close           # Close browser (aliases: quit, exit)
agent-browser connect 9222    # Connect to browser via CDP port
```

## Snapshot (page analysis)

```bash
agent-browser snapshot            # Full accessibility tree
agent-browser snapshot -i         # Interactive elements only (recommended)
agent-browser snapshot -c         # Compact output
agent-browser snapshot -d 3       # Limit depth to 3
agent-browser snapshot -s "#main" # Scope to CSS selector
agent-browser snapshot -s "body" --path   # Include xpath and cssPath in refs
agent-browser snapshot -s "body" --attrs  # Include element attributes in refs
```

### Path and Attributes Options

When you need element paths or attributes, use `--path` and `--attrs`:

```bash
# Get xpath and cssPath for elements (can use without --selector)
agent-browser snapshot --path
agent-browser snapshot -s "body" --path

# Get element attributes (id, class, href, etc.)
agent-browser snapshot --attrs
agent-browser snapshot -s "body" --attrs

# Get both
agent-browser snapshot --path --attrs
agent-browser snapshot -s "body" --path --attrs
```

**Note:** Using `--selector` is optional but recommended to limit scope and prevent large responses.

**Response example with --path --attrs:**
```json
{
  "refs": {
    "e1": {
      "role": "button",
      "name": "Submit",
      "xpath": "//*[@id=\"submit-btn\"]",
      "cssPath": "#submit-btn",
      "attributes": {"id": "submit-btn", "class": "btn-primary", "type": "submit"}
    }
  }
}
```

## Interactions (use @refs from snapshot)

```bash
agent-browser click @e1           # Click
agent-browser dblclick @e1        # Double-click
agent-browser focus @e1           # Focus element
agent-browser fill @e2 "text"     # Clear and type
agent-browser type @e2 "text"     # Type without clearing
agent-browser press Enter         # Press key (alias: key)
agent-browser press Control+a     # Key combination
agent-browser keydown Shift       # Hold key down
agent-browser keyup Shift         # Release key
agent-browser hover @e1           # Hover
agent-browser check @e1           # Check checkbox
agent-browser uncheck @e1         # Uncheck checkbox
agent-browser select @e1 "value"  # Select dropdown option
agent-browser select @e1 "a" "b"  # Select multiple options
agent-browser scroll down 500     # Scroll page (default: down 300px)
agent-browser scrollintoview @e1  # Scroll element into view (alias: scrollinto)
agent-browser drag @e1 @e2        # Drag and drop
agent-browser upload @e1 file.pdf # Upload files
agent-browser download @e1 ./file.pdf  # Download file by clicking element
```

### Human-like Mouse Movement

Enable globally via environment variable to simulate natural mouse trajectories:

```bash
# Enable human mode (default: arc path type)
export AGENT_BROWSER_HUMAN=1

# Or specify path type
export AGENT_BROWSER_HUMAN=bezier   # Bezier curve with overshoot
export AGENT_BROWSER_HUMAN=arc      # Smooth arc (default, most natural)
export AGENT_BROWSER_HUMAN=random   # Random path with jitter
export AGENT_BROWSER_HUMAN=linear   # Straight line (fastest)

# All interactions will use human-like movement
agent-browser click @e1
agent-browser fill @e1 "text"
agent-browser type @e1 "text"
agent-browser hover @e1
agent-browser dblclick @e1

# Wait with mouse wandering (when human mode enabled)
agent-browser wait 3000  # Wanders mouse while waiting

# Disable human mode
unset AGENT_BROWSER_HUMAN
```

**Trajectory Types:**
| Type | Description | Best For |
|------|-------------|----------|
| `arc` | Smooth arc trajectory (default) | Most natural, general use |
| `bezier` | Bezier curve with overshoot | Realistic targeting |
| `random` | Random path with jitter | Maximum unpredictability |
| `linear` | Straight line | Fastest, less detection needed |

**Affected Commands:**
| Command | Human Mode Effect |
|---------|-------------------|
| `click` | Human-like mouse trajectory + click |
| `dblclick` | Human-like mouse trajectory + double-click |
| `fill` | Human-like mouse trajectory + character-by-character typing |
| `type` | Human-like mouse trajectory + character-by-character typing |
| `hover` | Human-like mouse trajectory |
| `wait <ms>` | Random mouse wandering while waiting |

## Get Information

```bash
agent-browser get text @e1        # Get element text
agent-browser get html @e1        # Get innerHTML
agent-browser get value @e1       # Get input value
agent-browser get attr @e1 href   # Get attribute
agent-browser get title           # Get page title
agent-browser get url             # Get current URL
agent-browser get count ".item"   # Count matching elements
agent-browser get box @e1         # Get bounding box
agent-browser get styles @e1      # Get computed styles (font, color, bg, etc.)
```

## Check State

```bash
agent-browser is visible @e1      # Check if visible
agent-browser is enabled @e1      # Check if enabled
agent-browser is checked @e1      # Check if checked
```

## Screenshots and PDF

```bash
agent-browser screenshot          # Save to temporary directory
agent-browser screenshot path.png # Save to specific path
agent-browser screenshot --full   # Full page
agent-browser pdf output.pdf      # Save as PDF
```

## Video Recording

```bash
agent-browser record start ./demo.webm    # Start recording
agent-browser click @e1                   # Perform actions
agent-browser record stop                 # Stop and save video
agent-browser record restart ./take2.webm # Stop current + start new
```

## Wait

```bash
agent-browser wait @e1                     # Wait for element
agent-browser wait 2000                    # Wait milliseconds
agent-browser wait --text "Success"        # Wait for text (or -t)
agent-browser wait --url "**/dashboard"    # Wait for URL pattern (or -u)
agent-browser wait --load networkidle      # Wait for network idle (or -l)
agent-browser wait --fn "window.ready"     # Wait for JS condition (or -f)
```

## Mouse Control

```bash
agent-browser mouse move 100 200      # Move mouse
agent-browser mouse down left         # Press button
agent-browser mouse up left           # Release button
agent-browser mouse wheel 100         # Scroll wheel
```

## Semantic Locators (alternative to refs)

```bash
agent-browser find role button click --name "Submit"
agent-browser find text "Sign In" click
agent-browser find text "Sign In" click --exact      # Exact match only
agent-browser find label "Email" fill "user@test.com"
agent-browser find placeholder "Search" type "query"
agent-browser find alt "Logo" click
agent-browser find title "Close" click
agent-browser find testid "submit-btn" click
agent-browser find first ".item" click
agent-browser find last ".item" click
agent-browser find nth 2 "a" hover
```

**Important:** `first`, `last`, `nth` are locators for the `find` command, NOT CSS selectors. Do NOT use them directly with `click`, `fill`, etc.

```bash
# WRONG - "first" is not a CSS selector
agent-browser click "first .item"      # Will fail!

# CORRECT - Use find command with first locator
agent-browser find first ".item" click

# ALTERNATIVE - Use CSS pseudo-class selectors
agent-browser click ".item:first-of-type"
agent-browser click ".item:last-of-type"
agent-browser click ".item:nth-of-type(2)"
```

## Browser Settings

```bash
agent-browser set viewport 1920 1080          # Set viewport size
agent-browser set device "iPhone 14"          # Emulate device
agent-browser set geo 37.7749 -122.4194       # Set geolocation (alias: geolocation)
agent-browser set offline on                  # Toggle offline mode
agent-browser set headers '{"X-Key":"v"}'     # Extra HTTP headers
agent-browser set credentials user pass       # HTTP basic auth (alias: auth)
agent-browser set media dark                  # Emulate color scheme
agent-browser set media light reduced-motion  # Light mode + reduced motion
```

## Cookies and Storage

```bash
agent-browser cookies                     # Get all cookies
agent-browser cookies set name value      # Set cookie
agent-browser cookies clear               # Clear cookies
agent-browser storage local               # Get all localStorage
agent-browser storage local key           # Get specific key
agent-browser storage local set k v       # Set value
agent-browser storage local clear         # Clear all
```

## Network

```bash
agent-browser network route <url>              # Intercept requests
agent-browser network route <url> --abort      # Block requests
agent-browser network route <url> --body '{}'  # Mock response
agent-browser network unroute [url]            # Remove routes
agent-browser network requests                 # View tracked requests
agent-browser network requests --filter api    # Filter requests

# Wait for API request and capture response
agent-browser wait --request "api/users"       # Wait for matching request
agent-browser wait --request "aweme/post" --timeout 30000  # With timeout
```

## Tabs

```bash
agent-browser tab                 # List tabs
agent-browser tab new [url]       # New tab
agent-browser tab 2               # Switch to tab by index
agent-browser tab close           # Close current tab
agent-browser tab close 2         # Close tab by index
```

Note: `window new` command exists but creates a new browser window context.

## Iframes (--in-frame option)

Use `--in-frame` option to operate inside iframes. There is no separate `frame` command.

```bash
# Single iframe by ID or name
agent-browser snapshot --in-frame "#my-iframe"
agent-browser click @e1 --in-frame "#login-frame"
agent-browser fill #username "admin" --in-frame "#my-frame"

# Nested iframes using path
agent-browser snapshot --in-frame "#outer-iframe/inner-iframe"
agent-browser get value #input --in-frame "#parent/child"

# Using index instead of name
agent-browser snapshot --in-frame "#0"
agent-browser snapshot --in-frame "#0/1"  # First iframe's second child
```

### Frame Path Syntax

| Format | Example | Description |
|--------|---------|-------------|
| `#id` | `#my-frame` | Frame by ID attribute |
| `#name` | `#login-form` | Frame by name attribute |
| `#index` | `#0`, `#1` | Frame by position |
| `#path` | `#parent/child` | Nested frame by path |
| `#mixed` | `#0/login-form` | Mix of index and name |

The `--in-frame` option works with: click, dblclick, hover, focus, fill, type, check, uncheck, select, scrollintoview, drag, upload, download, press, wait, get, is, find, mouse, eval, snapshot, pdf, highlight, and more.

## Dialogs

```bash
agent-browser dialog accept [text]  # Accept dialog
agent-browser dialog dismiss        # Dismiss dialog
```

## JavaScript

```bash
agent-browser eval "document.title"          # Simple expressions only
agent-browser eval -b "<base64>"             # Any JavaScript (base64 encoded)
agent-browser eval --stdin                   # Read script from stdin
```

Use `-b`/`--base64` or `--stdin` for reliable execution. Shell escaping with nested quotes and special characters is error-prone.

```bash
# Base64 encode your script, then:
agent-browser eval -b "ZG9jdW1lbnQucXVlcnlTZWxlY3RvcignW3NyYyo9Il9uZXh0Il0nKQ=="

# Or use stdin with heredoc for multiline scripts:
cat <<'EOF' | agent-browser eval --stdin
const links = document.querySelectorAll('a');
Array.from(links).map(a => a.href);
EOF
```

## State Management

```bash
agent-browser state save auth.json    # Save cookies, storage, auth state
agent-browser state load auth.json    # Set state path (loads at browser launch)
```

**Note:** State must be loaded at browser launch. Use `--state` flag or close browser first:

```bash
# Method 1: Use --state flag at launch
agent-browser --state auth.json open https://app.example.com

# Method 2: Set path, close, then launch
agent-browser state load auth.json
agent-browser close
agent-browser open https://app.example.com
```

## Global Options

```bash
agent-browser --session <name> ...    # Isolated browser session
agent-browser --json ...              # JSON output for parsing
agent-browser --headed ...            # Show browser window (not headless)
agent-browser --full ...              # Full page screenshot (-f)
agent-browser --cdp <port> ...        # Connect via Chrome DevTools Protocol
agent-browser -p <provider> ...       # Cloud browser provider (--provider)
agent-browser --proxy <url> ...       # Use proxy server
agent-browser --proxy-bypass <list>   # Comma-separated bypass list for proxy
agent-browser --headers <json> ...    # HTTP headers scoped to URL's origin
agent-browser --executable-path <p>   # Custom browser executable
agent-browser --extension <path> ...  # Load browser extension (repeatable)
agent-browser --ignore-https-errors   # Ignore SSL certificate errors
agent-browser --help                  # Show help (-h)
agent-browser --version               # Show version (-V)
agent-browser <command> --help        # Show detailed help for a command
```

## Debugging

```bash
agent-browser --headed open example.com   # Show browser window
agent-browser --cdp 9222 snapshot         # Connect via CDP port
agent-browser connect 9222                # Alternative: connect command
agent-browser console                     # View console messages
agent-browser console --clear             # Clear console
agent-browser errors                      # View page errors
agent-browser errors --clear              # Clear errors
agent-browser highlight @e1               # Highlight element
agent-browser trace start                 # Start recording trace
agent-browser trace stop trace.zip        # Stop and save trace
```

## Step Recorder

Record user interactions as structured steps for LLM processing:

```bash
agent-browser recorder start                    # Start recording
agent-browser recorder start https://site.com   # Start with navigation
agent-browser recorder stop                     # Stop and output YAML
agent-browser recorder stop --output session.yaml  # Save to file
agent-browser recorder status                   # Show recording status
agent-browser recorder replay                   # Replay most recent
agent-browser recorder replay session.yaml      # Replay specific file
```

## Remote Viewing

```bash
agent-browser viewer           # Get viewer URL for browser session
agent-browser viewer --json    # Get all URLs (HTTP + WebSocket)
```

Requires Stream Server to be running.

## User Interaction

```bash
# Simple question
agent-browser ask "What should I do next?"

# Multiple choice question (JSON format)
agent-browser ask '{"questions":[{"question":"Choose action","options":[{"label":"Login"},{"label":"Skip"}]}]}'

# Multi-select question
agent-browser ask '{"questions":[{"question":"Select items","multiSelect":true,"options":[{"label":"Item 1"},{"label":"Item 2"}]}]}'
```

Requires Stream Server with message bridge.

## Session Management

```bash
agent-browser session          # Show current session name
agent-browser session list     # List all active sessions
agent-browser kill             # Kill all daemons and Stream Server
```

## Configuration

```bash
agent-browser config           # Show all AGENT_BROWSER_* settings
agent-browser config --json    # JSON output
```

## Setup

```bash
agent-browser install          # Install browser binaries
agent-browser install --with-deps  # Also install system dependencies (Linux)
```

## Diff Option (Page Change Detection)

Show page changes after actions:

```bash
agent-browser click @e1 --diff           # Show changes 3 levels up from target
agent-browser fill @e2 "text" --diff 5   # Show changes 5 levels up
agent-browser click @e1 --diff full      # Show entire page changes
agent-browser click @e1 --diff --selector "#content"  # Scope to selector
```

## Environment Variables

```bash
AGENT_BROWSER_SESSION="mysession"            # Default session name
AGENT_BROWSER_EXECUTABLE_PATH="/path/chrome" # Custom browser path
AGENT_BROWSER_EXTENSIONS="/ext1,/ext2"       # Comma-separated extension paths
AGENT_BROWSER_PROVIDER="browserbase"         # Cloud browser provider
AGENT_BROWSER_STREAM_PORT="9223"             # WebSocket streaming port
AGENT_BROWSER_HOME="/path/to/agent-browser"  # Custom install location
AGENT_BROWSER_HUMAN="1"                      # Enable human-like mouse movement (1, bezier, arc, random, linear)
AGENT_BROWSER_PROXY="http://proxy:8080"      # Proxy server URL
AGENT_BROWSER_PROXY_BYPASS="localhost,*"     # Proxy bypass hosts
```
