Agent Browser — Command Reference
Internal reference. For browser automation tasks, use agent-browser skill as entry point.
Navigation
| Command |
Description |
适用场景 |
open <url> |
Navigate to URL (supports chrome:// and chrome-extension://) |
所有任务起点 |
back / forward |
Browser history |
多页流程回溯 |
reload |
Refresh page |
强制刷新状态 |
close |
Close browser |
任务结束清理 |
Discovery
| Command |
Description |
适用场景 |
snapshot |
Accessibility tree with refs |
获取交互元素引用 |
snapshot -i |
Interactive elements only |
聚焦可操作元素 |
snapshot -c |
Compact (less noise) |
大页面减少输出噪音 |
snapshot -d <n> |
Limit tree depth |
只看顶层结构 |
snapshot -s <sel> |
Scope to CSS selector |
弹窗/局部区域聚焦 |
Interaction
| Command |
Description |
适用场景 |
click @e1 |
Click element |
按钮/链接触发 |
dblclick @e1 |
Double-click element |
可编辑单元格/选中文本 |
fill @e1 "text" |
Clear and fill input |
表单输入（替换原值） |
type @e1 "text" |
Type without clearing (appends) |
追加内容/受控组件 |
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 |
焦点已在目标时输入 |
keyboard inserttext "text" |
Insert text bypassing ALL key events (no keydown/keypress/keyup fired) |
绕过键盘事件拦截直接插入文本 |
press <key> |
Press named key: Enter, Tab, Control+a, ArrowDown |
提交表单/快捷键/方向键 |
focus @e1 |
Focus element |
聚焦后再 keyboard type |
check @e1 / uncheck @e1 |
Checkbox/radio |
复选框/单选操作 |
select @e1 "option" |
Dropdown selection |
<select> 下拉菜单 |
hover @e1 |
Mouse hover |
触发悬停菜单/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 |
看板排序/指针拖拽 |
upload @e1 <file> |
Upload file |
文件上传表单 |
download @e1 <path> |
Download file by clicking element |
导出按钮触发下载 |
scroll down |
Scroll page (up/down/left/right) |
触发懒加载/加载更多 |
scroll down --selector ".modal" |
Scroll within a specific container |
弹窗内容滚动 |
scrollintoview @e1 |
Scroll element into view |
元素不在视口时点击前 |
Dialog
| Command |
Description |
适用场景 |
dialog accept |
Accept alert/confirm dialog |
确认操作类弹窗 |
dialog accept "text" |
Accept prompt dialog with input |
Prompt 输入后确认 |
dialog dismiss |
Dismiss/cancel dialog |
取消操作/关闭 alert |
dialog status |
Check if a dialog is currently open |
断言弹窗是否存在 |
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 |
适用场景 |
mouse move <x> <y> |
Move mouse to coordinates |
Canvas/绘图应用 |
mouse down [btn] |
Mouse button down |
拖拽起点 |
mouse up [btn] |
Mouse button up |
拖拽终点 |
mouse wheel <dy> [dx] |
Scroll wheel |
精确滚动量控制 |
Get Info
| Command |
Description |
适用场景 |
get text @e1 |
Get element text |
断言显示内容 |
get html @e1 |
Get inner HTML |
复杂结构检查 |
get value @e1 |
Get input value |
表单当前值验证 |
get attr @e1 href |
Get attribute |
链接/data属性检查 |
get title / get url |
Page info |
导航后路由验证 |
get count "selector" |
Count matching elements |
列表条目数量断言 |
get box @e1 |
Bounding box (x, y, width, height) |
精确坐标/截图裁剪 |
get styles @e1 |
Computed styles |
CSS 样式调试 |
get cdp-url |
CDP WebSocket URL for the active page |
高级 CDP 调试 |
State Check
| Command |
Description |
适用场景 |
is visible @e1 |
Check if visible |
元素显示断言 |
is enabled @e1 |
Check if enabled |
按钮可交互断言 |
is checked @e1 |
Check if checked |
复选框状态断言 |
Waiting
| Command |
Description |
适用场景 |
wait @e1 |
Wait for element to appear |
异步内容渲染 |
wait @e1 --state hidden |
Wait for element to disappear |
Loading spinner 消失 |
wait @e1 --state detached |
Wait for element to be removed from DOM |
弹窗关闭后继续 |
wait 1000 |
Wait milliseconds |
CSS 过渡动画完成 |
wait --load networkidle |
Wait for network to be idle |
页面加载/导航后 |
wait --url "**/dashboard" |
Wait for URL to match pattern |
登录后跳转验证 |
wait --fn "window.ready" |
Wait for JavaScript expression to be truthy |
自定义加载完成信号 |
wait --text "Welcome" |
Wait for text to appear on page |
异步文字渲染 |
wait --download [path] |
Wait for a download to complete |
触发下载后等待完成 |
Capture
| Command |
Description |
适用场景 |
screenshot [path] |
Take screenshot |
当前视口快照 |
screenshot --full |
Full page screenshot |
完整页面记录/证据 |
screenshot --annotate |
Annotated screenshot with numbered labels |
Bug报告/文档截图 |
pdf <path> |
Save as PDF |
生成可打印报告 |
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
适用场景：DOM 结构变化检测，前后对比
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
适用场景：视觉回归测试，--threshold 0~1（默认 0.1，越小越严格）
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
适用场景：跨环境/版本对比，--screenshot 同时对比截图
Debug
| Command |
Description |
适用场景 |
inspect |
Open Chrome DevTools (CLI still works) |
交互式调试 |
console |
View console logs |
查看 JS 输出 |
console --pattern "err" |
Filter console logs |
快速定位错误日志 |
console --clear |
Clear console log buffer |
重置观察窗口 |
errors |
View JavaScript errors |
最先查，覆盖 80% 问题 |
errors --clear |
Clear error buffer |
重置错误计数 |
highlight <sel> |
Highlight element visually |
可视化确认定位 |
network requests |
View all network requests |
全量 API 调用记录 |
network requests --filter "api" |
Filter by URL pattern |
聚焦特定接口 |
network requests --type xhr,fetch |
Filter by resource type |
只看 XHR/Fetch |
network requests --method POST |
Filter by HTTP method |
只看写操作 |
network requests --status 4xx |
Filter by status code |
快速找失败请求 |
network requests --clear |
Clear network log |
重置记录 |
network request <requestId> |
View full request + response body |
查完整 payload |
network har start [path] |
Start HAR recording |
完整网络追踪起点 |
network har stop |
Stop and save HAR file |
导出供 DevTools 分析 |
trace start [path] |
Start Playwright trace recording |
Playwright 调试追踪 |
trace stop |
Stop trace |
用 Playwright Trace Viewer 打开 |
profiler start [path] |
Start Chrome DevTools profiler |
性能分析 |
profiler stop |
Stop profiler |
导出性能报告 |
record start <path> [url] |
Start video recording (WebM) |
录制演示/Bug 复现 |
record stop |
Stop and save video |
保存视频 |
record restart <path> [url] |
Stop current + start new recording |
重新录制（重拍） |
eval "JS code" |
Execute JavaScript |
自定义查询/状态注入 |
clipboard read |
Read clipboard content |
验证复制结果 |
clipboard write "text" |
Write to clipboard |
注入剪贴板数据 |
clipboard copy <sel> |
Copy element text to clipboard |
提取内容 |
clipboard paste <sel> |
Paste clipboard into element |
粘贴到输入框 |
Network Mocking
| Command |
Description |
适用场景 |
network route "**/*.png" --abort |
Block matching requests |
屏蔽图片/广告加速加载 |
network route "**/api/**" --body '{"ok":true}' |
Mock response body |
测试特定 API 响应 |
network unroute [url] |
Remove route (all if no url) |
恢复真实网络 |
Storage
| Command |
Description |
适用场景 |
cookies |
View all cookies |
会话状态检查 |
cookies set <name> <val> --domain example.com --secure --httpOnly |
Set cookie |
注入 Auth 令牌 |
cookies clear |
Clear all cookies |
重置会话状态 |
storage local |
View localStorage |
查看持久化数据 |
storage local get <key> |
Get localStorage key |
读取特定 key |
storage local set <key> <val> |
Set localStorage key |
注入 token/配置 |
storage local clear |
Clear localStorage |
重置前端状态 |
storage session get <key> |
SessionStorage (same API) |
会话级数据操作 |
Tabs
| Command |
Description |
适用场景 |
tab new |
Open new tab |
多标签流程 |
tab list |
List all tabs in current browser context |
查看已知标签 |
tab <n> |
Switch to tab by index (0-based) |
切换到目标标签 |
tab close <n> |
Close tab by index |
关闭辅助标签 |
target="_blank" 限制：点击 target="_blank" 链接时，浏览器可能在新的 BrowserContext 中打开，agent-browser 的 tab list 只跟踪当前 context 内的标签。如果新标签没有出现在 tab list 中，改用 tab new + open <url> 手动管理。
Sessions
| Command |
Description |
适用场景 |
session |
Show current session name |
确认当前会话 |
session list |
List active 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 |
适用场景 |
confirm <id> |
Approve a pending action |
审批写操作 |
deny <id> |
Deny a pending action |
拒绝危险操作 |
Device / Emulation
| Command |
Description |
适用场景 |
set viewport <w> <h> |
Set viewport size |
响应式测试 |
set viewport <w> <h> <scale> |
Set viewport with device pixel ratio |
Retina 屏测试 |
set device "iPhone 15 Pro" |
Preset device emulation |
移动端完整模拟 |
set geo <lat> <lng> |
Set geolocation |
地理位置功能测试 |
set offline [on|off] |
Toggle offline mode (always restore with set offline off) |
PWA/离线模式测试 |
set headers <json> |
Set HTTP headers scoped to page origin |
注入 Authorization |
set credentials <user> <pass> |
HTTP basic auth |
Basic Auth 站点 |
set media dark |
Dark mode |
暗色主题测试 |
set media dark reduced-motion |
Dark + reduced motion |
无障碍测试 |
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 |
适用场景 |
install |
Download Chromium (first time setup) |
首次安装 |
install --with-deps |
Also install system dependencies (Linux) |
Linux CI 环境 |
upgrade |
Upgrade agent-browser to latest (npm only; Homebrew: brew upgrade agent-browser) |
版本更新 |
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 |
--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 |
owenleezy