Browser Automation with BrowserOS

Control a real Chromium browser via browseros-cli. Run commands via Bash. Use --json for structured output, -p <pageId> to target specific tabs.

When NOT to Use

- Headless scraping in CI/CD with no display — use Playwright or Puppeteer instead.
Static page fetching where curl/wget suffices.

Safety Defaults

- Default to read-only first: snap, text, links, pages, ss.
Avoid eval unless no simpler command works.
Save screenshots/PDFs only to user-specified or workspace paths.
Close tabs when done: browseros-cli close <pageId>.

Setup

CODEBLOCK0

Core Workflow: snap → act → re-snap

Every interaction follows this loop:

1. Open a page → get a page ID.
Snap → get element IDs like [10] textbox "Email", [15] button "Submit".
Act on elements by ID (fill 10 "text", click 15).
Re-snap after ANY click, navigation, or form submit — IDs change after DOM updates.

Critical rules:

- open <url> = new tab. nav <url> = navigate current tab.
NEVER reuse element IDs after navigation — always snap again.
Use text for content extraction, snap for interaction, ss for visual verification.

CODEBLOCK1

Commands Quick Reference

Category	Key Commands
Navigate	INLINECODE22, `open --hidden`, `nav <url>`, `back`, `forward`, `reload`, `pages`, `active`, INLINECODE30
Observe

snap, snap -e, text, text --selector <css>, text --links, text --viewport, links, ss -o <path>, ss --full, eval "<js>", dom, dom-search "<q>", wait --text "<txt>" | | Input | click <id>, click --double, fill <id> "text", clear <id>, key Enter, hover <id>, focus <id>, check <id>, uncheck <id>, select <id> "val", scroll down [amt], drag <id> --to <id>, upload <id> <file>, dialog accept/dismiss | | Export | pdf <path>, download <id> <dir> | | Resources | window list/create/close/activate, bookmark list/search/create/remove/update/move, history recent/search/delete, group list/create/update/ungroup/close |

Full flags and options: see references/cli-commands.md or run browseros-cli <command> --help.

Common Patterns

Data extraction

CODEBLOCK2

Multi-tab research

CODEBLOCK3

Web app testing

CODEBLOCK4

Common Mistakes

Mistake	Fix
Using CSS selectors (`fill --selector "input[type=email]"`)	Always `snap` first, then use element IDs (`fill 10 "text"`)
Reusing element IDs after a click or navigation

IDs are invalidated by DOM changes — snap again | | Using eval to extract text | Use text or text --selector instead — lower tokens, structured output | | Forgetting to close tabs | Always close <pageId> when done to avoid resource leaks | | Using nav when you want a new tab | nav replaces the current tab. Use open for a new tab | | Using open when you want to stay in the same tab | open creates a new tab. Use nav to navigate in place | | Taking screenshots for content extraction | Use text for content — screenshots burn tokens and need vision | | Using dialog --accept (flag syntax) | Correct syntax is dialog accept or dialog dismiss (positional arg) |

Deep-Dive Documentation

Reference	Description
references/cli-commands.md	Full command reference with all flags

使用BrowserOS进行浏览器自动化

通过browseros-cli控制真实的Chromium浏览器。使用Bash运行命令。使用--json获取结构化输出，使用-p 定位特定标签页。

何时不使用

- 在无显示器的CI/CD环境中进行无头抓取——请改用Playwright或Puppeteer。
使用curl/wget即可满足的静态页面获取。

安全默认设置

- 默认优先使用只读操作：snap、text、links、pages、ss。
除非没有更简单的命令可用，否则避免使用eval。
仅将截图/PDF保存到用户指定或工作区路径。
完成后关闭标签页：browseros-cli close 。

安装设置

bash

检查CLI是否可用

browseros-cli --version

如果未安装：

npm install -g browseros-cli

如果未安装BrowserOS应用：

browseros-cli install

如果BrowserOS未运行：

browseros-cli launch

配置连接：

browseros-cli init --auto

验证：

browseros-cli health

核心工作流：snap → act → re-snap

每次交互都遵循此循环：

1. 打开页面 → 获取页面ID。
快照 → 获取元素ID，如[10] textbox Email、[15] button Submit。
操作元素（通过ID操作：fill 10 text、click 15）。
重新快照——在任何点击、导航或表单提交后——DOM更新后ID会改变。

关键规则：

- open = 新建标签页。nav = 在当前标签页导航。
导航后切勿重复使用元素ID——始终重新snap。
使用text提取内容，snap进行交互，ss进行视觉验证。

bash
browseros-cli open https://example.com/login # → 页面ID: 5
browseros-cli snap -p 5 # → [10] textbox Email, [11] textbox Password, [15] button Sign In
browseros-cli fill 10 user@example.com
browseros-cli fill 11 password123
browseros-cli click 15
browseros-cli snap -p 5 # 重新快照！提交后ID已改变
browseros-cli text -p 5 # 读取结果页面
browseros-cli close 5 # 清理

命令快速参考

类别	关键命令
导航	open <url>、open --hidden、nav <url>、back、forward、reload、pages、active、close [id]
观察

snap、snap -e、text、text --selector 、text --links、text --viewport、links、ss -o 、ss --full、eval 、dom、dom-search 、wait --text | | 输入 | click 、click --double、fill text、clear 、key Enter、hover 、focus 、check 、uncheck 、select val、scroll down [amt]、drag --to 、upload 、dialog accept/dismiss | | 导出 | pdf 、download | | 资源 | window list/create/close/activate、bookmark list/search/create/remove/update/move、history recent/search/delete、group list/create/update/ungroup/close |

完整标志和选项：参见references/cli-commands.md或运行browseros-cli --help。

常见模式

数据提取

bash browseros-cli open https://example.com/data browseros-cli text # 完整页面以markdown格式输出 browseros-cli text --selector table # 限定到特定元素 browseros-cli text --links # 包含超链接

多标签页研究

bash browseros-cli open https://site-a.com # → 页面ID: 1 browseros-cli open https://site-b.com # → 页面ID: 2 browseros-cli text -p 1 # 从第一个提取 browseros-cli text -p 2 # 从第二个提取 browseros-cli close 1 && browseros-cli close 2

Web应用测试

bash browseros-cli open http://localhost:3000 browseros-cli snap # 获取交互元素 browseros-cli ss -o test-state.png # 视觉快照 browseros-cli eval document.querySelectorAll(.error).length

常见错误

错误	修正
使用CSS选择器（fill --selector input[type=email]）	始终先snap，然后使用元素ID（fill 10 text）
在点击或导航后重复使用元素ID

深入文档

参考文档	描述
references/cli-commands.md	完整命令参考，包含所有标志