Browser Automation with BrowserOS

Control a real Chromium browser via browseros-cli. Run commands via Bash. Use --json for structured output, -p \x3CpageId> 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 \x3CpageId>.

Setup

# Check if CLI is available
browseros-cli --version

# If not installed:
npm install -g browseros-cli

# If BrowserOS app is not installed:
browseros-cli install

# If BrowserOS is not running:
browseros-cli launch

# Configure connection:
browseros-cli init --auto

# Verify:
browseros-cli health

Core Workflow: snap → act → re-snap

Every interaction follows this loop:

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

Critical rules:

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

browseros-cli open https://example.com/login    # → Page ID: 5
browseros-cli snap -p 5                          # → [10] textbox "Email", [11] textbox "Password", [15] button "Sign In"
browseros-cli fill 10 "[email protected]"
browseros-cli fill 11 "password123"
browseros-cli click 15
browseros-cli snap -p 5                          # Re-snap! IDs have changed after submit
browseros-cli text -p 5                          # Read result page
browseros-cli close 5                            # Clean up

Commands Quick Reference

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

Common Patterns

Data extraction

browseros-cli open https://example.com/data
browseros-cli text                         # full page as markdown
browseros-cli text --selector "table"      # scoped to element
browseros-cli text --links                 # include hyperlinks

Multi-tab research

browseros-cli open https://site-a.com      # → Page ID: 1
browseros-cli open https://site-b.com      # → Page ID: 2
browseros-cli text -p 1                    # extract from first
browseros-cli text -p 2                    # extract from second
browseros-cli close 1 && browseros-cli close 2

Web app testing

browseros-cli open http://localhost:3000
browseros-cli snap                         # get interactive elements
browseros-cli ss -o test-state.png         # visual snapshot
browseros-cli eval "document.querySelectorAll('.error').length"

Common Mistakes

Deep-Dive Documentation

Links

• BrowserOS
• CLI Source
• MCP Setup Guide
• Skills Repository