Cookies & Storage

agent-browser cookies # Get all cookies
agent-browser cookies set # Set cookie
agent-browser cookies clear # Clear cookies

agent-browser storage local # Get all localStorage
agent-browser storage local # Get specific key
agent-browser storage local set # Set value
agent-browser storage local clear # Clear all

agent-browser storage session # Same for sessionStorage

Network

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

Tabs & Windows

agent-browser tab # List tabs
agent-browser tab new [url] # New tab (optionally with URL)
agent-browser tab # Switch to tab n
agent-browser tab close [n] # Close tab
agent-browser window new # New window

Frames

agent-browser frame # Switch to iframe
agent-browser frame main # Back to main frame

Dialogs

agent-browser dialog accept [text] # Accept (with optional prompt text)
agent-browser dialog dismiss # Dismiss

Debug

agent-browser trace start [path] # Start recording trace
agent-browser trace stop [path] # Stop and save trace
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 # Highlight element
agent-browser state save # Save auth state
agent-browser state load # Load auth state

Navigation

agent-browser back # Go back
agent-browser forward # Go forward
agent-browser reload # Reload page

Setup

agent-browser install # Download Chromium browser
agent-browser install --with-deps # Also install system deps (Linux)

Sessions

Run multiple isolated browser instances:

Different sessions

agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com

Or via environment variable

AGENT_BROWSER_SESSION=agent1 agent-browser click "#btn"

List active sessions

agent-browser session list

Output:

Active sessions:

-> default

agent1

Show current session

agent-browser session

Each session has its own:

Browser instance
Cookies and storage
Navigation history
Authentication state

Snapshot Options

The snapshot command supports filtering to reduce output size:

agent-browser snapshot # Full accessibility tree
agent-browser snapshot -i # Interactive elements only (buttons, inputs, links)
agent-browser snapshot -c # Compact (remove empty structural elements)
agent-browser snapshot -d 3 # Limit depth to 3 levels
agent-browser snapshot -s "#main" # Scope to CSS selector
agent-browser snapshot -i -c -d 5 # Combine options

Option Description
-i, --interactive Only show interactive elements (buttons, links, inputs)
-c, --compact Remove empty structural elements
-d, --depth Limit tree depth
-s, --selector Scope to CSS selector
Options
Option Description
--session Use isolated session (or AGENT_BROWSER_SESSION env)
--headers Set HTTP headers scoped to the URL's origin
--executable-path Custom browser executable (or AGENT_BROWSER_EXECUTABLE_PATH env)
--json JSON output (for agents)
--full, -f Full page screenshot
--name, -n Locator name filter
--exact Exact text match
--headed Show browser window (not headless)
--cdp Connect via Chrome DevTools Protocol
--debug Debug output
Selectors
Refs (Recommended for AI)

Refs provide deterministic element selection from snapshots:

1. Get snapshot with refs

agent-browser snapshot

Output:

- heading "Example Domain" [ref=e1] [level=1]

- button "Submit" [ref=e2]

- textbox "Email" [ref=e3]

- link "Learn more" [ref=e4]

2. Use refs to interact

agent-browser click @e2 # Click the button
agent-browser fill @e3 "test@example.com" # Fill the textbox
agent-browser get text @e1 # Get heading text
agent-browser hover @e4 # Hover the link

Why use refs?

Deterministic: Ref points to exact element from snapshot
Fast: No DOM re-query needed
AI-friendly: Snapshot + ref workflow is optimal for LLMs

CSS Selectors

agent-browser click "#id"
agent-browser click ".class"
agent-browser click "div > button"

Text & XPath

agent-browser click "text=Submit"
agent-browser click "xpath=//button"

Semantic Locators

agent-browser find role button click --name "Submit"
agent-browser find label "Email" fill "test@test.com"

Agent Mode

Use --json for machine-readable output:

agent-browser snapshot --json

Returns: {"success":true,"data":{"snapshot":"...","refs":{"e1":{"role":"heading","name":"Title"},...}}}

agent-browser get text @e1 --json
agent-browser is visible @e2 --json

Optimal AI Workflow

1. Navigate and get snapshot

agent-browser open example.com
agent-browser snapshot -i --json # AI parses tree and refs

2. AI identifies target refs from snapshot

3. Execute actions using refs

agent-browser click @e2
agent-browser fill @e3 "input text"

4. Get new snapshot if page changed

agent-browser snapshot -i --json

Headed Mode

Show the browser window for debugging:

agent-browser open example.com --headed

This opens a visible browser window instead of running headless.
Authenticated Sessions

Use --headers to set HTTP headers for a specific origin, enabling authentication without login flows:

Headers are scoped to api.example.com only

agent-browser open api.example.com --headers '{"Authorization": "Bearer "}'

Requests to api.example.com include the auth header

agent-browser snapshot -i --json
agent-browser click @e2

Navigate to another domain - headers are NOT sent (safe!)

agent-browser open other-site.com

This is useful for:

Skipping login flows - Authenticate via headers instead of UI
Switching users - Start new sessions with different auth tokens
API testing - Access protected endpoints directly
Security - Headers are scoped to the origin, not leaked to other domains

To set headers for multiple origins, use --headers with each open command:

agent-browser open api.example.com --headers '{"Authorization": "Bearer token1"}'
agent-browser open api.acme.com --headers '{"Authorization": "Bearer token2"}'

For global headers (all domains), use set headers:

agent-browser set headers '{"X-Custom-Header": "value"}'

Custom Browser Executable

Use a custom browser executable instead of the bundled Chromium. This is useful for:

Serverless deployment: Use lightweight Chromium builds like @sparticuz/chromium (~50MB vs ~684MB)
System browsers: Use an existing Chrome/Chromium installation
Custom builds: Use modified browser builds

CLI Usage

Via flag

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

Via environment variable

AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com

Serverless Example (Vercel/AWS Lambda)

import chromium from '@sparticuz/chromium';
import { BrowserManager } from 'agent-browser';

export async function handler() {
const browser = new BrowserManager();
await browser.launch({
executablePath: await chromium.executablePath(),
headless: true,
});
// ... use browser
}