### Quick Start (No Install)

Source: https://agent-browser.dev/installation

Run agent-browser commands directly using npx without a global installation. Includes downloading Chrome on the first run.

```bash
npx agent-browser install   # Download Chrome (first time only)
npx agent-browser open example.com
```

--------------------------------

### Core Workflow Example

Source: https://agent-browser.dev/quick-start

Demonstrates the fundamental steps of opening a website, taking a snapshot to get element references, interacting with elements using those references, and taking another snapshot.

```shell
# 1. Navigate
agent-browser open example.com

# 2. Snapshot to get element refs
agent-browser snapshot -i
# Output:
# @e1 [heading] "Example Domain"
# @e2 [link] "More information..."

# 3. Interact using refs
agent-browser click @e2

# 4. Re-snapshot after page changes
agent-browser snapshot -i
```

--------------------------------

### Pre-navigation Setup with Batch Commands

Source: https://agent-browser.dev/init-scripts

Stage state like routes, cookies, or scripts before the first navigation by starting the browser without a URL and using batch commands.

```bash
agent-browser batch \
  '["open"]' \
  '["network","route","*","--abort","--resource-type","script"]' \
  '["cookies","set","--curl","cookies.curl","--domain","localhost"]' \
  '["navigate","http://localhost:3000/target"]'
```

--------------------------------

### Start Recording with Initial Navigation

Source: https://agent-browser.dev/recording

Initiate a browser session and start recording immediately to a file while navigating to a specified URL.

```bash
agent-browser open
agent-browser record start ./demo.webm https://example.com
```

--------------------------------

### Install and Run Agent Browser CLI

Source: https://agent-browser.dev/changelog

Install the agent-browser globally and run basic commands for opening websites and taking snapshots.

```bash
npm install -g agent-browser      # 7 MB install
agent-browser install              # download Chrome
agent-browser open example.com
agent-browser snapshot
```

--------------------------------

### Start Dashboard and Open Session

Source: https://agent-browser.dev/dashboard

Start the local dashboard server and open a new agent session. The dashboard will automatically connect to the session.

```bash
agent-browser dashboard start
agent-browser open example.com
```

--------------------------------

### Manage Observability Dashboard

Source: https://agent-browser.dev/changelog

Commands to install, start, and stop the local observability dashboard. The dashboard provides a live UI for browser sessions.

```bash
agent-browser dashboard install
agent-browser dashboard start
agent-browser open example.com    # session appears in dashboard
agent-browser dashboard stop
```

--------------------------------

### Install Appium and XCUITest Driver

Source: https://agent-browser.dev/ios

Install Appium globally and then install the XCUITest driver for iOS automation. Ensure Appium is installed before proceeding with driver installation.

```bash
# Install Appium globally
npm install -g appium

# Install the XCUITest driver for iOS
appium driver install xcuitest
```

--------------------------------

### Install Lightpanda Binary on Linux

Source: https://agent-browser.dev/engines/lightpanda

Installs the Lightpanda binary for Linux (x86_64) using curl and makes it executable.

```bash
curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux && chmod a+x ./lightpanda
```

--------------------------------

### Example Agent Browser JSON Configuration

Source: https://agent-browser.dev/configuration

A sample agent-browser.json file demonstrating various configuration options.

```json
{
  "headed": true,
  "proxy": "http://localhost:8080",
  "profile": "./browser-data",
  "userAgent": "my-agent/1.0",
  "hideScrollbars": false,
  "ignoreHttpsErrors": true
}
```

--------------------------------

### Global Installation

Source: https://agent-browser.dev/installation

Installs the agent-browser CLI globally for maximum performance. Requires running 'agent-browser install' to download the necessary Chrome binary.

```bash
npm install -g agent-browser
agent-browser install  # Download Chrome from Chrome for Testing (first time)
```

--------------------------------

### Install agent-browser CLI

Source: https://agent-browser.dev/

Install the agent-browser CLI globally using npm or Homebrew. The first-time use requires downloading Chrome.

```bash
npm install -g agent-browser      # all platforms
brew install agent-browser        # macOS
agent-browser install             # Download Chrome (first time)

# or try without installing
npx agent-browser open example.com
```

--------------------------------

### Basic Video Recording Workflow

Source: https://agent-browser.dev/recording

Start a browser session, begin recording to a specified file, perform actions, and then stop the recording.

```bash
agent-browser open https://example.com
agent-browser record start ./demo.webm
agent-browser snapshot -i
agent-browser click @e1

agent-browser record stop
```

--------------------------------

### CDN and Third-Party Resources Allowlist Example

Source: https://agent-browser.dev/security

Example of an allowlist that includes common CDN and third-party domains to prevent website breakage due to blocked sub-resource requests.

```bash
--allowed-domains "myapp.com,*.myapp.com,cdn.jsdelivr.net,fonts.googleapis.com,fonts.gstatic.com"
```

--------------------------------

### Build from Source

Source: https://agent-browser.dev/installation

Clones the agent-browser repository, installs dependencies, builds the project, and links it globally. Includes downloading Chrome.

```bash
git clone https://github.com/vercel-labs/agent-browser
cd agent-browser
pnpm install
pnpm build
pnpm build:native
./bin/agent-browser install
pnpm link --global
```

--------------------------------

### Start, Perform Actions, and Stop Profiling

Source: https://agent-browser.dev/profiler

This sequence demonstrates the basic workflow for capturing a performance profile. Start profiling, execute your browser actions, and then stop the profiler to save the trace data.

```bash
# Start profiling
agent-browser profiler start

# Perform actions
agent-browser navigate https://example.com
agent-browser click "#button"

# Stop and save profile
agent-browser profiler stop ./trace.json
```

--------------------------------

### AgentCore Examples with Different Configurations

Source: https://agent-browser.dev/providers/agentcore

Demonstrates various ways to configure AgentCore sessions, including using explicit regions, SSO profiles, and persistent browser profiles.

```bash
# Basic usage (credentials auto-resolved via AWS CLI)
agent-browser -p agentcore open https://example.com
```

```bash
# With a browser profile for persistent login state
AGENTCORE_PROFILE_ID=my-profile agent-browser -p agentcore open https://x.com/home
```

```bash
# With explicit region
AGENTCORE_REGION=eu-west-1 agent-browser -p agentcore open https://example.com
```

```bash
# With SSO profile
AWS_PROFILE=my-sso-profile agent-browser -p agentcore open https://example.com
```

--------------------------------

### Semantic Locator Examples

Source: https://agent-browser.dev/commands

Demonstrates finding and interacting with elements using semantic locators. Shows how to click buttons, fill forms, and hover.

```bash
agent-browser find role button click --name "Submit"
agent-browser find label "Email" fill "test@test.com"
agent-browser find alt "Logo" click
agent-browser find first ".item" click
agent-browser find last ".item" text
agent-browser find nth 2 ".card" hover
```

--------------------------------

### Install Lightpanda Binary on macOS

Source: https://agent-browser.dev/engines/lightpanda

Installs the Lightpanda binary for macOS (Apple Silicon) using curl and makes it executable.

```bash
curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos && chmod a+x ./lightpanda
```

--------------------------------

### Homebrew Installation (macOS)

Source: https://agent-browser.dev/installation

Installs agent-browser using Homebrew on macOS. Requires running 'agent-browser install' to download Chrome.

```bash
brew install agent-browser
agent-browser install  # Download Chrome (first time)
```

--------------------------------

### Linux Dependencies Installation

Source: https://agent-browser.dev/installation

Installs agent-browser on Linux, including necessary system dependencies.

```bash
agent-browser install --with-deps
```

--------------------------------

### Start, Stop, and Restart Video Recording

Source: https://agent-browser.dev/commands

Begin recording the browser's video output to a WebM file, stop the current recording, or stop and immediately start a new one.

```bash
agent-browser record start <path>     # Start video recording (WebM)
agent-browser record stop             # Stop and save video
agent-browser record restart <path>   # Stop current and start new recording
```

--------------------------------

### Setup Browser Use with API Key

Source: https://agent-browser.dev/providers/browser-use

Export your Browser Use API key and use the agent-browser command with the -p flag to specify the browseruse provider.

```bash
export BROWSER_USE_API_KEY="your-api-key"
agent-browser -p browseruse open https://example.com
```

--------------------------------

### Install Agent Browser Skill

Source: https://agent-browser.dev/installation

Install the agent-browser skill for your AI coding assistant using npx. This command fetches the skill from the repository and ensures it stays up-to-date.

```bash
npx skills add vercel-labs/agent-browser
```

--------------------------------

### Diagnose Installation

Source: https://agent-browser.dev/commands

Commands to diagnose installation issues, clean stale daemon files, and optionally repair common problems. Provides full diagnosis or quick local-only checks.

```bash
agent-browser doctor                     # Full diagnosis (env, Chrome, daemons, config, providers, network, launch test)
agent-browser doctor --offline --quick   # Local-only, fastest
agent-browser doctor --fix               # Also run destructive repairs (reinstall Chrome, purge old state, ...)
agent-browser doctor --json              # Structured JSON output for agents
```

--------------------------------

### Cargo Installation (Rust)

Source: https://agent-browser.dev/installation

Installs agent-browser from source using Cargo, the Rust package manager. Requires Node.js 24+, pnpm 11+, and the Rust toolchain. Also requires running 'agent-browser install' to download Chrome.

```bash
cargo install agent-browser
agent-browser install  # Download Chrome (first time)
```

--------------------------------

### Agent Browser Snapshot Output Example

Source: https://agent-browser.dev/snapshots

Shows the default compact text output format for the agent-browser snapshot command, including element references, types, and names.

```bash
agent-browser snapshot -i
# Output:
# @e1 [heading] "Example Domain" [level=1]
# @e2 [button] "Submit"
# @e3 [input type="email"] placeholder="Email"
# @e4 [link] "Learn more"
```

--------------------------------

### Verify Appium Installation

Source: https://agent-browser.dev/ios

Confirm that Appium is installed globally and the XCUITest driver is available. This helps troubleshoot 'Appium not found' errors.

```bash
# Make sure Appium is installed globally
npm install -g appium
appium driver install xcuitest

# Verify installation
appium --version
```

--------------------------------

### Setup Browser Use with Environment Variable

Source: https://agent-browser.dev/providers/browser-use

For CI/CD or scripts, set AGENT_BROWSER_PROVIDER to browseruse and export your API key. The agent-browser command will then connect to the cloud session.

```bash
export AGENT_BROWSER_PROVIDER=browseruse
export BROWSER_USE_API_KEY="your-api-key"
agent-browser open https://example.com
```

--------------------------------

### Local Project Installation

Source: https://agent-browser.dev/installation

Installs agent-browser as a local dependency for a specific project, allowing version pinning in package.json. Requires running 'agent-browser install' to download Chrome.

```bash
npm install agent-browser
npx agent-browser install  # Download Chrome (first time)
```

--------------------------------

### Start and Stop Traces

Source: https://agent-browser.dev/commands

Initiate a trace to record browser activity and stop it to save the trace data to a specified file path.

```bash
agent-browser trace start             # Start trace
agent-browser trace stop [path]       # Stop and save trace
```

--------------------------------

### Get All Skill Content

Source: https://agent-browser.dev/skills

Outputs the content for every available skill. This can be useful for a comprehensive overview or backup.

```bash
agent-browser skills get --all
```

--------------------------------

### Start Chrome with Remote Debugging

Source: https://agent-browser.dev/sessions

Start Chrome with the `--remote-debugging-port` flag to enable Agent Browser to connect and import authentication state. Ensure Chrome is closed before using `--profile` if Chrome is already running.

```bash
# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222
```

```bash
# Linux
google-chrome --remote-debugging-port=9222
```

--------------------------------

### Start and Stop Profiling

Source: https://agent-browser.dev/commands

Begin Chrome DevTools profiling to analyze performance and stop it to save the profile data to a JSON file.

```bash
agent-browser profiler start          # Start Chrome DevTools profiling
agent-browser profiler stop [path]    # Stop and save profile (.json)
```

--------------------------------

### Snapshot Diff Output Example

Source: https://agent-browser.dev/diffing

Illustrates the output format for snapshot diffing, showing added lines with '+' and removed lines with '-'. Includes a summary of changes.

```text
- button "Submit" [ref=e2]
+ button "Submit" [ref=e2] [disabled]
  3 additions, 2 removals, 41 unchanged
```

--------------------------------

### JSON Output for Scripting

Source: https://agent-browser.dev/quick-start

Provides examples of how to obtain agent-browser output in JSON format for easier programmatic parsing in scripts.

```shell
agent-browser snapshot --json
```

```shell
agent-browser get text @e1 --json
```

--------------------------------

### Chrome Trace Event Format Example

Source: https://agent-browser.dev/profiler

This is an example of the JSON output format for performance profiles, compatible with Chrome DevTools and Perfetto. It includes trace events with timestamps, durations, and process/thread information.

```json
{
  "traceEvents": [
    {
      "cat": "devtools.timeline",
      "name": "RunTask",
      "ph": "X",
      "ts": 12345,
      "dur": 100,
      "pid": 1,
      "tid": 1
    }
  ],
  "metadata": {
    "clock-domain": "LINUX_CLOCK_MONOTONIC"
  }
}
```

--------------------------------

### Switch Tab, Snapshot, and Interact

Source: https://agent-browser.dev/commands

Switch to a specific tab, take a snapshot to get element references, and then interact with elements within that tab's context.

```bash
agent-browser tab docs          # switch first
agent-browser snapshot          # refs for docs
agent-browser click @e3         # uses docs's refs
```

--------------------------------

### Open a website with default Chrome engine

Source: https://agent-browser.dev/engines/chrome

Use this command when Chrome is installed and discoverable by Agent Browser. No engine flag is needed as Chrome is the default.

```bash
agent-browser open example.com
```

--------------------------------

### Enable AI Chat with API Key

Source: https://agent-browser.dev/dashboard

Enable the AI chat panel by setting the AI_GATEWAY_API_KEY environment variable before starting the dashboard.

```bash
export AI_GATEWAY_API_KEY=gw_your_key_here
agent-browser dashboard start
```

--------------------------------

### Using Snapshot Refs with Agent Browser Commands

Source: https://agent-browser.dev/snapshots

Illustrates how to use element references (@eN) obtained from snapshots to interact with elements using commands like 'click', 'fill', and 'get text'.

```bash
agent-browser click @e2      # Click the Submit button
agent-browser fill @e3 "a@b.com"  # Fill the email input
agent-browser get text @e1        # Get heading text
```

--------------------------------

### Get Specific Skill Content

Source: https://agent-browser.dev/skills

Outputs the full content of a specific skill. Use the `--full` flag to include references and templates alongside the skill content.

```bash
agent-browser skills get <name>
```

```bash
agent-browser skills get <name> --full
```

--------------------------------

### Add Runtime Init Script

Source: https://agent-browser.dev/init-scripts

Add an init script dynamically after the browser session has started. This script will affect future documents and navigations.

```bash
agent-browser addinitscript "window.__testMode = true"
```

--------------------------------

### Get Skill Filesystem Path

Source: https://agent-browser.dev/skills

Prints the filesystem path to a specific skill's directory. This can be helpful for debugging or manual inspection of skill files.

```bash
agent-browser skills path [name]
```

--------------------------------

### Launch Init Extensions from Command Line

Source: https://agent-browser.dev/init-scripts

Specify one or more local extension directories to be loaded when the browser launches. This requires a local Chromium-based browser.

```bash
agent-browser --extension ./extension open https://example.com
```

```bash
agent-browser --extension ./a --extension ./b open https://example.com
```

--------------------------------

### Start Profiling with Custom Categories

Source: https://agent-browser.dev/profiler

Initiate performance profiling with a specific set of trace categories to focus on particular aspects of browser execution, such as JavaScript V8 execution and user timing.

```bash
agent-browser profiler start --categories "devtools.timeline,v8.execute,blink.user_timing"
```

--------------------------------

### Chat Command Examples

Source: https://agent-browser.dev/commands

Use the 'chat' command for natural language control of the browser. It translates instructions into agent-browser commands and streams AI responses. Requires AI_GATEWAY_API_KEY. Options include interactive REPL, piped input, quiet mode, verbose mode, model override, and JSON output.

```bash
agent-browser chat "open google.com and search for cats"     # Single-shot instruction
```

```bash
agent-browser chat                                           # Interactive REPL (type quit to exit)
```

```bash
echo "summarize this page" | agent-browser chat              # Piped input
```

```bash
agent-browser -q chat "summarize this page"                  # Quiet: text only, no tool calls shown
```

```bash
agent-browser -v chat "fill in the login form"               # Verbose: show commands and their output
```

```bash
agent-browser --model openai/gpt-4o chat "take a screenshot" # Override the default AI model
```

```bash
agent-browser --json chat "open example.com"                 # Structured JSON output
```

--------------------------------

### Configure Browser Launch Arguments

Source: https://agent-browser.dev/changelog

Control browser startup behavior using the --args, --user-agent, and --proxy-bypass flags for fine-grained configuration.

```bash
agent-browser --args "--disable-gpu,--no-sandbox" open example.com
agent-browser --user-agent "Custom UA" open example.com
agent-browser --proxy-bypass "localhost,*.internal" open example.com
```

--------------------------------

### AgentCore Session Information

Source: https://agent-browser.dev/providers/agentcore

When a session starts, AgentCore provides a session ID and a Live View URL. Open the Live View URL in your browser to monitor the session in real time.

```text
Session: abc123-def456
Live View: https://us-east-1.console.aws.amazon.com/bedrock-agentcore/browser/aws.browser.v1/session/abc123-def456#
```

--------------------------------

### Launch Init Scripts from Command Line

Source: https://agent-browser.dev/init-scripts

Specify one or more init scripts to be executed when the browser launches. Ensure the daemon is closed if it's already running when changing these options.

```bash
agent-browser --init-script ./instrumentation.js open https://example.com
```

```bash
agent-browser --init-script ./a.js --init-script ./b.js open https://example.com
```

--------------------------------

### Launch Chrome with browser extensions

Source: https://agent-browser.dev/engines/chrome

Use the `--extension` flag followed by the path to the extension directory to load browser extensions.

```bash
agent-browser --extension <path> open example.com
```

--------------------------------

### Human-Readable Demo Recording with Waits

Source: https://agent-browser.dev/recording

Create video demos for human viewing by adding small waits between actions to show transitions and timing. This snippet also includes taking a screenshot.

```bash
agent-browser open https://shop.example.com
agent-browser record start ./checkout.webm
agent-browser wait 500
agent-browser click @e4
agent-browser wait 500
agent-browser screenshot ./screenshots/cart.png
agent-browser record stop
```

--------------------------------

### HAR Recording

Source: https://agent-browser.dev/commands

Commands to start and stop HAR (HTTP Archive) recording. Use 'har start' to begin recording and 'har stop' to save the HAR data to a file.

```bash
agent-browser network har start                # Start HAR recording
```

```bash
agent-browser network har stop [output.har]    # Stop and save HAR (temp path if omitted)
```

--------------------------------

### Open a website with a custom Chromium-based binary

Source: https://agent-browser.dev/engines/chrome

Specify the path to a custom Chromium-based browser executable using the `--executable-path` flag.

```bash
agent-browser --executable-path /path/to/chromium open example.com
```

--------------------------------

### Retrieve Chrome DevTools Protocol URL

Source: https://agent-browser.dev/changelog

Get the Chrome DevTools Protocol WebSocket URL for the active page using the 'get cdp-url' subcommand, useful for external debugging tools.

```bash
agent-browser get cdp-url
```

--------------------------------

### Set Up Request Routing and Navigate

Source: https://agent-browser.dev/network

Configure network routes to intercept or mock requests before navigating to a URL. Routes are applied before requests are sent, affecting the initial page load.

```bash
agent-browser open
agent-browser network route "**/analytics/**" --abort
agent-browser network route "**/api/users" --body '{"users":[]}'
agent-browser navigate https://app.example.com
```

--------------------------------

### Agent Browser Core Workflow

Source: https://agent-browser.dev/installation

Add this to your instructions file to use agent-browser for web automation. Run `agent-browser --help` for all commands. Follow the numbered steps for the core workflow.

```markdown
## Browser Automation

Use `agent-browser` for web automation. Run `agent-browser --help` for all commands.

Core workflow:
1. `agent-browser open <url>` - Navigate to page
2. `agent-browser snapshot -i` - Get interactive elements with refs (@e1, @e2)
3. `agent-browser click @e1` / `fill @e2 "text"` - Interact using refs
4. Re-snapshot after page changes
```

--------------------------------

### Start Network Traffic Capture

Source: https://agent-browser.dev/changelog

Initiate network traffic capture using the `agent-browser network har start` command. This command begins recording network requests and responses in HAR 1.2 format.

```bash
agent-browser network har start
```

--------------------------------

### Open URL with Custom Download Path

Source: https://agent-browser.dev/changelog

Opens a URL and specifies a custom directory for downloads.

```bash
agent-browser --download-path ./downloads open https://example.com
```

--------------------------------

### Compare Staging and Production Environments

Source: https://agent-browser.dev/diffing

Use the diff command with the --screenshot flag to compare two URLs, such as staging and production environments, to verify parity visually.

```bash
agent-browser diff url https://staging.example.com https://prod.example.com --screenshot
```

--------------------------------

### Launch Chrome with storage state

Source: https://agent-browser.dev/engines/chrome

Use the `--state` flag to specify a path for storing the browser's state.

```bash
agent-browser --state <path> open example.com
```

--------------------------------

### Get Information from Elements

Source: https://agent-browser.dev/commands

Retrieve text, HTML, attribute values, and other properties of elements. Use for inspecting page content.

```bash
agent-browser get text <sel>          # Get text content
agent-browser get html <sel>          # Get innerHTML
agent-browser get value <sel>         # Get input value
agent-browser get attr <sel> <attr>   # Get attribute
agent-browser get title               # Get page title
agent-browser get url                 # Get current URL
agent-browser get cdp-url             # Get CDP WebSocket URL
agent-browser get count <sel>         # Count matching elements
agent-browser get box <sel>           # Get bounding box
agent-browser get styles <sel>        # Get computed styles
```

--------------------------------

### Set Browserbase API Key and Open URL

Source: https://agent-browser.dev/providers/browserbase

Configure the Browserbase API key and open a URL using the agent-browser CLI. The `-p` flag specifies the provider.

```bash
export BROWSERBASE_API_KEY="your-api-key"
agent-browser -p browserbase open https://example.com
```

--------------------------------

### Update Agent Browser

Source: https://agent-browser.dev/installation

Upgrades agent-browser to the latest version. Automatically detects the installation method and applies the appropriate update command.

```bash
agent-browser upgrade
```

--------------------------------

### List All Available Skills

Source: https://agent-browser.dev/skills

Lists all available skills with their names and descriptions. This command is useful for discovering which skills are available for your agent.

```bash
agent-browser skills list
```

--------------------------------

### Open URL in iOS Simulator

Source: https://agent-browser.dev/ios

Launch Safari on a specified iPhone simulator and navigate to a given URL. Use the `-p ios` flag to enable iOS mode and `--device` to specify the simulator.

```bash
# Launch Safari on iPhone 16 Pro
agent-browser -p ios --device "iPhone 16 Pro" open https://example.com
```

--------------------------------

### Trigger Downloads and Wait for Completion

Source: https://agent-browser.dev/changelog

Use the download command to initiate file downloads and the wait command with the --download flag to monitor their completion.

```bash
agent-browser download @e1 ./file.pdf
agent-browser wait --download ./output.zip --timeout 30000
```

--------------------------------

### Permissive Action Policy Example

Source: https://agent-browser.dev/security

A permissive action policy that allows all actions by default but explicitly denies 'eval', 'download', and 'upload'.

```json
{
  "default": "allow",
  "deny": ["eval", "download", "upload"]
}
```

--------------------------------

### Navigate and Interact with a Website

Source: https://agent-browser.dev/

Open a website, take a snapshot of the page content, and interact with elements using their references. Finally, close the browser.

```bash
# Navigate and get snapshot
agent-browser open example.com
agent-browser snapshot -i

# Output:
# - heading "Example Domain" [ref=e1]
# - link "More information..." [ref=e2]

# Interact using refs
agent-browser click @e2
agent-browser screenshot page.png
agent-browser close
```

--------------------------------

### List Available iOS Simulators

Source: https://agent-browser.dev/ios

View all iOS simulators available on your system to select a target device for testing. This command helps identify the names and UDIDs of simulators.

```bash
agent-browser device list
```

--------------------------------

### Restrictive Action Policy Example

Source: https://agent-browser.dev/security

A restrictive action policy that denies all actions by default and explicitly allows a specific set of common actions.

```json
{
  "default": "deny",
  "allow": ["navigate", "snapshot", "click", "scroll", "wait", "get"]
}
```

--------------------------------

### Connect to Cloud Browser Provider

Source: https://agent-browser.dev/cdp-mode

Connect to a cloud browser provider using the -p flag instead of launching a local browser. Ensure the provider is configured.

```bash
agent-browser -p browserbase open https://example.com
```

--------------------------------

### Console Event WebSocket Message

Source: https://agent-browser.dev/dashboard

Example of a WebSocket message sent when the browser logs to the console. Includes level, text, arguments, and timestamp.

```json
{
  "type": "console",
  "level": "log",
  "text": "Page loaded",
  "args": [{"type": "string", "value": "Page loaded"}],
  "timestamp": 1711367000100
}
```

--------------------------------

### Result Event WebSocket Message

Source: https://agent-browser.dev/dashboard

Example of a WebSocket message sent when a command finishes. Includes success status, data, duration, and timestamp.

```json
{
  "type": "result",
  "id": "r123",
  "action": "click",
  "success": true,
  "data": {},
  "duration_ms": 45,
  "timestamp": 1711367000045
}
```

--------------------------------

### Using Traditional Selectors

Source: https://agent-browser.dev/quick-start

Illustrates how to use CSS selectors and semantic locators for interacting with web elements.

```shell
agent-browser click "#submit"
agent-browser fill "#email" "test@example.com"
agent-browser find role button click --name "Submit"
```

--------------------------------

### Command Event WebSocket Message

Source: https://agent-browser.dev/dashboard

Example of a WebSocket message sent when a command begins executing. Includes action, ID, parameters, and timestamp.

```json
{
  "type": "command",
  "action": "click",
  "id": "r123",
  "params": { "selector": "@e5" },
  "timestamp": 1711367000000
}
```

--------------------------------

### Run Doctor Diagnostics

Source: https://agent-browser.dev/installation

Diagnoses the agent-browser installation and cleans stale daemon files. Provides options for offline, quick, fix, and JSON output.

```bash
agent-browser doctor                     # Full diagnosis
agent-browser doctor --offline --quick   # Local-only, fastest (~<1s)
agent-browser doctor --fix               # Also run destructive repairs
agent-browser doctor --json              # Structured output
```

--------------------------------

### Trigger and Wait for Downloads

Source: https://agent-browser.dev/commands

Use 'agent-browser download' to click an element and initiate a download. Use 'agent-browser wait --download' to pause execution until any download is complete. Downloads can be directed to a specific path using '--download-path' or the AGENT_BROWSER_DOWNLOAD_PATH environment variable.

```bash
agent-browser download <sel> <path>   # Click element to trigger download
```

```bash
agent-browser wait --download [path]  # Wait for any download to complete
```

--------------------------------

### Manage Dashboard Server

Source: https://agent-browser.dev/commands

Commands to start, specify a port for, or stop the agent-browser dashboard server. The dashboard can be accessed via localhost or a proxied URL.

```bash
agent-browser dashboard [start]       # Start the dashboard server (default port: 4848)
agent-browser dashboard start --port <n>  # Start on a specific port
agent-browser dashboard stop          # Stop the dashboard server
```

--------------------------------

### Extract Computed Styles from Elements

Source: https://agent-browser.dev/changelog

Retrieve the computed CSS styles of elements using the get styles command, specifying the target element with a selector.

```bash
agent-browser get styles "button"
```

--------------------------------

### Connect to Browserless.io Provider

Source: https://agent-browser.dev/changelog

Configure and use the browserless.io provider for remote browser instances. Set the API key via environment variable or command flag.

```bash
export BROWSERLESS_API_KEY="your-api-key"
agent-browser --provider browserless open example.com
agent-browser --provider browserless screenshot ./page.png
```

--------------------------------

### WebSocket Touch Input Events

Source: https://agent-browser.dev/streaming

Send touch events to the WebSocket server for mobile-like interactions, including touch start, move, end, and multi-touch gestures.

```json
// Touch start
{
  "type": "input_touch",
  "eventType": "touchStart",
  "touchPoints": [{ "x": 100, "y": 200 }]
}
```

```json
// Touch move
{
  "type": "input_touch",
  "eventType": "touchMove",
  "touchPoints": [{ "x": 150, "y": 250 }]
}
```

```json
// Touch end
{
  "type": "input_touch",
  "eventType": "touchEnd",
  "touchPoints": []
}
```

```json
// Multi-touch (pinch zoom)
{
  "type": "input_touch",
  "eventType": "touchStart",
  "touchPoints": [
    { "x": 100, "y": 200, "id": 0 },
    { "x": 200, "y": 200, "id": 1 }
  ]
}
```

--------------------------------

### Init Script Registration

Source: https://agent-browser.dev/commands

Commands for registering initialization scripts. '--init-script' registers a script before the first navigation, while 'addinitscript' registers one at runtime.

```bash
agent-browser open --init-script <path>           # Register before first navigation (repeatable)
```

```bash
agent-browser addinitscript <js>                  # Register at runtime (returns identifier)
```

```bash
agent-browser removeinitscript <identifier>       # Remove a previously registered init script
```

--------------------------------

### Take and Compare Snapshots

Source: https://agent-browser.dev/diffing

Use snapshots to verify that agent actions like clicks or fills have changed the page as expected. The first command takes an interactive-only baseline snapshot.

```bash
agent-browser snapshot -i          # Take interactive-only snapshot (baseline)
```

```bash
agent-browser fill @e3 "test@example.com"
```

```bash
agent-browser diff snapshot        # Compare current snapshot to the baseline
```

--------------------------------

### Enable Built-in React DevTools

Source: https://agent-browser.dev/init-scripts

Use the --enable react-devtools flag to automatically install the React DevTools hook. This is required for various React debugging commands.

```bash
agent-browser --enable react-devtools open http://localhost:3000
```

--------------------------------

### Record Browser Sessions to Video

Source: https://agent-browser.dev/changelog

Record browser activity to a WebM file using the record start and stop commands, integrating with Playwright's native recording.

```bash
agent-browser record start ./demo.webm
agent-browser click @e1
agent-browser record stop
```

--------------------------------

### Set Download Path

Source: https://agent-browser.dev/changelog

Specify a default download directory using the --download-path flag, AGENT_BROWSER_DOWNLOAD_PATH environment variable, or downloadPath config key.

```bash
agent-browser --download-path "/path/to/downloads" open example.com
```

--------------------------------

### Configure Screenshot Settings

Source: https://agent-browser.dev/changelog

Set persistent screenshot directory, quality, and format using global flags or environment variables.

```bash
agent-browser screenshot --screenshot-dir ./shots
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
```

--------------------------------

### Waiting Strategies

Source: https://agent-browser.dev/quick-start

Demonstrates various methods for pausing execution until specific conditions are met, such as element visibility, network activity, URL changes, or a fixed duration.

```shell
agent-browser wait @e1                   # Wait for element
agent-browser wait --load networkidle    # Wait for network idle
agent-browser wait --url "**/dashboard"  # Wait for URL pattern
agent-browser wait 2000                  # Wait milliseconds
```

--------------------------------

### Auto-Connect to Running Chrome Instance

Source: https://agent-browser.dev/cdp-mode

Automatically discover and connect to a running Chrome instance without specifying a port. This is useful for dynamic port assignments or zero-configuration setups.

```bash
# Auto-discover running Chrome with remote debugging
agent-browser --auto-connect open example.com
agent-browser --auto-connect snapshot

# Or via environment variable
AGENT_BROWSER_AUTO_CONNECT=1 agent-browser snapshot
```

--------------------------------

### Get Device UDID using system_profiler

Source: https://agent-browser.dev/ios

Alternatively, obtain the UDID of connected iOS devices by inspecting USB data through the `system_profiler` command. This is useful if `xcrun` is not available or preferred.

```bash
# Or via system profiler
system_profiler SPUSBDataType | grep -A 5 "iPhone\|iPad"
```

--------------------------------

### Use Lightpanda Engine via CLI Flag

Source: https://agent-browser.dev/engines/lightpanda

Demonstrates how to specify Lightpanda as the browser engine directly in the agent-browser command line.

```bash
agent-browser --engine lightpanda open example.com
```

```bash
agent-browser --engine lightpanda snapshot
```

```bash
agent-browser --engine lightpanda screenshot
```

--------------------------------

### Get Snapshot with References in iOS

Source: https://agent-browser.dev/ios

Capture a snapshot of the current page in the iOS simulator, including element references for later interaction. The `-i` flag enables reference generation.

```bash
# Get snapshot with refs (same as desktop)
agent-browser -p ios snapshot -i
```

--------------------------------

### Pass custom launch arguments to Chrome

Source: https://agent-browser.dev/engines/chrome

Use the `--args` flag followed by a space-separated list of arguments to pass custom launch arguments to Chrome.

```bash
agent-browser --args "--no-sandbox" open example.com
```

--------------------------------

### Capture Chrome Trace Events

Source: https://agent-browser.dev/debugging

Start and stop Chrome DevTools trace capture to save performance data. The trace is saved to a JSON file, with an auto-generated name if no path is specified.

```bash
agent-browser trace start

agent-browser open https://example.com
agent-browser click @e3

agent-browser trace stop ./trace.json
```

--------------------------------

### Enable Native Rust Daemon

Source: https://agent-browser.dev/changelog

Enable the experimental native Rust daemon using the --native flag, the AGENT_BROWSER_NATIVE environment variable, or by setting "native": true in the agent-browser.json configuration file.

```bash
# Via flag
agent-browser --native open example.com

# Via environment variable
export AGENT_BROWSER_NATIVE=1
agent-browser open example.com
```

```json
{"native": true}
```

--------------------------------

### Open URL on Real iOS Device

Source: https://agent-browser.dev/ios

Control Safari on a real iOS device connected via USB by specifying its UDID or device name. This requires WebDriverAgent to be signed and installed on the device.

```bash
# Connect device via USB, then use the UDID
agent-browser -p ios --device "<DEVICE_UDID>" open https://example.com

# Or use the device name if unique
agent-browser -p ios --device "John's iPhone" open https://example.com
```

--------------------------------

### Open URL with Kernel Environment Variables

Source: https://agent-browser.dev/providers/kernel

Configure agent-browser to use Kernel by setting environment variables for CI/scripts. The AGENT_BROWSER_PROVIDER must be set to 'kernel'.

```bash
export AGENT_BROWSER_PROVIDER=kernel
export KERNEL_API_KEY="your-api-key"
agent-browser open https://example.com
```

--------------------------------

### Configure Browser Proxy

Source: https://agent-browser.dev/changelog

Set up a browser proxy, including optional authentication, using the --proxy flag for network traffic control.

```bash
agent-browser --proxy http://user:pass@proxy.com:8080 open example.com
```

--------------------------------

### Build Dashboard

Source: https://agent-browser.dev/dashboard

Build the Next.js static export for the dashboard using pnpm.

```bash
pnpm build:dashboard
```

--------------------------------

### Enable Session Persistence with Agent Browser

Source: https://agent-browser.dev/sessions

Automatically save and restore cookies and localStorage across browser restarts using `--session-name`. State files are stored in `~/.agent-browser/sessions/` and loaded on daemon start.

```bash
# Auto-save/load state for "twitter" session
agent-browser --session-name twitter open twitter.com
```

```bash
# Login once, then state persists automatically
agent-browser --session-name twitter click "#login"
```

```bash
# Or via environment variable
export AGENT_BROWSER_SESSION_NAME=twitter
agent-browser open twitter.com
```

--------------------------------

### Start and Stop HAR Export

Source: https://agent-browser.dev/network

Begin capturing network traffic for HAR export, perform browser actions, and then stop the capture to save the HAR file. HAR files can contain sensitive information.

```bash
agent-browser network har start

agent-browser open https://app.example.com
agent-browser click @e4

agent-browser network har stop ./trace.har
```

--------------------------------

### Get Device UDID using xcrun

Source: https://agent-browser.dev/ios

Retrieve the Unique Device Identifier (UDID) for connected iOS devices using the `xcrun xctrace list devices` command. This is necessary for controlling real devices.

```bash
# List connected devices
xcrun xctrace list devices
```

--------------------------------

### Manage State

Source: https://agent-browser.dev/commands

Commands for saving, loading, listing, showing, renaming, clearing, and cleaning authentication states from files.

```bash
agent-browser state save <path>       # Save auth state to file
agent-browser state load <path>       # Load auth state from file
agent-browser state list              # List saved state files
agent-browser state show <file>       # Show state summary
agent-browser state rename <old> <new> # Rename state file
agent-browser state clear [name]      # Clear states for session name
agent-browser state clear --all       # Clear all saved states
agent-browser state clean --older-than <days>  # Delete old states
```

--------------------------------

### Debug SSR and No-JavaScript with Batch Commands

Source: https://agent-browser.dev/network

Utilize batch commands to configure network routes, such as aborting scripts, before navigating to a local development server. This setup is useful for debugging SSR or environments without JavaScript.

```bash
agent-browser batch \
  '["open"]' \
  '["network","route","*","--abort","--resource-type","script"]' \
  '["navigate","http://localhost:3000"]' \
  '["snapshot","-i"]'
```

--------------------------------

### Configure Launch Init Scripts with Environment Variable

Source: https://agent-browser.dev/init-scripts

Set the AGENT_BROWSER_INIT_SCRIPTS environment variable to a comma-separated list of init scripts. This is an alternative to using command-line arguments.

```bash
export AGENT_BROWSER_INIT_SCRIPTS="./a.js,./b.js"
agent-browser open https://example.com
```

--------------------------------

### Launch Chrome with persistent profiles

Source: https://agent-browser.dev/engines/chrome

Use the `--profile` flag to specify a path for persistent user data, which sets Chrome's `--user-data-dir`.

```bash
agent-browser --profile <path> open example.com
```