# Command Reference Complete reference for all agent-browser commands. For quick start and common patterns, see SKILL.md. ## Navigation ```bash agent-browser open # Launch browser (no navigation); stays on about:blank. # Pair with `network route`, `cookies set --curl`, or # `addinitscript` to stage state before the first navigation. agent-browser open # Launch + navigate (aliases: goto, navigate) # Supports: https://, http://, file://, about:, data:// # Auto-prepends https:// if no protocol given agent-browser read [url] # Fetch agent-readable text, or read rendered active-tab DOM # Explicit URLs send Accept: text/markdown, then try .md if needed # Walks ancestor paths for llms.txt before HTML fallback # --llms and --require-md without URL use the active tab URL # --filter narrows page content to matching heading sections # Honors --allowed-domains, --content-boundaries, and --max-output # Options: --raw, --require-md, --outline, --llms , --filter, --timeout agent-browser back # Go back agent-browser forward # Go forward agent-browser reload # Reload page agent-browser pushstate # SPA client-side navigation. Auto-detects # window.next.router.push (triggers RSC fetch on Next.js); # falls back to history.pushState + popstate/navigate events. agent-browser close # Close browser (aliases: quit, exit) agent-browser connect 9222 # Connect to browser via CDP port ``` ### Pre-navigation setup (one-turn batch) ```bash agent-browser batch \ '["open"]' \ '["network","route","*","--abort","--resource-type","script"]' \ '["cookies","set","--curl","cookies.curl","--domain","localhost"]' \ '["navigate","http://localhost:3000/target"]' ``` `open` with no URL gives you a clean launch so any interception, cookies, or init scripts you register take effect on the *first* real navigation. Use for SSR-only debug (`--resource-type script`), protected-origin auth, or capturing fresh `react suspense`/`vitals` state without noise from a prior page. ## Snapshot (page analysis) ```bash agent-browser snapshot # Full accessibility tree agent-browser snapshot -i # Interactive elements only (recommended) agent-browser snapshot -c # Compact output agent-browser snapshot -d 3 # Limit depth to 3 agent-browser snapshot -s "#main" # Scope to CSS selector ``` ## Interactions (use @refs from snapshot) ```bash agent-browser click @e1 # Click agent-browser click @e1 --new-tab # Click and open in new tab agent-browser dblclick @e1 # Double-click agent-browser focus @e1 # Focus element agent-browser fill @e2 "text" # Clear and type agent-browser type @e2 "text" # Type without clearing agent-browser press Enter # Press key (alias: key) agent-browser press Control+a # Key combination agent-browser keydown Shift # Hold key down agent-browser keyup Shift # Release key agent-browser hover @e1 # Hover agent-browser check @e1 # Check checkbox agent-browser uncheck @e1 # Uncheck checkbox agent-browser select @e1 "value" # Select dropdown option agent-browser select @e1 "a" "b" # Select multiple options agent-browser scroll down 500 # Scroll page (default: down 300px) agent-browser scrollintoview @e1 # Scroll element into view (alias: scrollinto) agent-browser drag @e1 @e2 # Drag and drop agent-browser upload @e1 file.pdf # Upload files ``` Clicks fail before dispatch when another element covers the target's click point. The error names the covering element, for example `covered by `. Dismiss or interact with that element, run a fresh snapshot, then retry the original action. ## Get Information ```bash agent-browser get text @e1 # Get element text agent-browser get html @e1 # Get innerHTML agent-browser get value @e1 # Get input value agent-browser get attr @e1 href # Get attribute agent-browser get title # Get page title agent-browser get url # Get current URL agent-browser get cdp-url # Get CDP WebSocket URL agent-browser get count ".item" # Count matching elements agent-browser get box @e1 # Get bounding box agent-browser get styles @e1 # Get computed styles (font, color, bg, etc.) ``` ## Check State ```bash agent-browser is visible @e1 # Check if visible agent-browser is enabled @e1 # Check if enabled agent-browser is checked @e1 # Check if checked ``` ## Screenshots and PDF ```bash agent-browser screenshot # Save to temporary directory agent-browser screenshot path.png # Save to specific path agent-browser screenshot --full # Full page agent-browser pdf output.pdf # Save as PDF ``` Headless Chromium screenshots hide native scrollbars for consistent image output. Pass `--hide-scrollbars false` when launching to keep native scrollbars visible. ## Video Recording ```bash agent-browser open https://example.com # Launch a browser session first agent-browser record start ./demo.webm # Start recording agent-browser click @e1 # Perform actions agent-browser record stop # Stop and save video agent-browser record restart ./take2.webm # Stop current + start new ``` ## Wait ```bash agent-browser wait @e1 # Wait for element agent-browser wait 2000 # Wait milliseconds agent-browser wait --text "Success" # Wait for text (or -t) agent-browser wait --url "**/dashboard" # Wait for URL pattern (or -u) agent-browser wait --load networkidle # Wait for network idle (or -l) agent-browser wait --fn "window.ready" # Wait for JS condition (or -f) ``` ## Mouse Control ```bash agent-browser mouse move 100 200 # Move mouse agent-browser mouse down left # Press button agent-browser mouse up left # Release button agent-browser mouse wheel 100 # Scroll wheel ``` ## Semantic Locators (alternative to refs) ```bash agent-browser find role button click --name "Submit" agent-browser find role heading text --name "Skills" # implicit roles work:

=heading,
    =list, top-level
    =banner agent-browser find text "Sign In" click agent-browser find text "Sign In" click --exact # Exact match only agent-browser find label "Email" fill "user@test.com" agent-browser find placeholder "Search" fill "query" agent-browser find alt "Logo" click agent-browser find title "Close" click agent-browser find testid "submit-btn" click agent-browser find first ".item" click agent-browser find last ".item" click agent-browser find nth 2 "a" hover ``` ## Browser Settings ```bash agent-browser set viewport 1920 1080 # Set viewport size agent-browser set viewport 1920 1080 2 # 2x retina (same CSS size, higher res screenshots) agent-browser set device "iPhone 14" # Emulate device agent-browser set geo 37.7749 -122.4194 # Set geolocation (alias: geolocation) agent-browser set offline on # Toggle offline mode agent-browser set headers '{"X-Key":"v"}' # Extra HTTP headers agent-browser set credentials user pass # HTTP basic auth (alias: auth) agent-browser set media dark # Emulate color scheme agent-browser set media light reduced-motion # Light mode + reduced motion ``` ## Cookies and Storage ```bash agent-browser cookies # Get all cookies agent-browser cookies set name value # Set cookie agent-browser cookies clear # Clear cookies agent-browser storage local # Get all localStorage agent-browser storage local key # Get specific key agent-browser storage local set k v # Set value agent-browser storage local clear # Clear all ``` ## Network ```bash agent-browser network route # Intercept requests agent-browser network route --abort # Block requests agent-browser network route --body '{}' # Mock response agent-browser network unroute [url] # Remove routes agent-browser network requests # View tracked requests agent-browser network requests --filter api # Filter requests agent-browser network request # Full request/response detail incl. body agent-browser network har start # Record traffic (embeds text response bodies) agent-browser network har start --content all # Embed all bodies (binary as base64) agent-browser network har start --content none # Sizes and headers only agent-browser network har stop [output.har] # Stop and save HAR ``` ## Tabs and Windows ```bash agent-browser tab # List tabs with tabId and label agent-browser tab new [url] # New tab agent-browser tab new --label docs [url] # New tab with a memorable label agent-browser tab t2 # Switch to tab by id agent-browser tab docs # Switch to tab by label agent-browser tab close # Close current tab agent-browser tab close t2 # Close tab by id agent-browser tab close docs # Close tab by label agent-browser window new # New window ``` Tab ids are stable strings of the form `t1`, `t2`, `t3`. They're never reused within a session, so the same id keeps referring to the same tab across commands. Positional integers are **not** accepted — `tab 2` errors with a teaching message; use `t2`. User-assigned labels (`docs`, `app`, `admin`) are interchangeable with ids everywhere a tab ref is accepted. Labels are the agent-friendly way to write multi-tab workflows: ```bash agent-browser tab new --label docs https://docs.example.com agent-browser tab new --label app https://app.example.com agent-browser tab docs # switch to docs agent-browser snapshot # populate refs for docs agent-browser click @e1 # ref click on docs agent-browser tab app # switch to app agent-browser tab close docs # close by label ``` Labels are never auto-generated, never rewritten on navigation, and must be unique within a session. To interact with another tab, switch to it first: the daemon maintains a single active tab, so refs (`@eN`) belong to the tab that was active when the snapshot ran. `tab list --json` also reports each tab's CDP `targetId`, accepted anywhere a tab ref is accepted (`tab `, `tab close `). Target ids stay stable across daemon restarts, unlike `t` ids, which are per-daemon counters. With `--pin-tab` the session is pinned to its bound tab: if that tab is closed, commands fail with a `tab_gone` error instead of falling back to another tab, and `tab new` or `tab list` recover. JSON errors include `code: "tab_gone"` and a recovery object with `data.targetId` plus optional sanitized `data.lastUrl`; batch uses `result` for the same object. Switching to a tab that the browser discarded to save memory reactivates it, since a discarded tab has no renderer to drive. Reactivation reloads the page and resets its unsaved state, and the switch result adds `"revived": true` so the reload is not 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`/`dialog dismiss` and its state is preserved. Closing the active tab onto a discarded successor revives it the same way and reports `"activeTabRevived": true`. ## Frames ```bash agent-browser frame "#iframe" # Switch to iframe by CSS selector agent-browser frame @e3 # Switch to iframe by element ref agent-browser frame main # Back to main frame ``` ### Iframe support Iframes are detected automatically during snapshots. When the main-frame snapshot runs, `Iframe` nodes are resolved and their content is inlined beneath the iframe element in the output (one level of nesting; iframes within iframes are not expanded). ```bash agent-browser snapshot -i # @e3 [Iframe] "payment-frame" # @e4 [input] "Card number" # @e5 [button] "Pay" # Interact directly — refs inside iframes already work agent-browser fill @e4 "4111111111111111" agent-browser click @e5 # Or switch frame context for scoped snapshots agent-browser frame @e3 # Switch using element ref agent-browser snapshot -i # Snapshot scoped to that iframe agent-browser frame main # Return to main frame ``` The `frame` command accepts: - **Element refs** — `frame @e3` resolves the ref to an iframe element - **CSS selectors** — `frame "#payment-iframe"` finds the iframe by selector - **Frame name/URL** — matches against the browser's frame tree ## Dialogs 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` to disable this behavior. ```bash agent-browser dialog accept [text] # Accept dialog agent-browser dialog dismiss # Dismiss dialog agent-browser dialog status # Check if a dialog is currently open ``` ## JavaScript ```bash agent-browser eval "document.title" # Simple expressions only agent-browser eval -b "" # Any JavaScript (base64 encoded) agent-browser eval --stdin # Read script from stdin ``` Use `-b`/`--base64` or `--stdin` for reliable execution. Shell escaping with nested quotes and special characters is error-prone. ```bash # Base64 encode your script, then: agent-browser eval -b "ZG9jdW1lbnQucXVlcnlTZWxlY3RvcignW3NyYyo9Il9uZXh0Il0nKQ==" # Or use stdin with heredoc for multiline scripts: cat <<'EOF' | agent-browser eval --stdin const links = document.querySelectorAll('a'); Array.from(links).map(a => a.href); EOF ``` ## Authentication and Plugins ```bash agent-browser auth save --url --username --password-stdin agent-browser auth login # Login using saved credentials agent-browser auth login --credential-provider [--item ] [--url ] agent-browser auth login --username-selector --password-selector [--submit-selector ] agent-browser auth list # List saved auth profiles agent-browser auth show # Show profile metadata, no passwords agent-browser auth delete # Delete a saved profile agent-browser plugin add # Add a plugin from npm or GitHub agent-browser plugin list # List configured plugins agent-browser plugin show # Show one configured plugin agent-browser plugin run --payload # Run an arbitrary plugin request ``` Credential provider plugins run out-of-process over the `agent-browser.plugin.v1` stdio JSON protocol and must declare `credential.read`. Use `--confirm-actions plugin::credential.read` to require explicit approval before a plugin resolves secrets. Other capabilities use the same protocol: - `browser.provider`: `agent-browser --provider open ` - `launch.mutate`: append local launch args, extensions, or init scripts - `command.run`: `agent-browser plugin run --payload ` `plugin run` is for `command.run` and custom capabilities. Core capabilities and protocol request types use their dedicated command paths. ## State Management ```bash agent-browser state save auth.json # Save cookies, storage, auth state agent-browser state load auth.json # Restore saved state ``` ## Live Streaming ```bash agent-browser stream status --json # Enabled state, port, client count agent-browser stream enable # Start the WebSocket stream server agent-browser stream enable --port 9223 # Experimental WebMCP page tools agent-browser webmcp list agent-browser webmcp invoke --params '{"key":"value"}' agent-browser webmcp invoke --params @input.json --detach agent-browser webmcp result agent-browser webmcp cancel agent-browser stream disable # Stop it ``` Clients connect to `ws://127.0.0.1:` and receive `frame`, `status`, `tabs`, `url`, and `console` messages. They send `input_mouse`, `input_keyboard`, and `input_touch` to drive the page, `{"type":"config","maxFps":N}` (1 to 120, `0` = uncapped) to cap their own frame rate, and `{"type":"config","pacing":"ack"}` to receive one frame at a time, acknowledged with `{"type":"ack","seq":N}`. Both settings can be declared on the URL instead (`ws://127.0.0.1:/?pacing=ack&maxFps=10`). See [streaming.md](streaming.md). ## Observability Dashboard ```bash agent-browser dashboard start agent-browser dashboard start --port 8080 agent-browser dashboard start --allowed-origins https://dashboard.example.com agent-browser dashboard stop ``` Loopback origins are allowed by default over IPv4 and IPv6 without an access token. Set `--allowed-origins` or `AGENT_BROWSER_DASHBOARD_ALLOWED_ORIGINS` to a comma-separated list of exact HTTPS reverse-proxied origins. Every origin must be valid, and custom 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 `http://localhost:` directly for local access. Repeated starts reuse the running dashboard only when the port and allowed origins match; stop it before changing either setting. ## MCP Server ```bash agent-browser mcp agent-browser mcp --tools all agent-browser mcp --tools core,network,react ``` Starts a stdio Model Context Protocol server. MCP clients should configure the server command as `agent-browser` with args `["mcp"]`. The server defaults to MCP protocol 2025-11-25 and accepts older supported client protocol versions during initialization. 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, a11y audit, 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 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` Tool calls use the same config files and environment variables as the CLI. Each tool accepts typed arguments plus `extraArgs` for advanced CLI flags and exact CLI parity. The common `allowedDomains` array maps to `--allowed-domains` and activates the same WebRTC containment and launch-mode restrictions. Tool discovery is paginated and includes read-only/open-world annotations so modern MCP clients can load the large typed surface incrementally. Use the `session` tool argument or `AGENT_BROWSER_SESSION` to isolate browser state. ## Global Options ```bash agent-browser --session ... # Isolated browser session agent-browser --json ... # JSON output for parsing agent-browser --headed ... # Show browser window (not headless; on displayless Linux an Xvfb display starts automatically) agent-browser --webgpu ... # Enable WebGPU (SwiftShader software Vulkan on Linux, no GPU needed) agent-browser --no-webmcp ... # Disable default experimental WebMCP Chrome features (or AGENT_BROWSER_NO_WEBMCP env) agent-browser --cdp ... # Connect via CDP; root query slash is optional agent-browser --pin-tab ... # Pin the session to its bound tab (strict tab binding) agent-browser --no-pin-tab ... # Disable a sticky pin previously enabled with --pin-tab agent-browser -p ... # Browser provider or configured provider plugin agent-browser --proxy ... # Use proxy server agent-browser --proxy-bypass # Hosts to bypass proxy agent-browser --headers ... # HTTP headers scoped to URL's origin agent-browser --executable-path

    # Custom browser executable agent-browser --extension ... # Load browser extension (repeatable) agent-browser --ignore-https-errors # Ignore SSL certificate errors agent-browser --ca-cert # Trust a CA in local Chromium on Linux (install --with-deps provides certutil) agent-browser --no-ca-cert # Clear CA trust retained by the running session agent-browser --hide-scrollbars false # Keep native scrollbars visible in headless Chromium screenshots agent-browser --help # Show help (-h) agent-browser --version # Show version (-V) agent-browser --help # Show detailed help for a command ``` ## Debugging ```bash agent-browser --headed open example.com # Show browser window agent-browser --cdp 9222 snapshot # Connect via CDP port agent-browser connect 9222 # Alternative: connect command agent-browser console # View console messages agent-browser console --clear # Clear console agent-browser errors # View page errors agent-browser errors --clear # Clear errors agent-browser highlight @e1 # Highlight element agent-browser inspect # Open Chrome DevTools for this session agent-browser trace start # Start recording trace agent-browser trace stop trace.json # Stop and save trace agent-browser profiler start # Start Chrome DevTools profiling agent-browser profiler stop trace.json # Stop and save profile ``` ## React / Web Vitals Requires `--enable react-devtools` at launch for the `react ...` commands. `vitals` and `pushstate` are framework-agnostic. ```bash agent-browser open --enable react-devtools # Launch with React hook installed agent-browser react tree # Full component tree agent-browser react inspect # Props, hooks, state, source agent-browser react renders start # Begin re-render recording agent-browser react renders stop [--json] # Stop and print render 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 agent-browser pushstate # SPA client-side nav (auto-detects Next router) ``` `vitals` prints a summary by default and uses the same fields as the structured `--json` response. ## Accessibility audit Runs an embedded axe-core audit with no CDN fetch. The vendored engine runs private partial audits through CDP across the page's frame tree and merges serialized results without page messaging, so page CSP does not block it, 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. Reports WCAG violations with impact, rule id, fix guidance URL, and failing-node selectors. ```bash agent-browser a11y # Audit the current page agent-browser a11y # Navigate, then audit agent-browser a11y --tags wcag2a,wcag2aa # Only rules with these axe tags agent-browser a11y --selector "#main" # Scope audit to a subtree agent-browser a11y --json # Structured results for automation ``` `--json` returns `counts` plus `violations`/`incomplete` arrays; each entry has `id`, `impact`, `help`, `helpUrl`, `tags`, `nodeCount`, and up to 10 `nodes` (`target` selector path arrays, `html` snippet, `failureSummary`). Nested `target` arrays preserve shadow DOM boundaries. `incomplete` lists rules axe could not evaluate automatically — review those manually. ## Init scripts ```bash agent-browser open --init-script # Register before first navigation (repeatable) agent-browser addinitscript # Register at runtime (returns identifier) agent-browser removeinitscript # Remove a previously registered init script ``` ## cURL cookie import ```bash agent-browser cookies set --curl # Auto-detects JSON/cURL/Cookie-header agent-browser cookies set --curl --domain example.com # Scope to a domain ``` Supported formats: JSON array of `{name, value}`, a cURL dump from DevTools -> Network -> Copy as cURL, or a bare Cookie header. Errors never echo cookie values. ## Network route by resource type ```bash agent-browser network route '*' --abort --resource-type script # Block scripts only (SSR-lock pattern) agent-browser network route '*' --resource-type image,font --body '' # Stub images and fonts ``` ## Environment Variables ```bash AGENT_BROWSER_SESSION="mysession" # Default session name AGENT_BROWSER_EXECUTABLE_PATH="/path/chrome" # Custom browser path AGENT_BROWSER_EXTENSIONS="/ext1,/ext2" # Comma-separated extension paths AGENT_BROWSER_INIT_SCRIPTS="/a.js,/b.js" # Comma-separated init script paths AGENT_BROWSER_ENABLE="react-devtools" # Comma-separated built-in init script features AGENT_BROWSER_HIDE_SCROLLBARS="false" # Keep native scrollbars visible in headless Chromium screenshots AGENT_BROWSER_WEBGPU="1" # Enable the WebGPU launch preset (see references/webgpu.md) AGENT_BROWSER_NO_XVFB="1" # Disable automatic Xvfb for headed mode on displayless Linux AGENT_BROWSER_PROVIDER="browserbase" # Browser provider or configured provider plugin AGENT_BROWSER_STREAM_PORT="9223" # Override WebSocket streaming port (default: OS-assigned) AGENT_BROWSER_DASHBOARD_ALLOWED_ORIGINS="https://dashboard.example.com" # Trusted HTTPS reverse-proxied dashboard origins AGENT_BROWSER_CONFIG="./agent-browser.json" # Custom config file AGENT_BROWSER_CDP="9222" # Connect daemon to CDP port or WebSocket URL AGENT_BROWSER_ALLOWED_DOMAINS="example.com" # Restrict network domains; requires a fresh controllable browser context without profile/session startup args, restore/state replay, or direct-page provider plugins AGENT_BROWSER_PLUGINS='[{"name":"vault","command":"agent-browser-plugin-vault","capabilities":["credential.read"]},{"name":"stealth","command":"agent-browser-plugin-stealth","capabilities":["launch.mutate"]}]' ```