Browser Automation with agent-browser
Core Workflow
Every browser automation follows this pattern:
- Navigate:
agent-browser open <url>
- Snapshot:
agent-browser snapshot -i (get element refs like @e1, @e2)
- Interact: Use refs to click, fill, select
- Re-snapshot: After navigation or DOM changes, get fresh refs
agent-browser open https://example.com/form
agent-browser snapshot -i
# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i # Check result
Command Chaining
Commands can be chained with && in a single shell invocation. The browser persists between commands via a background daemon.
# Chain open + wait + snapshot in one call
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
# Chain multiple interactions
agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "password123" && agent-browser click @e3
Essential Commands
# Navigation
agent-browser open https://example.com
agent-browser go back
agent-browser reload
# Snapshots (Text/DOM)
agent-browser snapshot -i # Include interactive refs (@e1)
agent-browser snapshot -i --all # Include hidden/non-interactive
# Interaction
agent-browser click @e1
agent-browser fill @e2 "Text to type"
agent-browser select @e3 "Option Value"
agent-browser hover @e4
agent-browser press @e1 Enter
agent-browser scroll down
# Verification & Waiting
agent-browser diff snapshot # Compare current state to last snapshot
agent-browser wait --load networkidle
agent-browser wait @e1 # Wait for element to appear
agent-browser wait 2000 # Wait 2000ms
# Cleanup
agent-browser close # Close the background daemon session
Advanced Usage and Common Patterns
For information on Mobile Testing, Form Handling, iFrames, Shadow DOM, Security Configuration, Diffing, Timeouts, Ref Lifecycle, Annotated Screenshots (Vision), Locators, and JS evaluation:
See references/ADVANCED.md
Deep-Dive Documentation
| Reference |
When to Use |
| references/commands.md |
Full command reference with all options |
| references/snapshot-refs.md |
Ref lifecycle, invalidation rules, troubleshooting |
| references/session-management.md |
Parallel sessions, state persistence, concurrent scraping |
| references/authentication.md |
Login flows, OAuth, 2FA handling, state reuse |
| references/video-recording.md |
Recording workflows for debugging and documentation |
| references/profiling.md |
Chrome DevTools profiling for performance analysis |
| references/proxy-support.md |
Proxy configuration, geo-testing, rotating proxies |
Ready-to-Use Templates
| Template |
Description |
| templates/form-automation.sh |
Form filling with validation |
| templates/authenticated-session.sh |
Login once, reuse state |
| templates/capture-workflow.sh |
Content extraction with screenshots |
./templates/form-automation.sh https://example.com/form
./templates/authenticated-session.sh https://app.example.com/login
./templates/capture-workflow.sh https://example.com ./output
1---2name: agent-browser3description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.4---56# Browser Automation with agent-browser78## Core Workflow910Every browser automation follows this pattern:11121. **Navigate**: `agent-browser open <url>`132. **Snapshot**: `agent-browser snapshot -i` (get element refs like `@e1`, `@e2`)143. **Interact**: Use refs to click, fill, select154. **Re-snapshot**: After navigation or DOM changes, get fresh refs1617```bash18agent-browser open https://example.com/form19agent-browser snapshot -i20# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"2122agent-browser fill @e1 "user@example.com"23agent-browser fill @e2 "password123"24agent-browser click @e325agent-browser wait --load networkidle26agent-browser snapshot -i # Check result27```2829## Command Chaining3031Commands can be chained with `&&` in a single shell invocation. The browser persists between commands via a background daemon.3233```bash34# Chain open + wait + snapshot in one call35agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i3637# Chain multiple interactions38agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "password123" && agent-browser click @e339```4041## Essential Commands4243```bash44# Navigation45agent-browser open https://example.com46agent-browser go back47agent-browser reload4849# Snapshots (Text/DOM)50agent-browser snapshot -i # Include interactive refs (@e1)51agent-browser snapshot -i --all # Include hidden/non-interactive5253# Interaction54agent-browser click @e155agent-browser fill @e2 "Text to type"56agent-browser select @e3 "Option Value"57agent-browser hover @e458agent-browser press @e1 Enter59agent-browser scroll down6061# Verification & Waiting62agent-browser diff snapshot # Compare current state to last snapshot63agent-browser wait --load networkidle64agent-browser wait @e1 # Wait for element to appear65agent-browser wait 2000 # Wait 2000ms6667# Cleanup68agent-browser close # Close the background daemon session69```7071## Advanced Usage and Common Patterns7273For information on Mobile Testing, Form Handling, iFrames, Shadow DOM, Security Configuration, Diffing, Timeouts, Ref Lifecycle, Annotated Screenshots (Vision), Locators, and JS evaluation:7475**See [references/ADVANCED.md](references/ADVANCED.md)**7677## Deep-Dive Documentation7879| Reference | When to Use |80|-----------|-------------|81| [references/commands.md](references/commands.md) | Full command reference with all options |82| [references/snapshot-refs.md](references/snapshot-refs.md) | Ref lifecycle, invalidation rules, troubleshooting |83| [references/session-management.md](references/session-management.md) | Parallel sessions, state persistence, concurrent scraping |84| [references/authentication.md](references/authentication.md) | Login flows, OAuth, 2FA handling, state reuse |85| [references/video-recording.md](references/video-recording.md) | Recording workflows for debugging and documentation |86| [references/profiling.md](references/profiling.md) | Chrome DevTools profiling for performance analysis |87| [references/proxy-support.md](references/proxy-support.md) | Proxy configuration, geo-testing, rotating proxies |8889## Ready-to-Use Templates9091| Template | Description |92|----------|-------------|93| [templates/form-automation.sh](templates/form-automation.sh) | Form filling with validation |94| [templates/authenticated-session.sh](templates/authenticated-session.sh) | Login once, reuse state |95| [templates/capture-workflow.sh](templates/capture-workflow.sh) | Content extraction with screenshots |9697```bash98./templates/form-automation.sh https://example.com/form99./templates/authenticated-session.sh https://app.example.com/login100./templates/capture-workflow.sh https://example.com ./output101```
d-o-hub