agent-browser

Commands

Core

Unknown commands exit with status 1, including when you request command help.

When the top-level Chrome/CDP eval result is a value JSON cannot represent, plain output prints its exact JavaScript token, including NaN, Infinity, -Infinity, -0, BigInt literals, and undefined. With --json, data.result stays null and sibling data.unserializable contains the token. MCP text prints the token, and structured responses expose it at structuredContent.response.data.unserializable.

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
agent-browser mcp call <tool> <json>  # Run one MCP tool and print its result

For fill and type, put options before the optional -- marker. Text after the marker is literal, including values that look like flags. For example, agent-browser fill "#search" -- --json fills with --json, and agent-browser --json type "#search" --clear --delay 10 -- --clear clears the field, then types --clear. MCP agent_browser_fill and agent_browser_type pass typed text values literally, so they do not need the marker.

select works on a native <select> and on a custom ARIA combobox or listbox, such as Radix or Headless UI. On a custom widget it opens the widget, then clicks the role=option whose name or value matches. A value with no match is an error that lists the available options, a matched option marked aria-disabled is an error instead of a click, and an option already selected in a multi-select listbox is left alone.

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

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

get cdp-url reports the CDP WebSocket URL of a browser that is already running. It requires a running browser and never launches one. A batch containing only get cdp-url commands also skips browser launch. A mixed batch can launch a browser for its other commands.

Read agent-friendly text

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

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):

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:

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 "[email protected]"
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

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

For selector waits, --state accepts visible, hidden, attached, or detached and cannot be combined with URL, load, function, text, download, or millisecond wait modes. The global auth-state --state <path> remains available before wait, as it does before other commands.

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.

A load-state wait runs for its whole timeout budget, taken from --timeout or AGENT_BROWSER_DEFAULT_TIMEOUT, and returns an error when it expires.

Downloads

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

wait --download returns the oldest download not yet claimed by an earlier wait, including one that finished before the command ran, so it can follow the command that triggered it. With [path], the file is moved there; without it, the output is where the browser saved it. Saving to a local path only applies to a browser agent-browser launched: over --cdp, --auto-connect, or a provider, the saved file is named by the remote endpoint, so download and wait --download [path] are rejected.

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 for upload, download, local file, screenshot, PDF, and clipboard workflows.

Mouse

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

The wheel scrolls at the current tracked pointer, which starts at 0,0. Failed wheel dispatches leave the tracked pointer unchanged.

Mouse coordinates and wheel deltas accept finite decimal values; invalid supplied values are rejected. For mouse wheel, omitted dy and dx default to 100 and 0, respectively, and explicit 0 values are preserved.

To scroll elsewhere, move the pointer first:

agent-browser mouse move 600 400
agent-browser mouse wheel 100

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

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 for clipboard, upload, download, local file, screenshot, and PDF workflows.

Settings

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)

Viewport scales and geolocation coordinates must be finite numbers.

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

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

Cookies & storage

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

Reads accept at most one key, sets require one key and one value, and clears take no operands. A bare key is shorthand for a one-key read.

Cookie operations are get (the default), set, and clear; unknown operations return an error. Cookie attributes use kebab-case flags such as --http-only and --same-site. The legacy --httpOnly and --sameSite spellings remain accepted. When setting one cookie, unknown flags and extra arguments return an error.

agent-browser cookies set session_id abc123 --http-only --same-site Strict

Network

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 <url> --body <json> --allow-origin <origin>  # Mock readable cross-origin
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)

If HAR export fails, recording and captured requests remain available. Fix the destination and retry network har stop.

See Network for pre-navigation routing, request filters, HAR export, and SSR/no-JavaScript debugging.

Tabs & frames

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:

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.

A label starts with a letter and contains only letters, digits, -, or _, and cannot use the reserved t<N> or T<N> tab-id form. Rejected labels preserve the current tab's refs and selected frame.

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: "tab_gone", data.targetId, and optional sanitized data.lastUrl. Batch output carries the recovery object under result. See 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:

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

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.

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

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

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 when you need a saved WebM or MP4 artifact.

Debug

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 for console, error, dialog, trace, highlight, and DevTools workflows. See Video Recording for recording requirements and record workflows, and Profiler for performance profiles.

Auth vault

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:

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.

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.

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.

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

State management

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

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

Session names accept Unicode letters and numbers, hyphens, and underscores only. For example, café-東京_7 is valid, while my session is rejected because it contains a space.

Chrome profiles

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

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.

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

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:

--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)
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:

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.

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

react tree prints the component tree when one is available. If the response contains only a header, no tree was collected. Confirm the page uses React and that a React root has mounted.

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

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

agent-browser --init-script <path> open <url>  # Register before first navigation (repeatable)
agent-browser removeinitscript <identifier>

See Init Scripts & Extensions for launch-time scripts, script removal, built-in React DevTools, and extensions.

Global options

--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
--cdp-headers <json>     # Headers for --cdp discovery and WebSocket handshake (or AGENT_BROWSER_CDP_HEADERS env)
--auto-connect           # Auto-discover and connect to running Chrome
--no-auto-connect        # Return an --auto-connect session to a local launch (overrides AGENT_BROWSER_AUTO_CONNECT)
--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
--relaunch               # Relaunch the session's browser even when no setting changed

In a batch, --relaunch relaunches the browser once: the first command that can launch a browser carries it. Commands that never launch one, such as read, and commands denied by policy or waiting for confirmation pass it on to the next command.

See Configuration for config files and environment variables. See 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.

# 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

echo '[["fill", "#password", "secret"]]' | agent-browser batch --json --omit-command
OptionDescription
--bailStop on first error (default: continue all commands)
--jsonOutput results as a JSON array
--omit-commandWith --json, replace each command array with a stable zero-based index field

Put global flags such as --init-script and --enable on the outer batch invocation. Keep command-specific options and literal command arguments inside each item.

agent-browser --enable react-devtools batch "open" "navigate data:text/html,<h1>hi</h1>"

With --json --omit-command, rows use a stable zero-based index field on success, failure, or --bail; default JSON output keeps the command field. This only removes command arrays and does not make output safe for secrets. Errors and response data are unchanged: type echoes typed text, and get value/eval may return input values. The MCP agent_browser_batch tool accepts omitCommand: true.

MCP server

agent-browser mcp
agent-browser mcp --tools all
agent-browser mcp --tools core,network,react
agent-browser mcp call agent_browser_open '{"url":"https://example.com"}'
agent-browser mcp --config /path/to/trusted-config.json
agent-browser mcp call agent_browser_open '{"url":"https://example.com"}' --config /path/to/trusted-config.json
echo '{"selector":"@e2"}' | agent-browser mcp call agent_browser_click -

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.

mcp call runs one MCP tool without a stdio session and prints its tools/call result as JSON, with the agent-browser version in _meta.agentBrowserVersion. Pass the tool arguments as a JSON object, or - to read them from stdin. Every tool is available unless --tools limits the call to profiles. The exit code is 0 on success, 1 when the tool reports an error, and 2 for an unknown tool or invalid arguments. Use it from runtimes that cannot keep a stdio session open between tool calls, such as serverless agents. Access settings such as AGENT_BROWSER_ALLOWED_DOMAINS come from the environment, as with the server.

For tool calls that run the CLI, structuredContent.response contains parsed CLI JSON. stdout is included only when the output cannot be parsed as JSON; exitCode and stderr are always included.

In a Vercel Sandbox, startAgentBrowserMcp runs the server over the sandbox command's stdin. See Next.js + Vercel.

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:

{
  "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, and key, so MCP clients show meaningful approval prompts instead of raw command arrays. Tool discovery is paginated and includes read-only/open-world annotations so modern MCP clients can load the large typed surface incrementally.

Every tool also accepts the shared arguments session, restore, allowedDomains, extraArgs, timeoutMs, namespace, restoreSave, restoreCheckUrl, restoreCheckText, restoreCheckFn, caCert, useSystemCa, clearCaCert, idleTimeout, and relaunch. A tool's schema lists only the ones that usually matter for it: session on every tool, restore and relaunch on open and tab_new, allowedDomains and extraArgs on open, tab_new, and read, and timeoutMs on tools that navigate, wait, or run scripts. The server's initialize instructions describe all of them. allowedDomains maps to --allowed-domains, activates the same WebRTC containment and launch-mode restrictions, and is rejected when the server already sets allowed domains. idleTimeout maps to --idle-timeout, accepts values such as 30s, 5m, 1h, or raw milliseconds, and accepts 0 to disable idle shutdown. relaunch: true maps to --relaunch. extraArgs carries per-command options and display or emulation flags such as --engine; it cannot set --config or global flags that change network, file, policy, or host access. Set host-wide options in the MCP server's environment or selected config.

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

Pass --config <trusted-path> to agent-browser mcp or agent-browser mcp call to select one trusted config file. MCP tool child processes load only that file, replacing default user/project discovery. Put any required safety policy in it. Environment variables and accepted per-tool CLI arguments keep their normal precedence.

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:

agent-browser open example.com && agent-browser wait --load domcontentloaded && agent-browser snapshot -i
agent-browser fill @e1 "[email protected]" && 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:

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 for local files, uploads, downloads, screenshots, PDFs, and clipboard workflows.

PreviousModern Web GuidanceNextConfiguration