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.
```bash
# 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:
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