浏览 CLI
AI代理的浏览器自动化CLI. 建造在 阶段手,提供原始浏览器控制而无需LLM集成.
安装
npm install -g @browserbasehq/browse-cli
需要安装在系统中的铬/铬.
快速启动
# Navigate to a URL (auto-starts browser daemon)
browse open https://example.com
# Take a snapshot to get element refs
browse snapshot -c
# Click an element by ref
browse click @0-5
# Type text
browse type "Hello, world!"
# Take a screenshot
browse screenshot ./page.png
# Stop the browser
browse stop
如何运作
浏览使用守护进程架构进行快速,状态的交互:
- 第一个命令 自动启动 Chrome 浏览器守护进程
- 随后的命令 重用同一浏览器会话
- 国家持续存在 命令之间 (cookies, refs等)
- 多会 支持通过
--session或者说BROWSE_SESSION环境 var
自愈会
CLI会自动从陈旧的会话中恢复. 如果守护进程或克罗姆崩溃:
- 检测失败
- 清理陈旧的进程和文件
- 重新启动守护进程
- 重试命令
特工不需要处理恢复 - 命令"只是工作".
图标
导航
browse open <url> [--wait load|domcontentloaded|networkidle] [-t|--timeout ms]
browse reload
browse back
browse forward
这个 --timeout 旗 (默认: 3000ms) 控制等待页面负载状态的时间 。 对慢装页面使用较长的超时 :
browse open https://slow-site.com --timeout 60000
单击动作
browse click <ref> [-b left|right|middle] [-c count] # Click by ref (e.g., @0-5)
browse click_xy <x> <y> [--button] [--xpath] # Click at coordinates
协调行动
browse hover <x> <y> [--xpath]
browse scroll <x> <y> <deltaX> <deltaY> [--xpath]
browse drag <fromX> <fromY> <toX> <toY> [--steps n] [--xpath]
键盘
browse type <text> [-d delay] [--mistakes]
browse press <key> # e.g., Enter, Tab, Cmd+A
表单
browse fill <selector> <value> [--no-press-enter]
browse select <selector> <values...>
browse highlight <selector> [-d duration]
页面信息
browse get url
browse get title
browse get text <selector>
browse get html <selector>
browse get value <selector>
browse get box <selector> # Returns center coordinates
browse snapshot [-c|--compact] # Accessibility tree with refs
browse screenshot [path] [-f|--full-page] [-t png|jpeg]
等待时
browse wait load [state]
browse wait selector <selector> [-t timeout] [-s visible|hidden|attached|detached]
browse wait timeout <ms>
多标签
browse pages # List all tabs
browse newpage [url] # Open new tab
browse tab_switch <n> # Switch to tab by index
browse tab_close [n] # Close tab (default: last)
网络抓取
抓取 HTTP 请求到文件系统检查 :
browse network on # Start capturing requests
browse network off # Stop capturing
browse network path # Get capture directory path
browse network clear # Clear captured requests
抓取的请求被保存为目录 :
/tmp/browse-default-network/
001-GET-api.github.com-repos/
request.json # method, url, headers, body
response.json # status, headers, body, duration
守护进程控制
browse start # Explicitly start daemon
browse stop [--force] # Stop daemon
browse status # Check daemon status
browse env [target] # Show or switch environment: local | remote
环境切换( 本地对远程)
当代理机应该保持相同的指令流时使用环境切换,但是 浏览器运行时间需要更改 :
local在您的机器上运行 Chrome( 最适合本地调试/ dev 循环)remote运行浏览器会话(最适合反机器人硬化和云运行)
# Show active environment (if running) and desired environment for next start
browse env
# Switch current session to Browserbase (restarts daemon if needed)
browse env remote
# Switch back to local Chrome (clean isolated browser by default)
browse env local
本地浏览器策略
默认, browse env local 发射一个干净的孤立本地浏览器.
使用 browse env local --auto-connect 选择重用已运行的
启用远程调试的 Chrome 。 如果找不到可调试的 Chrome, 它
回到发射一个孤立的浏览器.
# Use a clean isolated browser (default)
browse env local
# Auto-discover local Chrome, fallback to isolated
browse env local --auto-connect
# Attach to a specific CDP target (port or URL)
browse env local 9222
browse env local ws://localhost:9222/devtools/browser/...
自动发现检查 :
DevToolsActivePort众所周知的克罗姆/克罗姆/布拉夫用户数据目录中的文档- 常见调试端口( 9222, 9229)
让你的克洛姆可以发现:
- 打开
chrome://inspect/#remote-debugging - 检查框 浏览器实例 Allow 远程调试
更多信息,请参见 Chrome DevTools 文档。 。 。 .
使用 browse status 找出解决了哪些战略:
browse status
# {"running":true,"session":"default","mode":"local","localStrategy":"isolated","localSource":"isolated"}
一般行为
- 环境范围为每
--session browse env <target>持续覆盖并重新启动守护进程browse stop清除覆盖, 所以下一个开始会回到基于 env- var 的自动检测- 自动检测默认为 :
remote何时BROWSERBASE_API_KEY设定local否则
全球选项
| 选项 | 说明 |
|---|---|
--session <name> | 多个浏览器的会话名称( 默认: “ 默认 ” ) |
--headless | 在无头模式下运行 Chrome |
--headed | 用可见窗口运行 Chrome( 默认) |
--ws <url|port> | 一发 CDP 连接( 通过守护进程) |
--json | 输出为 JSON |
环境变量
| 变量 | 说明 |
|---|---|
BROWSE_SESSION | 默认会话名称( 以 --session(中文(简体) ) |
BROWSERBASE_API_KEY | 浏览器库 API 密钥( 需要 browse env remote(中文(简体) ) |
元素参考文献
运行后 browse snapshot,您可以通过他们的参考ID参考元素:
# Get snapshot with refs
browse snapshot -c
# Output includes refs like [0-5], [1-2], etc.
# RootWebArea "Example" url="https://example.com"
# [0-0] link "Home"
# [0-1] link "About"
# [0-2] button "Sign In"
# Click using ref (multiple formats supported)
browse click @0-2 # @ prefix
browse click 0-2 # Plain ref
browse click ref=0-2 # Explicit prefix
完整的快照产出包括绘图:
- ưμ㼯A: 跨框架 XPath 选择器
- 缩写: 可用时快速 CSS 选择器
- uRL地图: 从链接提取的 URL
多个会话
同时运行多个浏览器实例 :
# Terminal 1
BROWSE_SESSION=session1 browse open https://google.com
# Terminal 2
BROWSE_SESSION=session2 browse open https://github.com
# Or use --session flag
browse --session work open https://slack.com
browse --session personal open https://twitter.com
直接 CDP 连接
选择使用已存在的 Chrome 实例 :
让你的克洛姆可以发现:
- 打开
chrome://inspect/#remote-debugging - 检查框 浏览器实例 Allow 远程调试
- 启用自动连接后重新运行 CLI .
更多信息,请参见 Chrome DevTools 文档。 。 。 .
# Auto-discover Chrome with remote debugging enabled
browse env local --auto-connect
browse open https://example.com
# Or target a specific port / WebSocket URL
browse env local 9222
browse --ws ws://localhost:9222/devtools/browser/... open https://example.com
优化 AI 工作流程
- 导航 转到目标页面(浏览器自动启动)
- 抓图 获取可访问性树 :
- 点击/填充 直接使用参考文献(例如,
@0-5(中文(简体) ) - 重新拍摄 在核实状态变化的行动之后
- 停下来 完成时
browse open https://example.com
browse snapshot -c
# [0-5] textbox: Search
# [0-8] button: Submit
browse fill @0-5 "my query"
browse click @0-8
browse snapshot -c # Verify result
browse stop
解决问题
找不到颜色
CLI使用你的系统Chrome/Chrome. 未找到的 :
# macOS - Install Chrome or set path
export CHROME_PATH=/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
# Linux - Install chromium
sudo apt install chromium-browser
Stale 守护进程
如果守护进程失去响应:
browse stop --force
套接字权限被拒绝
# Clean up stale socket files
rm /tmp/browse-*.sock /tmp/browse-*.pid
平台支持
- macOS (英特尔和苹果硅)
- Linux (x64和arm64) (英语)
Windows支持需要WSL或TCP socket执行.
发展
# Clone and setup (in monorepo)
cd packages/cli
pnpm install # Install dependencies first!
pnpm run build # Build the CLI
# Run without building (for development)
pnpm run dev -- <command>
# Or with tsx directly
npx tsx src/index.ts <command>
# Run linting and formatting
pnpm run lint
pnpm run format
许可证
麻省理工学院 - 看 自由主义