agent-browser-commands
[INTERNAL TEMPLATE] Command reference for agent-browser CLI. Used by agent-browser orchestrator during execution.
How do I install this agent skill?
npx skills add https://github.com/owenleezy/agent-browser-skill --skill agent-browser-commandsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill is a command reference for a browser automation tool. It describes a comprehensive set of features for navigating the web, interacting with page elements, and accessing browser data such as cookies and local storage. While these are standard capabilities for browser automation, the skill is inherently susceptible to indirect prompt injection when processing untrusted content from the web.
- Socketpass
No alerts
- Snykfail
Risk: HIGH · 2 issues
What does this agent skill do?
Agent Browser — Command Reference
Internal reference. For browser automation tasks, use
agent-browserskill 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-stdinover--passwordto 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 |
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/owenleezy/agent-browser-skill/agent-browser-commands">View agent-browser-commands on skillZs</a>