Agent Browser — Command Reference
Internal reference. For browser automation tasks, use agent-browser skill as entry point.
Navigation
| Command |
Description |
Use Cases |
open <url> |
Navigate to URL (supports chrome:// and chrome-extension://) |
Starting point for all tasks |
back / forward |
Browser history |
Multi-page flow backtracking |
reload |
Refresh page |
Force refresh state |
close |
Close browser |
Task end cleanup |
Discovery
| Command |
Description |
Use Cases |
snapshot |
Accessibility tree with refs |
Get interactive element references |
snapshot -i |
Interactive elements only |
Focus on actionable elements |
snapshot -c |
Compact (less noise) |
Reduce output noise on large pages |
snapshot -d <n> |
Limit tree depth |
View top-level structure only |
snapshot -s <sel> |
Scope to CSS selector |
Popup/local area focus |
Interaction
| Command |
Description |
Use Cases |
click @e1 |
Click element |
Button/link trigger |
dblclick @e1 |
Double-click element |
Editable cell/selected text |
fill @e1 "text" |
Clear and fill input |
Form input (replace original value) |
type @e1 "text" |
Type without clearing (appends) |
Append content/controlled component |
keyboard type "text" |
Type into focused element — fires keydown/keypress/input/keyup per character, but does NOT reliably trigger document-level keydown listeners; use eval dispatchEvent(new KeyboardEvent(...)) for document-scoped event handlers |
Input when focus is already on target |
keyboard inserttext "text" |
Insert text bypassing ALL key events (no keydown/keypress/keyup fired) |
Insert text directly bypassing keyboard event interception |
press <key> |
Press named key: Enter, Tab, Control+a, ArrowDown |
Submit form/shortcut keys/arrow keys |
focus @e1 |
Focus element |
Focus then keyboard type |
check @e1 / uncheck @e1 |
Checkbox/radio |
Checkbox/radio operation |
select @e1 "option" |
Dropdown selection |
<select> dropdown menu |
hover @e1 |
Mouse hover |
Trigger hover menu/Tooltip |
drag @e1 @e2 |
Drag source element onto target — uses Playwright's pointer-based drag; works for mouse-event draggable libraries (Sortable.js, jQueryUI). Does NOT dispatch HTML5 DragEvent (dragstart/dragover/drop); for HTML5 Drag API use eval to dispatch DragEvent manually |
Kanban sorting/pointer drag |
upload @e1 <file> |
Upload file |
File upload form |
download @e1 <path> |
Download file by clicking element |
Export button triggers download |
scroll down |
Scroll page (up/down/left/right) |
Trigger lazy loading/load more |
scroll down --selector ".modal" |
Scroll within a specific container |
Popup content scrolling |
scrollintoview @e1 |
Scroll element into view |
Before clicking when element is not in viewport |
Dialog
| Command |
Description |
Use Cases |
dialog accept |
Accept alert/confirm dialog |
Confirmation action popups |
dialog accept "text" |
Accept prompt dialog with input |
Confirm after Prompt input |
dialog dismiss |
Dismiss/cancel dialog |
Cancel operation/close alert |
dialog status |
Check if a dialog is currently open |
Assert whether popup exists |
Mouse (fine control)
Dispatches pointer/mouse events at pixel coordinates. Use for canvas, drawing apps, and CSS/pointer-event-based draggable components. Does NOT trigger HTML5 Drag API events (dragstart/dragover/drop) — those require eval DragEvent.
| Command |
Description |
Use Cases |
mouse move <x> <y> |
Move mouse to coordinates |
Canvas/drawing applications |
mouse down [btn] |
Mouse button down |
Drag start point |
mouse up [btn] |
Mouse button up |
Drag end point |
mouse wheel <dy> [dx] |
Scroll wheel |
Precise scroll amount control |
Get Info
| Command |
Description |
Use Cases |
get text @e1 |
Get element text |
Assert displayed content |
get html @e1 |
Get inner HTML |
Complex structure inspection |
get value @e1 |
Get input value |
Form current value verification |
get attr @e1 href |
Get attribute |
Link/data attribute inspection |
get title / get url |
Page info |
Route verification after navigation |
get count "selector" |
Count matching elements |
List item count assertion |
get box @e1 |
Bounding box (x, y, width, height) |
Precise coordinates/screenshot cropping |
get styles @e1 |
Computed styles |
CSS style debugging |
get cdp-url |
CDP WebSocket URL for the active page |
Advanced CDP debugging |
State Check
| Command |
Description |
Use Cases |
is visible @e1 |
Check if visible |
Element visibility assertion |
is enabled @e1 |
Check if enabled |
Button interactability assertion |
is checked @e1 |
Check if checked |
Checkbox state assertion |
Waiting
| Command |
Description |
Use Cases |
wait @e1 |
Wait for element to appear |
Asynchronous content rendering |
wait @e1 --state hidden |
Wait for element to disappear |
Loading spinner disappears |
wait @e1 --state detached |
Wait for element to be removed from DOM |
Continue after popup closes |
wait 1000 |
Wait milliseconds |
CSS transition animation completes |
wait --load networkidle |
Wait for network to be idle |
After page load/navigation |
wait --url "**/dashboard" |
Wait for URL to match pattern |
Redirect verification after login |
wait --fn "window.ready" |
Wait for JavaScript expression to be truthy |
Custom loading completion signal |
wait --text "Welcome" |
Wait for text to appear on page |
Asynchronous text rendering |
wait --download [path] |
Wait for a download to complete |
Wait for completion after triggering download |
Capture
| Command |
Description |
Use Cases |
screenshot [path] |
Take screenshot |
Current viewport snapshot |
screenshot --full |
Full page screenshot |
Full page record/evidence |
screenshot --annotate |
Annotated screenshot with numbered labels |
Bug report/documentation screenshots |
pdf <path> |
Save as PDF |
Generate printable report |
Screenshot options: --screenshot-dir <path> (default dir), --screenshot-quality <0-100> (JPEG), --screenshot-format png|jpeg
Diff & Visual Regression
diff snapshot
agent-browser diff snapshot # vs last snapshot in session
agent-browser diff snapshot --baseline before.txt # vs saved snapshot file
agent-browser diff snapshot -s ".sidebar" # scope to selector
agent-browser diff snapshot -c -d 3 # compact + depth limit
Use Cases: DOM structure change detection, before-and-after comparison
diff screenshot
agent-browser diff screenshot --baseline before.png
agent-browser diff screenshot --baseline before.png --output diff.png --threshold 0.1
agent-browser diff screenshot --baseline before.png -s "#main-content" --full
Use Cases: Visual regression testing,--threshold 0~1(default 0.1, smaller is stricter)
diff url
agent-browser diff url https://staging.example.com https://prod.example.com
agent-browser diff url https://v1.example.com https://v2.example.com --screenshot --full
agent-browser diff url <u1> <u2> --wait-until networkidle
Use Cases: Cross-environment/version comparison,--screenshot compare screenshots simultaneously
Debug
| Command |
Description |
Use Cases |
inspect |
Open Chrome DevTools (CLI still works) |
Interactive debugging |
console |
View console logs |
View JS output |
console --pattern "err" |
Filter console logs |
Quickly locate error logs |
console --clear |
Clear console log buffer |
Reset observation window |
errors |
View JavaScript errors |
Check first, covers 80% of issues |
errors --clear |
Clear error buffer |
Reset error count |
highlight <sel> |
Highlight element visually |
Visually confirm the location |
network requests |
View all network requests |
Full API call records |
network requests --filter "api" |
Filter by URL pattern |
Focus on a specific endpoint |
network requests --type xhr,fetch |
Filter by resource type |
Only view XHR/Fetch |
network requests --method POST |
Filter by HTTP method |
Only view write operations |
network requests --status 4xx |
Filter by status code |
Quickly find failed requests |
network requests --clear |
Clear network log |
Reset records |
network request <requestId> |
View full request + response body |
Check the full payload |
network har start [path] |
Start HAR recording |
Starting point for full network tracing |
network har stop |
Stop and save HAR file |
Export for DevTools analysis |
trace start [path] |
Start Playwright trace recording |
Playwright debug tracing |
trace stop |
Stop trace |
Open with Playwright Trace Viewer |
profiler start [path] |
Start Chrome DevTools profiler |
Performance analysis |
profiler stop |
Stop profiler |
Export performance report |
record start <path> [url] |
Start video recording (WebM) |
Record demo/Bug reproduction |
record stop |
Stop and save video |
Save video |
record restart <path> [url] |
Stop current + start new recording |
Re-record (retake) |
eval "JS code" |
Execute JavaScript |
Custom query/state injection |
clipboard read |
Read clipboard content |
Verify the copied result |
clipboard write "text" |
Write to clipboard |
Inject clipboard data |
clipboard copy <sel> |
Copy element text to clipboard |
Extract content |
clipboard paste <sel> |
Paste clipboard into element |
Paste into the input field |
Network Mocking
| Command |
Description |
Use cases |
network route "**/*.png" --abort |
Block matching requests |
Block images/ads to speed up loading |
network route "**/api/**" --body '{"ok":true}' |
Mock response body |
Test specific API responses |
network unroute [url] |
Remove route (all if no url) |
Restore the real network |
Storage
| Command |
Description |
Use cases |
cookies |
View all cookies |
Session state check |
cookies set <name> <val> --domain example.com --secure --httpOnly |
Set cookie |
Inject Auth token |
cookies clear |
Clear all cookies |
Reset session state |
storage local |
View localStorage |
View persisted data |
storage local get <key> |
Get localStorage key |
Read a specific key |
storage local set <key> <val> |
Set localStorage key |
Inject token/config |
storage local clear |
Clear localStorage |
Reset frontend state |
storage session get <key> |
SessionStorage (same API) |
Session-level data operations |
Tabs
| Command |
Description |
Use cases |
tab new |
Open new tab |
Multi-tab workflow |
tab list |
List all tabs in current browser context |
View known tabs |
tab <n> |
Switch to tab by index (0-based) |
Switch to the target tab |
tab close <n> |
Close tab by index |
Close auxiliary tabs |
target="_blank" Limitation: when clicking a target="_blank" link, the browser may open it in a new BrowserContext, and agent-browser's tab list only tracks tabs within the current context. If the new tab does not appear in tab list , use tab new + open <url> to manage it manually.
Sessions
| Command |
Description |
Use cases |
session |
Show current session name |
Confirm the current session |
session list |
List active sessions |
View multiple concurrent sessions |
Auth Vault
Save and reuse login credentials — avoids manual login in every E2E run:
# Save once
agent-browser auth save myapp --url http://localhost:5173/login --username admin --password secret
# Reuse in any test (auto-fills and submits login form)
agent-browser auth login myapp
# Manage
agent-browser auth list
agent-browser auth show myapp
agent-browser auth delete myapp
Credentials are encrypted with AES-256-GCM (AGENT_BROWSER_ENCRYPTION_KEY). Prefer --password-stdin over --password to avoid shell history exposure.
Batch Execution
Execute multiple commands from stdin as a JSON array — more efficient than sequential shell calls:
echo '[["fill","@e1","user@example.com"],["fill","@e2","pass"],["click","@e3"]]' | agent-browser batch
agent-browser batch --bail # stop on first error (default: continue all)
Confirmation
For actions that require explicit approval (when --confirm-actions is set):
| Command |
Description |
Use cases |
confirm <id> |
Approve a pending action |
Approve write operations |
deny <id> |
Deny a pending action |
Reject dangerous operations |
Device / Emulation
| Command |
Description |
Use cases |
set viewport <w> <h> |
Set viewport size |
Responsive testing |
set viewport <w> <h> <scale> |
Set viewport with device pixel ratio |
Retina display testing |
set device "iPhone 15 Pro" |
Preset device emulation |
Full mobile emulation |
set geo <lat> <lng> |
Set geolocation |
Geolocation feature testing |
set offline [on|off] |
Toggle offline mode (always restore with set offline off) |
PWA/offline mode testing |
set headers <json> |
Set HTTP headers scoped to page origin |
Inject Authorization |
set credentials <user> <pass> |
HTTP basic auth |
Basic Auth sites |
set media dark |
Dark mode |
Dark theme testing |
set media dark reduced-motion |
Dark + reduced motion |
Accessibility testing |
iOS Simulator (requires Xcode + Appium): use -p ios flag
agent-browser -p ios open http://localhost:3000
agent-browser -p ios --device "iPhone 15 Pro" snapshot
agent-browser -p ios device list
agent-browser -p ios swipe up
Setup
| Command |
Description |
Use cases |
install |
Download Chromium (first time setup) |
First-time installation |
install --with-deps |
Also install system dependencies (Linux) |
Linux CI environment |
upgrade |
Upgrade agent-browser to latest (npm only; Homebrew: brew upgrade agent-browser) |
Version update |
Semantic Locators (find)
Preferred over CSS selectors — survives UI refactoring:
agent-browser find role button click --name "Submit"
agent-browser find role link click --name "Learn More"
agent-browser find role button click --name "Submit" --exact # exact name match
agent-browser find text "Sign In" click
agent-browser find label "Email" fill "user@example.com"
agent-browser find placeholder "Search..." type "query"
agent-browser find testid "submit-button" click
agent-browser find alt "Company logo" click
agent-browser find first "button.primary" click
agent-browser find last "a.link" click
agent-browser find nth 2 ".card" hover # 0-based index
Valid find subcommands: role, text, label, placeholder, alt, title, testid, first, last, nth
❌ find ref does NOT exist.
Using Refs from Snapshot
snapshot returns refs like [ref=e3]. These can be used directly with action commands — NOT via find:
# ✅ Direct ref usage
agent-browser click @e3
agent-browser fill @e3 "hello"
agent-browser hover @e3
# ✅ Refs in assertions
agent-browser is visible @e3
agent-browser get text @e3
agent-browser get value @e3
# ❌ Wrong — ref is not a find subcommand
agent-browser find ref e3 fill "hello"
Global Options
| Option |
Description |
--headed |
Show browser window; also via AGENT_BROWSER_HEADED=1 |
--engine chrome|lightpanda |
Browser engine; also via AGENT_BROWSER_ENGINE |
-p, --provider <name> |
Browser provider: ios, browserbase, kernel, browseruse, browserless |
--cdp <port> |
Connect to Chrome via CDP |
--auto-connect |
Auto-discover running Chrome |
--profile <path> |
Persistent browser profile (auth reuse) |
--session <name> |
Isolated session |
--session-name <name> |
Auto-save/restore cookies & localStorage |
--state <path> |
Load storage state from JSON |
--download-path <path> |
Default download directory; also via AGENT_BROWSER_DOWNLOAD_PATH |
--headers '{"Authorization":"Bearer token"}' |
Auth headers |
--proxy "http://127.0.0.1:7890" |
Proxy server (also reads HTTP_PROXY / HTTPS_PROXY / ALL_PROXY env vars as fallback) |
--proxy-bypass "localhost,*.internal" |
Bypass proxy (also reads NO_PROXY env var) |
--color-scheme dark|light |
Color scheme preference |
--ignore-https-errors |
Ignore TLS certificate errors |
--allow-file-access |
Allow file:// URL access |
--user-agent <ua> |
Custom User-Agent |
--allowed-domains <list> |
Restrict to approved domains (security); --domain-allowlist is an alias |
--action-policy <path> |
JSON file defining allowed/blocked action categories |
--confirm-actions <list> |
Action categories requiring confirmation |
--confirm-interactive |
Interactive confirmation prompts in TTY |
--content-boundaries |
Wrap page output in boundary markers (helps parse --max-output) |
--max-output <chars> |
Truncate page output to N chars; also via AGENT_BROWSER_MAX_OUTPUT |
--json |
JSON output |
--full / -f |
Full page (screenshot) |
--annotate |
Annotated output |
--debug |
Debug output |
Key Environment Variables
| Variable |
Description |
AGENT_BROWSER_HEADED=1 |
Show browser window |
AGENT_BROWSER_ENGINE=chrome|lightpanda |
Browser engine (chrome is default) |
AGENT_BROWSER_NATIVE=1 |
⚠️ Legacy alias — accepted but undocumented in 0.22+; prefer omitting (chrome engine is default) |
AGENT_BROWSER_DEFAULT_TIMEOUT |
Default action timeout in ms (default: 25000) |
AGENT_BROWSER_MAX_OUTPUT |
Max characters for page output |
AGENT_BROWSER_STREAM_PORT |
Enable WebSocket streaming on port (e.g., 9223) |
AGENT_BROWSER_IDLE_TIMEOUT_MS |
Auto-shutdown daemon after N ms of inactivity |
AGENT_BROWSER_ENCRYPTION_KEY |
64-char hex key for AES-256-GCM Auth Vault encryption |
AGENT_BROWSER_SCREENSHOT_DIR |
Default screenshot output directory |
