agent-browser: CLI Browser Automation

Vercel's headless browser automation CLI designed for AI agents. Uses ref-based selection (@e1, @e2) from accessibility snapshots.

Setup Check

Check installation

command -v agent-browser >/dev/null 2>&1 && echo "Installed" || echo "NOT INSTALLED - run: npm install -g agent-browser && agent-browser install"

Install if needed

npm install -g agent-browser agent-browser install # Downloads Chromium

Core Workflow

The snapshot + ref pattern is optimal for LLMs:

• Navigate to URL

• Snapshot to get interactive elements with refs

• Interact using refs (@e1, @e2, etc.)

• Re-snapshot after navigation or DOM changes

Step 1: Open URL

agent-browser open https://example.com

Step 2: Get interactive elements with refs

agent-browser snapshot -i --json

Step 3: Interact using refs

agent-browser click @e1 agent-browser fill @e2 "search query"

Step 4: Re-snapshot after changes

agent-browser snapshot -i

Key Commands

Navigation

agent-browser open <url> # Navigate to URL agent-browser back # Go back agent-browser forward # Go forward agent-browser reload # Reload page agent-browser close # Close browser

Snapshots (Essential for AI)

agent-browser snapshot # Full accessibility tree agent-browser snapshot -i # Interactive elements only (recommended) agent-browser snapshot -i --json # JSON output for parsing agent-browser snapshot -c # Compact (remove empty elements) agent-browser snapshot -d 3 # Limit depth

Interactions

agent-browser click @e1 # Click element agent-browser dblclick @e1 # Double-click agent-browser fill @e1 "text" # Clear and fill input agent-browser type @e1 "text" # Type without clearing agent-browser press Enter # Press key agent-browser hover @e1 # Hover element agent-browser check @e1 # Check checkbox agent-browser uncheck @e1 # Uncheck checkbox agent-browser select @e1 "option" # Select dropdown option agent-browser scroll down 500 # Scroll (up/down/left/right) agent-browser scrollintoview @e1 # Scroll element into view

Get Information

agent-browser get text @e1 # Get element text agent-browser get html @e1 # Get element HTML agent-browser get value @e1 # Get input value agent-browser get attr href @e1 # Get attribute agent-browser get title # Get page title agent-browser get url # Get current URL agent-browser get count "button" # Count matching elements

Screenshots & PDFs

agent-browser screenshot # Viewport screenshot agent-browser screenshot --full # Full page agent-browser screenshot output.png # Save to file agent-browser screenshot --full output.png # Full page to file agent-browser pdf output.pdf # Save as PDF

Wait

agent-browser wait @e1 # Wait for element agent-browser wait 2000 # Wait milliseconds agent-browser wait "text" # Wait for text to appear

Semantic Locators (Alternative to Refs)

agent-browser find role button click --name "Submit" agent-browser find text "Sign up" click agent-browser find label "Email" fill "user@example.com" agent-browser find placeholder "Search..." fill "query"

Sessions (Parallel Browsers)

Run multiple independent browser sessions

agent-browser --session browser1 open https://site1.com agent-browser --session browser2 open https://site2.com

List active sessions

agent-browser session list

Examples

Login Flow

agent-browser open https://app.example.com/login agent-browser snapshot -i

Output shows: textbox "Email" [ref=e1], textbox "Password" [ref=e2], button "Sign in" [ref=e3]

agent-browser fill @e1 "user@example.com" agent-browser fill @e2 "password123" agent-browser click @e3 agent-browser wait 2000 agent-browser snapshot -i # Verify logged in

Search and Extract

agent-browser open https://news.ycombinator.com agent-browser snapshot -i --json

Parse JSON to find story links

agent-browser get text @e12 # Get headline text agent-browser click @e12 # Click to open story

Form Filling

agent-browser open https://forms.example.com agent-browser snapshot -i agent-browser fill @e1 "John Doe" agent-browser fill @e2 "john@example.com" agent-browser select @e3 "United States" agent-browser check @e4 # Agree to terms agent-browser click @e5 # Submit button agent-browser screenshot confirmation.png

Debug Mode

Run with visible browser window

agent-browser --headed open https://example.com agent-browser --headed snapshot -i agent-browser --headed click @e1

JSON Output

Add --json for structured output:

agent-browser snapshot -i --json

Returns:

{ "success": true, "data": { "refs": { "e1": {"name": "Submit", "role": "button"}, "e2": {"name": "Email", "role": "textbox"} }, "snapshot": "- button "Submit" [ref=e1]\n- textbox "Email" [ref=e2]" } }

Inspection & Debugging

JavaScript Evaluation

agent-browser eval "document.title" # Evaluate JS expression agent-browser eval "JSON.stringify(localStorage)" # Return serialized data agent-browser eval "document.querySelectorAll('a').length" # Count elements

Console & Errors

agent-browser console # Show browser console output agent-browser console --clear # Show and clear console agent-browser errors # Show JavaScript errors only agent-browser errors --clear # Show and clear errors

Network

agent-browser network requests # List captured requests agent-browser network requests --filter "api" # Filter by URL pattern agent-browser route "/.png" abort # Block matching requests agent-browser route "https://api.example.com/" fulfill --status 200 --body '{"mock":true}' # Mock response agent-browser unroute "/*.png" # Remove route handler

Storage

Cookies

agent-browser cookies get # Get all cookies agent-browser cookies get --name "session" # Get specific cookie agent-browser cookies set --name "token" --value "abc" # Set cookie agent-browser cookies clear # Clear all cookies

Local & Session Storage

agent-browser storage local # Get all localStorage agent-browser storage local --key "theme" # Get specific key agent-browser storage session # Get all sessionStorage agent-browser storage session --key "cart" # Get specific key

Device & Settings

agent-browser set viewport 1920 1080 # Set viewport size agent-browser set device "iPhone 14" # Emulate device agent-browser set geo --lat 47.6 --lon -122.3 # Set geolocation agent-browser set offline true # Enable offline mode agent-browser set offline false # Disable offline mode agent-browser set media "prefers-color-scheme" "dark" # Set media feature agent-browser set headers '{"X-Custom":"value"}' # Set extra HTTP headers agent-browser set credentials "user" "pass" # Set HTTP auth credentials

Element Debugging

agent-browser highlight @e1 # Highlight element visually agent-browser get box @e1 # Get bounding box (x, y, width, height) agent-browser get styles @e1 # Get computed styles agent-browser is visible @e1 # Check if element is visible agent-browser is enabled @e1 # Check if element is enabled agent-browser is checked @e1 # Check if checkbox/radio is checked

Recording & Tracing

agent-browser trace start # Start recording trace agent-browser trace stop trace.zip # Stop and save trace file agent-browser record start # Start recording video agent-browser record stop video.webm # Stop and save recording

Tabs & Windows

agent-browser tab list # List open tabs agent-browser tab new https://example.com # Open URL in new tab agent-browser tab close # Close current tab agent-browser tab 2 # Switch to tab by index

Advanced Mouse

agent-browser mouse move 100 200 # Move mouse to coordinates agent-browser mouse down # Press mouse button agent-browser mouse up # Release mouse button agent-browser mouse wheel 0 500 # Scroll (deltaX, deltaY) agent-browser drag @e1 @e2 # Drag from element to element

vs Playwright MCP

Feature agent-browser (CLI) Playwright MCP

Interface Bash commands MCP tools

Selection Refs (@e1) Refs (e1)

Output Text/JSON Tool responses

Parallel Sessions Tabs

Best for Quick automation Tool integration

Use agent-browser when:

• You prefer Bash-based workflows

• You want simpler CLI commands

• You need quick one-off automation

Use Playwright MCP when:

• You need deep MCP tool integration

• You want tool-based responses

• You're building complex automation