---
title: "Commands"
description: "Browser automation CLI for AI agents"
canonical_url: "https://agent-browser.dev/commands"
---

# Commands

## Core

```bash
agent-browser open                    # Launch browser (no nav); stays on about:blank
agent-browser open <url>              # Launch + navigate (aliases: goto, navigate)
agent-browser read [url]              # Fetch agent-readable text, or read rendered active-tab DOM
agent-browser click <sel>             # Click element (--new-tab to open in new tab)
agent-browser dblclick <sel>          # Double-click
agent-browser fill <sel> <text>       # Clear and fill
agent-browser type <sel> <text>       # Type into element
agent-browser press <key>             # Press key (Enter, Tab, Control+a) (alias: key)
agent-browser keyboard type <text>    # Type at current focus (no selector needed)
agent-browser keyboard inserttext <text>  # Insert text without key events
agent-browser keydown <key>           # Hold key down
agent-browser keyup <key>             # Release key
agent-browser hover <sel>             # Hover element
agent-browser focus <sel>             # Focus element
agent-browser select <sel> <val>      # Select dropdown by value or visible label
agent-browser check <sel>             # Check checkbox
agent-browser uncheck <sel>           # Uncheck checkbox
agent-browser scroll <dir> [px]       # Scroll (up/down/left/right, --selector <sel>)
agent-browser scrollintoview <sel>    # Scroll element into view
agent-browser drag <src> <dst>        # Drag and drop
agent-browser upload <sel> <files>    # Upload files
agent-browser screenshot [path]       # Screenshot (--full for full page)
agent-browser screenshot --annotate   # Annotated screenshot with numbered element labels
agent-browser screenshot --if-changed # Recommended: skip unchanged images to save tokens
agent-browser screenshot --threshold 0.01 # Ignore changes affecting at most 1% of pixels
agent-browser screenshot --screenshot-dir ./shots    # Save to custom directory
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf <path>              # Save page as PDF
agent-browser snapshot                # Accessibility tree with refs
agent-browser eval <js>               # Run JavaScript
agent-browser connect <port|url>      # Connect to browser via CDP
agent-browser stream enable [--port <port>]  # Start runtime WebSocket streaming
agent-browser webmcp list                     # List experimental page tools
agent-browser webmcp invoke <tool> --params @input.json
agent-browser stream status           # Show runtime streaming state and bound port
agent-browser stream disable          # Stop runtime WebSocket streaming
agent-browser close                   # Close browser (aliases: quit, exit)
agent-browser close --all             # Close all active sessions
agent-browser mcp                     # Start an MCP stdio server
```

Browser responses automatically announce WebMCP tools on first discovery and when the catalog changes. Summaries contain only names, brief descriptions, origins, and frame IDs. Choose a relevant tool, then fetch its full schema with `agent-browser webmcp list <tool> --frame <frame-id> --json` before invoking it. Schemas and annotations are never included proactively. Unchanged catalogs and pages without tools add no context. JSON exposes updates as `data.webmcp`; CLI and MCP text include the same bounded summary. See [WebMCP](/webmcp) for update semantics and security.

Clicks fail before dispatch when another element covers the target's click point. The error names the covering element, for example `covered by <div#consent-banner>`. Dismiss or interact with that element, take a fresh snapshot, then retry the original action. Click and dblclick fail, instead of reporting success, when the element is hidden, disabled, or outside the viewport. `click --new-tab` opens the link's URL directly, so these checks do not apply to it.

Headless Chromium screenshots hide native scrollbars for consistent image output. Pass `--hide-scrollbars false` when launching to keep native scrollbars visible.

## Get info

```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
```

## Read agent-friendly text

```bash
agent-browser read
agent-browser read https://example.com/article
agent-browser read https://example.com/article --filter overview
agent-browser read https://example.com/article --outline
agent-browser read https://docs.example.com --llms index --filter auth
agent-browser read https://docs.example.com --llms full --filter auth
agent-browser read example.com/article --require-md
agent-browser read https://example.com/article --json
```

`read` fetches a URL without launching Chrome. Omit the URL to read the rendered DOM of the active tab in the current browser session, including browser auth state and client-side updates. Explicit URL reads send `Accept: text/markdown` by default, try the same URL with `.md` appended when the first response is not markdown, walk ancestor paths toward `/` to find the nearest `llms.txt` for a matching docs link, print markdown or plain text when available, and fall back to readable text extracted from HTML. `--llms` and `--require-md` with no URL use the active tab URL because they depend on HTTP resources. `read` does not read `llms-full.txt` unless you ask for it.

Options: `--raw` prints the response body without HTML extraction, `--require-md` fails unless the server returns `Content-Type: text/markdown`, `--outline` prints a compact heading outline for one page, `--llms index` prints a compact nearest-ancestor `llms.txt` link list, `--llms full` reads the nearest-ancestor `llms-full.txt`, `--filter <text>` narrows page sections, llms links/sections, or outline headings, and `--timeout <ms>` changes the request timeout. Global safeguards such as `--allowed-domains`, `--content-boundaries`, and `--max-output` also apply to read fetches and output.

## Check state

```bash
agent-browser is visible <sel>        # Check if visible
agent-browser is enabled <sel>        # Check if enabled
agent-browser is checked <sel>        # Check if checked
```

## Find elements

Semantic locators with actions (`click`, `fill`, `check`, `hover`, `text`):

```bash
agent-browser find role <role> <action> [value]
agent-browser find text <text> <action> [value]
agent-browser find label <label> <action> [value]
agent-browser find placeholder <ph> <action> [value]
agent-browser find alt <text> <action> [value]
agent-browser find title <text> <action> [value]
agent-browser find testid <id> <action> [value]
agent-browser find first <sel> <action> [value]
agent-browser find last <sel> <action> [value]
agent-browser find nth <n> <sel> <action> [value]
```

Options:

- `--name <name>`: filter role by accessible name
- `--exact`: exact, case-sensitive match. For `role` it applies to the accessible name, whose default is a case-insensitive substring.

Examples:

```bash
agent-browser find role button click --name "Submit"
agent-browser find role heading text --name "Skills"     # implicit roles work: <h2>=heading, <ul>=list, top-level <header>=banner
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
```

## Wait

```bash
agent-browser wait <selector>         # Wait for element
agent-browser wait <ms>               # Wait for time
agent-browser wait --text "Welcome"   # Wait for text (substring match)
agent-browser wait --url "**/dash"    # Wait for URL pattern
agent-browser wait --load domcontentloaded # Wait for DOMContentLoaded
agent-browser wait --load load        # Wait for the load event
agent-browser wait --load networkidle # Use only for pages known to become quiet
agent-browser wait --fn "condition"   # Wait for JS condition
agent-browser wait --download [path]  # Wait for download
agent-browser wait --fn "!document.body.innerText.includes('Loading...')"  # Wait for text to disappear
agent-browser wait "#spinner" --state hidden           # Wait for element to disappear
```

After a page change, prefer a selector, text, URL, or JavaScript condition that represents the state you need. Use `networkidle` only when the page is known to become quiet, because SSE, WebSockets, polling, and long-polling can keep it from resolving.

## Downloads

```bash
agent-browser download <sel> <path>   # Click element to trigger download
agent-browser wait --download [path]  # Wait for any download to complete
```

Use `--download-path <dir>` (or `AGENT_BROWSER_DOWNLOAD_PATH` env) to set a default download directory. Without it, downloads go to a temporary directory that is deleted when the browser closes.

See [Files & Clipboard](/files) for upload, download, local file, screenshot, PDF, and clipboard workflows.

## Mouse

```bash
agent-browser mouse move <x> <y>      # Move mouse instantly
agent-browser mouse move 600 400 --duration 250 --steps 24
agent-browser mouse move 600 400 --human --seed 42
agent-browser mouse down [button]     # Press button
agent-browser mouse up [button]       # Release button
agent-browser mouse wheel <dy> [dx]   # Scroll wheel
```

Use `--human` with `click`, `drag`, or `mouse move` for curved, eased movement from the current cursor position. For `mouse move`, `--duration` sets the target total milliseconds including browser response time, `--steps` sets the number of events, and `--seed` makes the path reproducible. A slow browser can still extend the requested duration.

## Clipboard

```bash
agent-browser clipboard read                      # Read text from clipboard
agent-browser clipboard write "Hello, World!"     # Write text to clipboard
agent-browser clipboard copy                      # Copy current selection (Ctrl+C)
agent-browser clipboard paste                     # Paste from clipboard (Ctrl+V)
```

See [Files & Clipboard](/files) for clipboard, upload, download, local file, screenshot, and PDF workflows.

## Settings

```bash
agent-browser set viewport <w> <h> [scale]  # Set viewport size (scale for retina, e.g. 2)
agent-browser set device <name>       # Emulate device ("iPhone 14")
agent-browser set geo <lat> <lng>     # Set geolocation
agent-browser set offline [on|off]    # Toggle offline mode
agent-browser set headers <json>      # Extra HTTP headers
agent-browser set credentials <u> <p> # HTTP basic auth for current and future tabs
agent-browser set media [dark|light]  # Emulate color scheme (persists for session)
```

Use `--color-scheme` for persistent dark/light mode across all commands:

```bash
agent-browser --color-scheme dark open https://example.com
```

## Cookies & storage

```bash
agent-browser cookies                 # Get all cookies
agent-browser cookies set <name> <val> # 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

agent-browser storage session         # Same for sessionStorage
```

## Network

```bash
agent-browser network route <url>              # Intercept requests
agent-browser network route <url> --abort      # Block requests
agent-browser network route <url> --body <json>  # Mock response
agent-browser network route '*' --abort --resource-type script  # Block scripts only
agent-browser network unroute [url]            # Remove routes
agent-browser network requests                 # View tracked requests
agent-browser network requests --clear         # Clear request log
agent-browser network requests --filter <pat>  # Filter by URL pattern
agent-browser network requests --type xhr,fetch  # Filter by resource type
agent-browser network requests --method POST   # Filter by HTTP method
agent-browser network requests --status 2xx    # Filter by status (200, 2xx, 400-499)
agent-browser network request <requestId>      # View full request/response detail
agent-browser network har start                # Start HAR recording (embeds text response bodies)
agent-browser network har start --content all  # Embed all response bodies (binary as base64)
agent-browser network har start --content none # Metadata only, no bodies
agent-browser network har stop [output.har]    # Stop and save HAR (temp path if omitted)
```

See [Network](/network) for pre-navigation routing, request filters, HAR export, and SSR/no-JavaScript debugging.

## Tabs & frames

```bash
agent-browser tab                              # List tabs (each row shows tabId and label)
agent-browser tab new [url]                    # New tab
agent-browser tab new --label docs [url]       # New tab with a user-assigned label
agent-browser tab <t<N>|label>                 # Switch to a tab by id or label
agent-browser tab close [t<N>|label]           # Close a tab (defaults to active)
agent-browser window new                       # Open new browser window
agent-browser frame <sel>                      # Switch to iframe by CSS selector
agent-browser frame @e3                        # Switch to iframe by element ref
agent-browser frame main                       # Back to main frame
```

### Stable tab ids and labels

Tab ids are stable strings of the form `t1`, `t2`, `t3`. They're never reused within a session, so `t2` keeps pointing at the same tab even as other tabs are opened or closed. The `t` prefix mirrors the `@e1` element-ref convention and is not interchangeable with positional integers — `agent-browser tab 2` errors with a teaching message; use `t2`.

You can also assign a memorable label (`docs`, `app`, `admin`) at tab-creation time and use it anywhere an id is accepted:

```bash
agent-browser tab new --label docs https://docs.example.com
agent-browser tab docs          # switch to the docs tab
agent-browser snapshot          # populate refs for docs
agent-browser click @e3         # click uses docs's refs
agent-browser tab close docs    # close by label
```

Labels are never auto-generated and never rewritten on navigation — an agent that names a tab `docs` keeps that name until the tab is closed. Labels are unique within a session; creating a second tab with an existing label errors.

Tabs opened through `tab new` or `click --new-tab` inherit the session's setup before their first document loads: user agent, `set headers`, `set credentials`, origin-scoped `--headers`, init scripts, `route` rules, and emulation overrides (color scheme, timezone, locale, geolocation, offline). Turning offline mode off or setting headers to `{}` restores the default setup for future tabs.

`tab list --json` also reports each tab's CDP `targetId`, and target ids are accepted anywhere a tab ref is accepted (`tab <targetId>`, `tab close <targetId>`). Unlike `t<N>` ids, which are per-daemon counters, target ids stay stable across daemon restarts. Each session is bound to its active tab by target id and returns to it after a daemon restart; with `--pin-tab` the binding is strict and a closed bound tab produces a `tab_gone` error instead of a silent fallback. JSON errors include <code>code: "tab_gone"</code>, <code>data.targetId</code>, and optional sanitized <code>data.lastUrl</code>. Batch output carries the recovery object under <code>result</code>. See [CDP Mode](/cdp-mode) for the multi-session workflow.

Refs (`@e1`, etc.) are scoped to the tab that was active when the snapshot ran, so switch tabs first, then snapshot and interact:

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

### Discarded tab revival

Browsers discard background tabs to save memory, leaving a tab with no renderer to drive. Switching to a discarded tab reactivates it, which reloads the page and resets its unsaved state; the switch result adds `"revived": true` so the reload is visible rather than silent. A tab whose page is paused by a JavaScript dialog is alive rather than discarded: the switch leaves it untouched and adds `"dialogBlocked": true`. Resolve the dialog with `dialog accept` or `dialog dismiss` and the tab keeps its state. Closing the active tab onto a discarded successor revives it the same way and reports `"activeTabRevived": true`.

### Snapshot deltas

```bash
agent-browser snapshot --delta
agent-browser snapshot --delta --full
```

`snapshot --delta` returns `full`, `unchanged`, or incremental updates per tab and option set. URL changes or large deltas return full state; `--full` resets the baseline. Apply a delta’s `changes` to ref metadata and `treeChange` to the previous tree: split on newlines, replace `deleteCount` lines at zero-based `startLine` with `lines`, then rejoin. Apply both to `baseRevision` before advancing to `revision`.

### Iframe support

Iframes are detected automatically during snapshots. `Iframe` nodes are resolved and their content is inlined beneath the iframe element in the snapshot output. Refs assigned to elements inside iframes carry frame context, so `click`, `fill`, and other interactions work without manually switching frames.

```bash
agent-browser snapshot -i
# @e3 [Iframe] "payment-frame"
#   @e4 [input] "Card number"
#   @e5 [button] "Pay"

# Interact directly using refs — no frame switch needed
agent-browser fill @e4 "4111111111111111"
agent-browser click @e5

# Or switch frame context for scoped snapshots
agent-browser frame @e3
agent-browser snapshot -i             # Only elements inside that iframe
agent-browser frame main              # Return to main frame
```

The `frame` command accepts element refs (`@e3`), CSS selectors (`"#my-iframe"`), or frame name/URL.

## Dialogs

```bash
agent-browser dialog accept [text]    # Accept dialog (with optional prompt text)
agent-browser dialog dismiss          # Dismiss dialog
agent-browser dialog status           # Check if a dialog is currently open
```

By default, `alert` and `beforeunload` dialogs are automatically accepted so they never block the agent. `confirm` and `prompt` dialogs still require explicit handling. Use `--no-auto-dialog` (or `AGENT_BROWSER_NO_AUTO_DIALOG=1`) to disable automatic handling.

When a JavaScript dialog (`alert`, `confirm`, `prompt`) is pending, all command responses include a `warning` field with the dialog type and message.

## Streaming

```bash
agent-browser stream enable           # Start runtime WebSocket streaming on an auto-selected port
agent-browser stream enable --port 9223  # Bind a specific localhost port
agent-browser stream status           # Show enabled state, port, browser connection, screencasting
agent-browser stream disable          # Stop runtime streaming and remove the .stream metadata file
```

Streaming is enabled automatically for all sessions. Use these commands to check status, re-enable on a specific port, or disable streaming.

Streaming is separate from file-based recordings. Use [Video Recording](/recording) when you need a saved WebM or MP4 artifact.

## Debug

```bash
agent-browser trace start             # Start trace
agent-browser trace stop [path]       # Stop and save trace
agent-browser profiler start          # Start Chrome DevTools profiling
agent-browser profiler stop [path]    # Stop and save profile (.json)
agent-browser record start <path>     # Start video recording (.webm/.mp4, 30 fps; needs ffmpeg)
agent-browser record start <path> --fps 60  # Record at 60 fps (--fps accepts 1-60)
agent-browser record start <path> --cursor  # Include an animated mouse pointer
agent-browser record start <path> --contact-sheet # Also save a timestamped PNG summary
agent-browser record start <path> --contact-sheet-threshold 0.02 # Tune changed-frame selection
agent-browser record stop             # Stop and save video
agent-browser record restart <path>   # Stop current and start new recording
agent-browser console                 # View console messages
agent-browser console --json          # JSON output with raw CDP args
agent-browser console --clear         # Clear console log
agent-browser errors                  # View page errors
agent-browser errors --clear          # Clear error log
agent-browser highlight <sel>         # Highlight element
agent-browser inspect                 # Open Chrome DevTools for the active page
```

Recording requires `ffmpeg` on `PATH`. See [Debugging](/debugging) for console, error, dialog, trace, highlight, and DevTools workflows. See [Video Recording](/recording) for recording requirements and `record` workflows, and [Profiler](/profiler) for performance profiles.

## Auth vault

```bash
agent-browser auth save <name> [opts]    # Save auth profile
agent-browser auth login <name>          # Login using saved credentials
agent-browser auth login <name> --no-navigate
                                          # Use active page after origin validation
agent-browser auth login <name> --credential-provider <plugin> [--item <ref>] [--url <url>]
                                          # Resolve credentials from plugin
agent-browser auth login <name> --username-selector <s> --password-selector <s> [--submit-selector <s>]
                                          # Override selectors for one login
agent-browser auth list                  # List saved profiles (names and URLs only)
agent-browser auth show <name>           # Show profile metadata (no passwords)
agent-browser auth delete <name>         # Delete a saved profile
agent-browser plugin add <ref>           # Add a plugin from npm or GitHub
agent-browser plugin list                # List configured plugins
agent-browser plugin show <name>         # Show one configured plugin
agent-browser plugin run <name> <type> --payload <json>
                                          # Run an arbitrary plugin request
```

Save options:

- `--url <url>`: login page URL (required)
- `--username <user>`: username (required)
- `--password <pass>`: password (required unless `--password-stdin`)
- `--password-stdin`: read password from stdin (recommended to avoid shell history exposure)
- `--username-selector <sel>`: custom CSS selector for username field
- `--password-selector <sel>`: custom CSS selector for password field
- `--submit-selector <sel>`: custom CSS selector for submit button

`auth login` filters matching controls by their layout size, computed visibility and opacity, and disabled/readonly state, including custom CSS selectors. If a selected credential field is replaced or redirects focus before entry, the command fails without submitting.

`auth login` navigates with `load` and then waits for the username/password/submit selectors to appear before interacting. This improves reliability on SPA login pages where fields render after initial page load.

Use `--no-navigate` after an in-page click, challenge clearance, consent dismissal, or other stateful setup that must survive credential entry:

```bash
agent-browser open https://example.com/
agent-browser click "a[href='/login']"
agent-browser auth login work --no-navigate
```

The flag suppresses only the initial auth-login navigation. It requires an existing active top-level HTTP(S) page and compares that page with the effective credential URL by scheme, host, and effective port. Paths, queries, and fragments may differ. Waiting, filling, clicking submit, and any submit-triggered navigation are unchanged. A command-level `--url` overrides profile or provider URL metadata and acts as the expected-origin constraint rather than a navigation destination.

Plugin login options:

- `--credential-provider <plugin>`: resolve credentials from a configured plugin
- `--item <ref>`: provider-specific vault item reference
- `--url <url>`: login URL override
- `--no-navigate`: use the active top-level page after validating it against the effective credential origin
- `--username-selector <sel>`: selector override for this login
- `--password-selector <sel>`: selector override for this login
- `--submit-selector <sel>`: selector override for this login

Credential provider plugins run out-of-process over the `agent-browser.plugin.v1` stdio JSON protocol. They return credentials to the daemon for a single login and agent-browser does not save those credentials locally.

Other plugin capabilities use the same protocol:

- `browser.provider`: use the plugin with `--provider <name>` to return a CDP WebSocket URL
- `launch.mutate`: append local launch args, extensions, or init scripts before Chrome starts
- `command.run`: run arbitrary namespaced requests through `agent-browser plugin run`

`plugin run` is for `command.run` and custom capabilities. Core capabilities and protocol request types use their dedicated command paths.

```bash
echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin
agent-browser auth login github
agent-browser plugin add agent-browser-plugin-vault --name vault
agent-browser auth login my-app --credential-provider vault --item "My App"
agent-browser auth login my-app --credential-provider vault --item "My App" --no-navigate --url https://identity.example.com/login
agent-browser --provider cloud-browser open https://example.com
agent-browser plugin run captcha captcha.solve --payload '{"siteKey":"...","url":"https://example.com"}'
agent-browser auth list
```

## Confirmation

When `--confirm-actions` is set, certain action categories return a `confirmation_required` response instead of executing immediately. Use `confirm` or `deny` to approve or reject the action.

```bash
agent-browser confirm <confirmation-id>  # Approve a pending action
agent-browser deny <confirmation-id>     # Deny a pending action
```

Pending confirmations auto-deny after 60 seconds.

```bash
agent-browser --confirm-actions eval,download eval "document.title"
# Returns confirmation_required with ID
agent-browser confirm c_8f3a1234
```

## State management

```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
```

## Sessions

```bash
agent-browser session                 # Show current session name
agent-browser session list            # List active sessions
```

## Chrome profiles

```bash
agent-browser profiles               # List available Chrome profiles
agent-browser profiles --json        # List profiles as JSON
agent-browser --profile Default open https://gmail.com  # Reuse a profile's login state
```

## Dashboard

```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 start --allowed-origins <origins> # Allow exact HTTPS reverse-proxied browser origins
agent-browser dashboard stop          # Stop the dashboard server
```

Loopback dashboard origins are accepted by default without an access token. For a reverse-proxied or forwarded URL, pass its exact browser origin with `--allowed-origins` or set `AGENT_BROWSER_DASHBOARD_ALLOWED_ORIGINS`. Every configured origin must be a valid exact HTTPS origin. Ports must be integers from 1 to 65535. Unknown options, missing values, invalid ports, and malformed origins fail without starting the server. The command prints private tokenized access URLs only for external origins; open the matching URL once to establish the browser session and do not share it. Open the normal `http://localhost:<port>` URL for local access. The browser stays on the dashboard origin; per-session tabs, status, and stream traffic are proxied internally, so session ports do not need to be exposed. Stop the running dashboard before changing the port or allowed origins.

## Doctor

Diagnose your install, auto-clean stale daemon files, and optionally repair common problems.

```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 --webgpu            # Also run a live WebGPU render probe (see the WebGPU page)
agent-browser doctor --json              # Structured JSON output for agents
```

Exit code is `0` if all checks pass (warnings are fine), `1` if any fail. See the [Installation page](/installation#doctor) for the full check catalog.

## Chat

Use natural language to control the browser via AI. The `chat` command translates instructions into agent-browser commands, executes them, and streams the AI response. Requires `AI_GATEWAY_API_KEY` to be set.

```bash
agent-browser chat "open google.com and search for cats"     # Single-shot instruction
agent-browser chat                                           # Interactive REPL (type quit to exit)
echo "summarize this page" | agent-browser chat              # Piped input
agent-browser -q chat "summarize this page"                  # Quiet: text only, no tool calls shown
agent-browser -v chat "fill in the login form"               # Verbose: show commands and their output
agent-browser --model openai/gpt-4o chat "take a screenshot" # Override the default AI model
agent-browser --json chat "open example.com"                 # Structured JSON output
```

Chat-specific options:

```bash
--model <name>           # AI model (or AI_GATEWAY_MODEL env, default: anthropic/claude-sonnet-4.6)
-v, --verbose            # Show tool commands and their raw output
-q, --quiet              # Show only the AI text response (hide tool calls)
```

## Navigation

```bash
agent-browser back                    # Go back
agent-browser forward                 # Go forward
agent-browser reload                  # Reload page
agent-browser pushstate <url>         # SPA client-side nav; auto-detects window.next.router.push,
                                      # falls back to history.pushState + popstate
```

## Pre-navigation setup

Some flows need routes, cookies, or init scripts configured *before* the first navigation (SSR debug, auth on protected origins, etc.). `open` without a URL launches the browser but stays on `about:blank`, leaving room to stage state. `batch` makes it one CLI invocation:

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

## React / Web Vitals

React commands require `--enable react-devtools` at launch (installs the React DevTools hook before any page JS runs). `vitals` and `pushstate` work on any site.

```bash
agent-browser open --enable react-devtools <url>   # Launch with React hook installed
agent-browser react tree                           # Full component tree
agent-browser react inspect <fiberId>              # Inspect one component
agent-browser react renders start                  # Begin fiber render recording
agent-browser react renders stop [--json]          # Stop + print profile
agent-browser react suspense [--only-dynamic] [--json]  # Suspense boundaries + classifier
                                                         # --only-dynamic hides the "static" list
agent-browser vitals [url] [--json]                # LCP/CLS/TTFB/FCP/INP + hydration
```

Works on any React app (Next.js, Remix, Vite+React, CRA, TanStack Start, React Native Web, etc.). `vitals` and `pushstate` are framework-agnostic.

See [React & Web Vitals](/react) for full command details and examples.

## Accessibility audits

Run an embedded axe-core audit against the current page or navigate to a URL first. The vendored engine works without a CDN request and runs under strict page CSP. It runs private partial audits across the page's frame tree and merges serialized results without page messaging, so page-provided `window.axe` values remain intact and iframe violations retain their frame selector paths. Accessibility audits require a CDP browser and are not available with Safari or iOS WebDriver sessions.

```bash
agent-browser a11y                                 # Audit the current page
agent-browser a11y https://example.com             # Navigate, then audit
agent-browser a11y --tags wcag2a,wcag2aa           # Filter by axe rule tags
agent-browser a11y --selector "#main"              # Scope to a subtree
agent-browser a11y https://example.com --json      # Structured results
```

The default output lists violations and incomplete checks with impact, rule ID, fix guidance, and failing-node paths. JSON output preserves axe's `target` selector path arrays, including nested arrays for shadow DOM boundaries and multiple entries for frame boundaries.

## Init scripts

```bash
agent-browser open --init-script <path>           # Register before first navigation (repeatable)
agent-browser addinitscript <js>                  # Register at runtime (returns identifier)
agent-browser removeinitscript <identifier>       # Remove from every tab in the session
```

See [Init Scripts & Extensions](/init-scripts) for launch-time scripts, runtime scripts, built-in React DevTools, and extensions.

## Global options

```bash
--session <name>         # Isolated browser session
--restore [name]         # Auto-save/restore session state, defaults to --session
--restore-save <policy>  # Restore save policy: auto, always, never
--namespace <name>       # Isolate daemon sockets and restore-state directories
--profile <path>         # Persistent browser profile directory
--state <path>           # Load storage state from JSON file
--headers <json>         # HTTP headers scoped to URL's origin
--executable-path <path> # Custom browser executable
--extension <path>       # Load browser extension (repeatable)
--init-script <path>     # Register a page init script before first navigation (repeatable)
--enable <feature>       # Built-in init scripts: react-devtools (repeatable or comma-list)
--args <args>            # Browser launch args (commas inside a value are kept)
--user-agent <ua>        # Custom User-Agent string
--proxy <url>            # Proxy server URL
--proxy-bypass <hosts>   # Hosts to bypass proxy
--ignore-https-errors    # Ignore HTTPS certificate errors
--ca-cert <path>         # Trust a CA for CLI requests, and for local Chromium on Linux
--no-ca-cert             # Clear CA trust retained by the running session
--use-system-ca          # Use the OS trust store for CLI requests (read, install, upgrade, doctor)
--allow-file-access      # Allow file:// URLs to access local files (Chromium only)
--hide-scrollbars <bool> # Hide native scrollbars in headless Chromium screenshots
-p, --provider <name>    # Browser provider or configured provider plugin
--device <name>          # iOS device name (e.g., "iPhone 15 Pro")
--json                   # JSON output (for scripts)
--annotate               # Annotated screenshot with numbered element labels
--screenshot-dir <path>   # Default screenshot output directory (or AGENT_BROWSER_SCREENSHOT_DIR)
--screenshot-quality <n>  # JPEG quality 0-100 (or AGENT_BROWSER_SCREENSHOT_QUALITY)
--screenshot-format <fmt> # Format: png (default), jpeg (or AGENT_BROWSER_SCREENSHOT_FORMAT)
--headed                 # Show browser window (not headless)
--webgpu                 # Enable WebGPU (software Vulkan on Linux, no GPU needed)
--no-webmcp              # Disable default experimental WebMCP Chrome features (or AGENT_BROWSER_NO_WEBMCP env)
--cdp <port|url>         # Connect via CDP; root WebSocket query slash is optional
--auto-connect           # Auto-discover and connect to running Chrome
--color-scheme <scheme>  # Color scheme: dark, light, no-preference
--download-path <path>   # Default download directory
--content-boundaries     # Wrap page output in boundary markers for LLM safety
--max-output <chars>     # Truncate page output to N characters
--allowed-domains <list> # Allowed domains; rejects restore/state replay, profile/session startup args, and direct-page providers
--action-policy <path>   # Path to action policy JSON file
--confirm-actions <list> # Action categories requiring confirmation
--confirm-interactive    # Interactive confirmation prompts (auto-denies if stdin is not a TTY)
--engine <name>          # Browser engine: chrome (default), lightpanda, obscura (experimental)
--input-mode <mode>      # Pointer movement: instant (default), smooth, human
--idle-timeout <time>    # Auto-shutdown daemon after inactivity (default: 1h; 0 disables)
--no-auto-dialog         # Disable auto-accept for alert and beforeunload dialogs
--model <name>           # AI model for chat (or AI_GATEWAY_MODEL env)
-v, --verbose            # Show tool commands and their raw output (chat)
-q, --quiet              # Show only AI text responses (chat)
--config <path>          # Use a custom config file
--debug                  # Debug output
```

See [Configuration](/configuration) for config files and environment variables. See [Proxy](/proxy) for proxy server, bypass, and credential settings.

## Batch execution

Execute multiple commands in a single invocation. Commands can be passed as quoted arguments or piped as JSON via stdin.

```bash
# Argument mode: each quoted argument is a full command
agent-browser batch "open https://example.com" "snapshot -i" "screenshot"

# With --bail to stop on first error
agent-browser batch --bail "open https://example.com" "click @e1" "screenshot"

# Stdin mode: pipe commands as JSON
echo '[
  ["open", "https://example.com"],
  ["snapshot", "-i"],
  ["click", "@e1"],
  ["screenshot", "result.png"]
]' | agent-browser batch --json
```

<table>
  <thead>
    <tr><th>Option</th><th>Description</th></tr>
  </thead>
  <tbody>
    <tr><td><code>--bail</code></td><td>Stop on first error (default: continue all commands)</td></tr>
    <tr><td><code>--json</code></td><td>Output results as a JSON array</td></tr>
  </tbody>
</table>

## MCP server

```bash
agent-browser mcp
agent-browser mcp --tools all
agent-browser mcp --tools core,network,react
```

Starts a Model Context Protocol server over stdio. MCP clients launch this command as a subprocess and exchange newline-delimited JSON-RPC on stdin and stdout. The server defaults to MCP protocol 2025-11-25 and accepts older supported client protocol versions during initialization. A tool call with an argument its schema does not declare fails with an invalid-params error that names the unknown keys and lists the tool's own arguments.

The default tools profile is `core`, which keeps MCP context small for everyday browser automation. Use `--tools all` for the full typed CLI parity surface, or combine profiles with commas, such as `--tools core,network,react`.

Profiles:

- `core` - Default. Navigation, snapshots, interaction, waits, reads, screenshots, JavaScript eval, close, tab basics, and profile discovery
- `network` - Network routes, request inspection, HAR, headers, credentials, offline
- `state` - Cookies, storage, auth, saved state, sessions, profiles, skills
- `debug` - Console/errors, tracing, profiling, recording, accessibility audits, clipboard, plugins, doctor, dashboard, install, upgrade, chat, diff, batch, confirm/deny
- `tabs` - Back/forward/reload, tabs, windows, frames, dialogs
- `react` - React tree/inspect/renders/suspense, vitals, pushstate
- `mobile` - Viewport/device/geolocation/media, touch, swipe, mouse, keyboard
- `all` - Every MCP tool, including the full typed CLI parity surface

Example MCP client config:

```json
{
  "mcpServers": {
    "agent-browser": {
      "command": "agent-browser",
      "args": ["mcp"]
    }
  }
}
```

With `--tools all`, the server exposes typed tools across the CLI command surface, including navigation, snapshots, input, waits, screenshots/PDF, get/is/find, mouse, network, storage, cookies, tabs, windows, frames, dialogs, tracing, recording, accessibility audits, clipboard, auth, state, iOS, diff, React, vitals, sessions, skills, plugins, doctor, dashboard, install, upgrade, chat, eval, and close.

Common tools include:

- `agent_browser_tools_profiles`
- `agent_browser_open`
- `agent_browser_snapshot`
- `agent_browser_click`
- `agent_browser_fill`
- `agent_browser_type`
- `agent_browser_press`
- `agent_browser_wait_for_selector`
- `agent_browser_screenshot`
- `agent_browser_get_url`
- `agent_browser_eval`
- `agent_browser_close`

Each tool has typed fields such as `url`, `selector`, `text`, `key`, `session`, `allowedDomains`, and `idleTimeout`, so MCP clients show meaningful approval prompts instead of raw command arrays. The common `allowedDomains` array maps to `--allowed-domains` and activates the same WebRTC containment and launch-mode restrictions. The common `idleTimeout` string maps to `--idle-timeout`, accepts values such as `30s`, `5m`, `1h`, or raw milliseconds, and accepts `0` to disable idle shutdown. Each tool also accepts `extraArgs` for per-command options and display or emulation flags such as `--engine`, but global flags that change network, file, policy, or host access (such as `--allowed-domains`, `--action-policy`, `--executable-path`, `--args`, and `--config`) are rejected and must be set in the MCP server's environment or config. Tool discovery is paginated and includes read-only/open-world annotations so modern MCP clients can load the large typed surface incrementally.

Tool invocations use the same config files and environment variables as the CLI. Use `session` in the tool arguments, or set `AGENT_BROWSER_SESSION`, to isolate browser state.

## Command chaining

Chain commands with `&&` in a single shell invocation. The browser persists via a background daemon, so chaining works naturally and is more efficient than separate calls:

```bash
agent-browser open example.com && agent-browser wait --load domcontentloaded && agent-browser snapshot -i
agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "pass" && agent-browser click @e3
agent-browser open example.com && agent-browser wait --load load && agent-browser screenshot page.png
```

Use `&&` when you don't need to read intermediate output. Run commands separately when you need to parse output first (e.g., snapshot to discover refs, then interact with those refs).

## Local files

Open local files (PDFs, HTML) using `file://` URLs:

```bash
agent-browser --allow-file-access open file:///path/to/document.pdf
agent-browser --allow-file-access open file:///path/to/page.html
agent-browser screenshot output.png
```

The `--allow-file-access` flag enables JavaScript to access other local files. Chromium only.

See [Files & Clipboard](/files) for local files, uploads, downloads, screenshots, PDFs, and clipboard workflows.