---

name: browser description: Automate browser interactions using agent-browser CLI — navigate, click, fill forms, scrape content, take screenshots, and more. argument-hint: <command> [args...] allowed-tools: Bash(npx agent-browser *)

Browser Automation with agent-browser

Control a headless Chromium browser via CLI commands. All commands are run with npx agent-browser <command>.

Setup (first time only)

npx agent-browser install

Navigation

| Command | Description | |---|---| | open <url> | Navigate to a URL | | close | Close browser | | tab | List open tabs | | tab new [url] | Open new tab | | tab <n> | Switch to tab n | | tab close [n] | Close tab | | window new | Open new browser window | | frame <selector> | Switch to iframe | | frame main | Return to main frame |

Page Inspection (use these to understand page structure)

| Command | Description | |---|---| | snapshot | Get accessibility tree with @e1, @e2 element refs (best for AI) | | screenshot [path] | Capture screenshot | | screenshot --full | Full page screenshot | | screenshot --annotate | Screenshot with numbered element labels | | get text <sel> | Extract text content | | get html <sel> | Get innerHTML | | get value <sel> | Get input value | | get attr <sel> <attr> | Get element attribute | | get title | Get page title | | get url | Get current URL | | get count <sel> | Count matching elements | | get box <sel> | Get bounding box | | get styles <sel> | Get computed styles | | is visible <sel> | Check if element is visible | | is enabled <sel> | Check if element is enabled | | is checked <sel> | Check if checkbox is checked |

Clicking & Interaction

| Command | Description | |---|---| | click <sel> | Click an element | | click <sel> --new-tab | Click, opening in new tab | | dblclick <sel> | Double-click | | hover <sel> | Hover over element | | focus <sel> | Focus element | | scroll <dir> [px] | Scroll up/down/left/right | | scrollintoview <sel> | Scroll element into view | | drag <src> <tgt> | Drag and drop |

Text Input

| Command | Description | |---|---| | fill <sel> <text> | Clear field and type text | | type <sel> <text> | Type into focused element (appends) | | keyboard type <text> | Type with real keystrokes | | keyboard inserttext <text> | Insert text without key events | | press <key> | Press a key (Enter, Tab, Control+a, etc.) | | keydown <key> | Hold key down | | keyup <key> | Release key |

Form Controls

| Command | Description | |---|---| | check <sel> | Check a checkbox | | uncheck <sel> | Uncheck a checkbox | | select <sel> <val> | Select dropdown option | | upload <sel> <files> | Upload file(s) to input |

Semantic Find (locate elements by meaning, not CSS)

find role <role> <action> [value]         # By ARIA role
find text <text> <action>                 # By visible text
find label <label> <action> [value]       # By label
find placeholder <ph> <action> [value]    # By placeholder
find alt <text> <action>                  # By alt text
find title <text> <action>                # By title attribute
find testid <id> <action> [value]         # By data-testid
find first <sel> <action> [value]         # First match
find last <sel> <action> [value]          # Last match
find nth <n> <sel> <action> [value]       # Nth match

Actions: click, fill, type, hover, focus, check, uncheck, text

Options: --name <name> (filter by accessible name), --exact (exact match)

Examples:

npx agent-browser find role button click --name "Submit"
npx agent-browser find text "Sign In" click
npx agent-browser find label "Email" fill "user@example.com"
npx agent-browser find placeholder "Search..." fill "vinyl records"

Waiting

| Command | Description | |---|---| | wait <selector> | Wait for element to appear | | wait <ms> | Wait N milliseconds | | wait --text "text" | Wait for text to appear | | wait --url "**/path" | Wait for URL pattern | | wait --load networkidle | Wait for network idle | | wait --fn "window.ready" | Wait for JS condition |

Cookies & Storage

| Command | Description | |---|---| | cookies | Get all cookies | | cookies set <name> <val> | Set a cookie | | cookies clear | Clear cookies | | storage local | Get all localStorage | | storage local <key> | Get localStorage key | | storage local set <k> <v> | Set localStorage value | | storage local clear | Clear localStorage | | storage session | Same commands for sessionStorage |

Network Interception

| Command | Description | |---|---| | network route <url> | Intercept requests matching URL | | network route <url> --abort | Block matching requests | | network route <url> --body <json> | Mock response body | | network unroute [url] | Remove intercept routes | | network requests | View tracked requests | | network requests --filter <pat> | Filter requests by pattern |

JavaScript Execution

| Command | Description | |---|---| | eval <js> | Run JavaScript in page context | | eval -b <base64> | Run base64-encoded JS |

Browser Configuration

| Command | Description | |---|---| | set viewport <w> <h> | Set viewport size | | set device <name> | Emulate device (e.g. "iPhone 14") | | set media dark | Emulate dark color scheme | | set media light | Emulate light color scheme | | set offline on | Enable offline mode | | set offline off | Disable offline mode | | set geo <lat> <lng> | Set geolocation | | set headers <json> | Set extra HTTP headers | | set credentials <user> <pass> | Set HTTP basic auth |

Mouse Control

| Command | Description | |---|---| | mouse move <x> <y> | Move cursor to coordinates | | mouse down [button] | Press mouse button | | mouse up [button] | Release mouse button | | mouse wheel <dy> [dx] | Scroll wheel |

State Persistence

| Command | Description | |---|---| | state save <path> | Save auth/session state | | state load <path> | Load saved state | | state list | List saved states | | state clear [name] | Clear a saved state | | state clear --all | Clear all saved states |

Debugging

| Command | Description | |---|---| | console | View console messages | | errors | View uncaught exceptions | | highlight <sel> | Visually highlight element | | trace start [path] | Start trace recording | | trace stop [path] | Stop and save trace | | profiler start | Start CPU profiling | | profiler stop [path] | Save profile | | pdf <path> | Save page as PDF |

Comparison & Diffing

| Command | Description | |---|---| | diff snapshot | Compare current vs previous snapshot | | diff snapshot --baseline <file> | Compare against saved file | | diff screenshot --baseline <file> | Visual pixel comparison | | diff url <a> <b> | Compare two URLs |

Typical Workflow

1. Open a page: open http://localhost:3000
2. Inspect structure: snapshot (returns element refs like @e1, @e2)
3. Interact using refs: click @e3 or fill @e5 "my text"
4. Verify results: get text @e7 or screenshot
5. Close when done: close

Selectors

Commands accept these selector types:

• Element refs from snapshot: @e1, @e2, etc. (preferred for AI)
• CSS selectors: #id, .class, div > span
• XPath: //button[@type="submit"]
• Semantic find: Use the find command family above

Default Login Flow

When testing locally, log in first before performing authenticated browser actions:

• URL: http://localhost:3000/auth
• Use Supabase Auth (email/password)

Project-Specific Pages

Key pages to test in the MVP boilerplate:

| Page | URL | Notes | |---|---|---| | Landing | http://localhost:3000 | Sections: Navbar, Hero, Logos, Items, Stats, Pricing, FAQ, Cta, Footer | | Sign In / Sign Up | http://localhost:3000/auth | Supabase Auth UI | | Account | http://localhost:3000/account | Authenticated - user profile & subscription | | Pricing | http://localhost:3000/#pricing | Stripe checkout integration |

Testing Dark Mode

# Toggle dark mode via the ModeToggle button in the navbar
npx agent-browser find role button click --name "Toggle theme"

# Or force via browser emulation
npx agent-browser set media dark
npx agent-browser set media light

Testing Responsive Design

# Mobile
npx agent-browser set viewport 375 812

# Tablet
npx agent-browser set viewport 768 1024

# Desktop
npx agent-browser set viewport 1440 900