browser4-cli

Browser Automation with browser4-cli

Browser automation CLI for AI agents — Chrome/Chromium via CDP with accessibility-tree snapshots.

1. Core Loop

Every browser4-cli session follows this pattern:

1. NAVIGATE    browser4-cli goto <url>              # auto-opens/reconnects session
2. SNAPSHOT    browser4-cli snapshot -v 0            # capture accessibility tree (viewport 0 = top)
3. INTERACT    browser4-cli click <ref>              # use refs from the snapshot
              browser4-cli fill <ref> <value>
              browser4-cli press Enter
4. RE-SNAPSHOT browser4-cli snapshot -v 0 --auto-diff # verify what changed (diff vs previous)
5. EXTRACT     browser4-cli htmlsnapshot get ...      # or eval, or X-SQL (see §4)

Copy-Paste Template

browser4-cli goto "https://example.com"
browser4-cli snapshot -v 0          # read the page; note refs
browser4-cli fill <ref> "<value>"   # interact
browser4-cli press Enter
browser4-cli wait --load networkidle
browser4-cli snapshot -v 0 --auto-diff  # verify what changed
browser4-cli htmlsnapshot get text "<css-selector>" --all

For quick inline viewing without opening a file, add --stdout:

browser4-cli snapshot -v 0 --stdout   # print snapshot to stdout instead of file

2. Key Concepts

Element Refs

After commands that modify browser state, browser4-cli saves an accessibility-tree snapshot — a YAML file showing the page structure:

- generic [ref=e7]:
  - link "News" [ref=e191]:
    - /url: https://example.com/news
  - textbox "Search query" [ref=e35]
  - button "Search" [ref=e25]

Each interactive element has a ref (e5, e12) — the element's Chrome DevTools Protocol backend node ID, prefixed with e (so e12345 refers to backend node 12345). Use them to target elements in click, fill, type, get attr, etc.

Ref Lifecycle

Refs are ephemeral — they become invalid after commands that change the DOM tree structure:

• Safe (refs survive): fill, type, press, check, uncheck, select — these only modify element properties (value, checked, selectedIndex) without adding/removing DOM nodes.
• Unsafe (re-snapshot after): click on navigation links or buttons that trigger page updates, goto, reload, tab switches — these restructure the DOM or load new pages.
• Gray area: click on checkboxes/radio buttons and some dropdown toggles may or may not mutate the DOM. When in doubt, capture a new snapshot after clicking.

In practice, you can fill an entire form from a single snapshot. Only re-snapshot if a ref unexpectedly fails — the CLI will surface a clear error so you know when it's needed.

Output Modes

• Default — human-readable output on stdout with tips on stderr.
• --json — single-line JSON envelope on stdout only. All tips, hints, warnings, and human-readable text are suppressed (clean machine output).
• --quiet / -q — suppress all normal output; only errors appear on stderr.

Sessions

Named sessions isolate browser state (cookies, localStorage, tabs). Use -s <name> to target a named session. goto auto-opens/reconnects — you rarely need to manage sessions manually.

The list command displays a "Next open" column showing what happens when goto or open targets a named session that already exists:

• Reuse — reconnects to the existing browser window (session is active on the backend).
• Refresh — opens a fresh window (session is stale or missing).

3. Command Map

4. Decision Trees

4a. Choosing an Extraction Method

Need to extract data from a page?
├─ Need to interact first (click, fill, scroll)? → snapshot + refs, then extract
├─ Static page, one field? → htmlsnapshot get text "<selector>"
├─ Static page, one field, ALL matches? → htmlsnapshot get all text "<selector>"
├─ Static page, multiple correlated fields (title+price+url per item)?
│  → htmlsnapshot query with X-SQL DOM_LOAD_AND_SELECT
├─ Dynamic/complex JS logic needed? → eval --json (use --stdin or --file on Windows)
├─ Natural language ("find the product price")? → extract (needs LLM key)
└─ High volume, many pages? → crawl or swarm with --sql

4b. Choosing Bulk/Scale Approach

Need to process multiple pages?
├─ Single list page (products on one search results page)?
│  → htmlsnapshot query with DOM_LOAD_AND_SELECT
├─ Multiple known URLs (list in a file)? → crawl --seed-file urls.txt --depth 0 --sql @query.sql
├─ Crawl from a start URL (follow links)? → crawl <url> --out-link-selector "..." --depth N
├─ Need parallel execution (high throughput)? → swarm create → swarm query --seed-file ...
├─ Repeated monitoring (check every hour)? → loop -- eval "..." -i 3600
└─ Just a few URLs in a shell script?
   → for url in ...; do browser4-cli goto "$url"; ... done  (add wait between iterations)

4c. Query Granularity: get vs get all vs query

Warning: Multiple get all calls produce unaligned arrays (different lengths, different order). For correlated fields, use query with DOM_LOAD_AND_SELECT scoped to a parent container.

5. Critical Warnings

Warning: Refs are single-use for navigation and DOM-mutating commands. Re-snapshot after click (on links/buttons), goto, reload, and tab switches. Form interactions (fill, type, press, check, uncheck, select) are safe — you can fill an entire form from a single snapshot. Never store refs across navigations.

Warning: CSS selectors are tied to live websites — they break when sites change their HTML. Always discover selectors with htmlsnapshot inspect or htmlsnapshot summary before extraction. Treat scenario examples as patterns, not copy-paste recipes.

Warning: Shell quoting on Windows — complex JS/SQL with nested quotes causes escaping issues. Prefer --sql @file.sql (read from file), --sql-stdin (piped), --sql-base64 (encoded), or eval --file/eval --stdin/eval --base64 (JS from file or base64). For htmlsnapshot inspect, use @file, --stdin, or --selector-base64. Never inline --sql "..." with double-quoted CSS selectors on Windows. See shell-quoting.md for the full workaround workflow.

Warning: Don't cat snapshot files — they can exceed 256KB. Use viewport pagination (snapshot -v 0), snapshot grep <pattern>, or snapshot --stdout --page 1 instead.

Note: Output pagination defaults — get html, get all html, and grep paginate at 2K lines. get text and get all text are not paginated by default. Use --all to disable pagination, or --page N for subsequent pages.

Note: Interactive mode (snapshot -i) strips generic <div> containers. Many e-commerce product cards use generic divs, not semantic elements. Prefer --viewport 0 or htmlsnapshot for shopping/search pages.

6. Quick Patterns

Interactive Form Fill

browser4-cli goto "https://example.com/login"
browser4-cli snapshot -v 0
browser4-cli fill <email-ref> "user@example.com"
browser4-cli fill <password-ref> "password"
browser4-cli click <submit-ref>
browser4-cli wait --load networkidle
browser4-cli snapshot -v 0 --auto-diff

Find Elements by Text (snapshot grep)

browser4-cli goto "https://example.com"
browser4-cli snapshot -v 0                        # capture snapshot first
browser4-cli snapshot grep "See also"             # search for text in the full AX tree
browser4-cli snapshot grep -i "price|rating"      # case-insensitive regex alternation
browser4-cli snapshot grep -A 3 -B 1 "Checkout"   # show surrounding context lines

Static Data Extraction (Single Field)

browser4-cli goto "https://example.com/product/42"
browser4-cli htmlsnapshot                           # capture static HTML snapshot
browser4-cli htmlsnapshot get text ".product-title"
browser4-cli htmlsnapshot get attr ".product-image" src

Bulk Extraction (X-SQL — Correlated Fields)

# Write query to file (no shell escaping)
cat > query.sql << 'SQLEOF'
SELECT
    DOM_FIRST_TEXT(DOM, '.title') AS title,
    DOM_FIRST_FLOAT(DOM, '.price', 0.0) AS price,
    DOM_FIRST_HREF(DOM, 'a') AS url
FROM DOM_LOAD_AND_SELECT(@url, '.product-card', 1, 48)
WHERE DOM_IS_NOT_NIL(DOM)
ORDER BY DOM_FIRST_FLOAT(DOM, '.price', 999999.0) ASC
SQLEOF

browser4-cli htmlsnapshot query "https://example.com/products" --sql @query.sql

7. Reference Map

Organized by task — follow the link that matches what you're trying to do:

Extract data from pages: htmlsnapshot.md — get, get all, query, grep, summary, inspect, export x-sql.md — X-SQL function reference (DOM, STR, ARRAY namespaces) htmlsnapshot-scenarios.md — 16 end-to-end recipes (e-commerce, Amazon, SEO, CI, jobs, real estate)

Run at scale (multiple pages/URLs): crawl.md — recursive crawling, seed-file bulk fetch, X-SQL extraction swarm.md — parallel scraping across multiple browser contexts loop.md — repeated task execution with persistence/resume

Manage browser state: storage-state.md — cookies, localStorage, sessionStorage, state save/load attach.md — connect to existing Chrome/Edge via CDP

AI-powered extraction: agent.md — extract, summarize, agent run|status|result, LLM provider config

Resilient selectors: power-dom.md — PowerCSS :expr() visual-feature selectors css-selector-bridge.md — bridging snapshot refs to CSS selectors

Configure fetching: load-options-guide.md — cache control, quality requirements, interaction, portal crawling

Troubleshoot: shell-quoting.md — avoid shell-quoting breakage for complex JS/X-SQL on Windows / Git Bash

Installation

Requires Node.js.

npm install -g browser4-cli
browser4-cli install

Windows (PowerShell):

irm https://browser4.oss-cn-beijing.aliyuncs.com/scripts/install-browser4-cli.ps1 | iex
browser4-cli install

Development

See development.md — prerequisites, building from source, and cargo run patterns.