`, ``, and other non-interactive containers | Simple forms, login pages, sparse pages with clear interactive controls. Reduces noise when you only need clickable/fillable elements | > | `htmlsnapshot` | Static HTML (CSS selectors) | Content extraction (text, attributes), when you need CSS selectors instead of AX refs | > > **`-i` trade-off:** Interactive mode discards structural context. On e-commerce/search pages where product cards use generic `

` wrappers, `-i` may strip the containers you need. For these pages, prefer `--viewport 0` or use `htmlsnapshot` for CSS-based extraction. > > **Example — simple form page:** > ```bash > # Without -i: shows full page tree including header, footer, nav, etc. > browser4-cli snapshot --stdout > # ... 200+ lines ... > > # With -i: shows only form fields and buttons > browser4-cli snapshot -i --stdout > # e5 textbox "Email" /url: /login > # e6 textbox "Password" /url: /login > # e7 button "Sign In" /url: /login > # 12 lines — just the interactive controls > ``` > **Warning:** `htmlsnapshot` captures the **current live DOM** at capture time. Re-capture (run `htmlsnapshot`) after any interaction or navigation to reflect JS updates — a previously captured snapshot is stale only if you do not re-capture. The auto-captured snapshot after `goto` is an earlier capture and does not include later interactions. For one-off live reads without a capture step, use `eval`. The `htmlsnapshot inspect` command reads the stored snapshot — re-capture first to inspect the updated DOM. > **Warning — backend startup fails in sandboxed/restricted environments:** The Browser4 backend (Spring Boot/JVM) writes its log files to a `logs/` directory inside the runtime bundle — `BROWSER4_RUNTIME_DIR` (default `%APPDATA%/browser4` on Windows, `~/.local/share/browser4` on Linux). In sandboxes that only allow writes to the workspace, this write is denied and the server never becomes ready: `goto`/`open` hang until the startup timeout with `FileNotFoundException … Access denied` (or `拒绝访问`) in the startup log. > > **Diagnose:** the failed command prints a startup-log path under `🧾 Details` — look for a `logs\*.log` (or `logs/*.log`) write failure there. > > **Fix:** point the runtime and state at writable locations before the first launch: > ```bash > # PowerShell > $env:BROWSER4_RUNTIME_DIR = "D:\workspace\browser4-runtime" # JRE/JARs + logs (~200 MB) > $env:BROWSER4_CLI_STATE_DIR = "D:\workspace\.browser4-state" # session state > ``` > `BROWSER4_RUNTIME_DIR` relocates the runtime (re-downloads the bundle if not already present); `BROWSER4_CLI_STATE_DIR` already auto-falls back to `./.browser4-cli-state` when `~/.browser4` is unwritable. ## 6. Quick Patterns ### Multi-Session Workflow Named sessions isolate browser state. Create and switch with `-s `, list with `list`, close one with `close`, and clean up with `close-all`: ```bash browser4-cli -s research goto "https://en.wikipedia.org" # opens "research" browser4-cli -s news goto "https://news.ycombinator.com" # opens "news" browser4-cli -s news snapshot -i --stdout # act inside "news" browser4-cli list # show all sessions browser4-cli -s news close # close only "news" browser4-cli close-all # close every session ``` ### Interactive Form Fill ```bash browser4-cli open --headless "https://example.com/login" browser4-cli snapshot -v 0 browser4-cli fill "user@example.com" browser4-cli fill "password" browser4-cli click browser4-cli wait --load networkidle browser4-cli snapshot -v 0 --auto-diff ``` ### Find Elements by Text (snapshot grep) ```bash browser4-cli open --headless "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 ``` ### Mouse Interactions ```bash # Hover — reveal tooltips, expand menus, trigger hover effects browser4-cli hover # hover over an element browser4-cli snapshot grep "tooltip" # verify tooltip appeared # Double-click — trigger dblclick handlers browser4-cli dblclick # double-click an element # Drag-and-drop — move elements between containers browser4-cli drag

# drag source onto target browser4-cli snapshot grep "new position" # verify element was moved ``` ### Dialog Handling Native browser dialogs (`alert()`, `confirm()`, `prompt()`) block the page's main thread. When a dialog appears (e.g., after clicking a button), `click` will time out. Handle the dialog with a separate command: ```bash browser4-cli click "#alertBtn" # triggers alert — click will time out browser4-cli dialog-accept # dismiss the alert ("OK") browser4-cli click "#confirmBtn" # triggers confirm browser4-cli dialog-accept # click "OK" (returns true to page) browser4-cli click "#promptBtn" # triggers prompt browser4-cli dialog-accept "Hello from Browser4" # fill prompt and accept browser4-cli dialog-dismiss # cancel/dismiss any dialog ``` **Note:** `dialog-accept` and `dialog-dismiss` must be run in a separate invocation — they cannot be part of the same command as the triggering `click`. Alternatively, use `click --auto-dismiss-dialogs ` to auto-accept any dialog triggered by the click in a single invocation. ### Verifying Results (verify-after-interaction) Every interaction should be followed by verification. These patterns show how to confirm your actions had the expected effect: ```bash # After click — diff vs previous snapshot browser4-cli click browser4-cli snapshot -v 0 --auto-diff --stdout # shows only what changed # After hover — search for expected content browser4-cli hover browser4-cli snapshot grep "expected-tooltip-text" # After drag — confirm reordering browser4-cli drag browser4-cli snapshot grep "new order|reordered|moved" # After dialog — verify the interaction log browser4-cli click "#alertBtn" && browser4-cli dialog-accept browser4-cli snapshot grep "\[alert\]|\[confirm\]|\[prompt\]" # Generate resilient CSS selectors from snapshot refs browser4-cli generate-locator # produces e.g. "#contactForm > button.primary" browser4-cli get text "#contactForm > button.primary" # verify with the generated selector ``` ### Static Data Extraction (Single Field) ```bash browser4-cli open --headless "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) ```bash # Write query to file (no shell escaping) cat > query.sql << 'SQLEOF' SELECT DOM_FIRST_TEXT(DOM, '.title') AS title, DOM_FIRST_TEXT(DOM, '.price') AS price, DOM_FIRST_ATTR(DOM, 'a[href]', 'href') AS url, DOM_FIRST_ATTR(DOM, 'img:expr(width > 250 && height > 250)', 'src') AS img FROM DOM_LOAD_AND_SELECT(@url, '.product-card') SQLEOF browser4-cli htmlsnapshot query "https://example.com/products" --sql @query.sql ``` ### PowerCSS Modern web pages change their HTML structure frequently, but their **visual layout** stays stable. PowerCSS extends standard CSS selectors with a `:expr()` pseudo-selector that queries elements by their **computed numerical features** — size, position, and content density. This makes selectors resilient to markup changes. #### Numerical Features Browser4 computes these features for every DOM node: | Feature | Description | |---------|-------------| | `top` | Top Y-coordinate of the element (pixels) | | `left` | Left X-coordinate of the element (pixels) | | `width` | Width of the element (pixels) | | `height` | Height of the element (pixels) | | `char` | Number of characters inside the node | | `txt_nd` | Number of descendant text nodes | | `img` | Number of descendant `` elements | | `a` | Number of descendant `` elements | | `sibling` | Number of sibling nodes | | `child` | Number of child nodes | | `dep` | Node depth in the document tree | | `seq` | Node sequence in document order | | `txt_dns` | Text node density | These are usable in any CSS selector via `:expr(...)`, in X-SQL `DOM_*` functions, and in `htmlsnapshot get` / `htmlsnapshot query` commands. --- #### `:expr()` Pseudo-Selector ``` element:expr(expression) ``` Operators in expressions include `+`, `-`, `*`, `/`, `^`, `%`, `==`, `!=`, `<`, `>`, `<=`, `>=`, `&&`, `||`. Use parentheses for grouping. ### Agent Task Lifecycle (Async) Agent tasks run asynchronously — submit a task, poll for completion, then fetch results: ```bash # 1. Submit a natural-language task (returns ) browser4-cli agent run "Find the top 5 products and their prices on this page" # 2. Poll until complete browser4-cli agent status # Look for: "processState": "done" or "isDone": true # 3. Get the result browser4-cli agent result ``` **Note:** `agent run` is asynchronous. Submit with `agent run`, then use `agent status` and `agent result` to track completion and fetch output. **Polling with `isDone`:** The JSON from `agent status` includes `isDone: true` when finished. Shell scripts can parse this: ```bash while true; do done=$(browser4-cli agent status | grep -o '"isDone" *: *true') [ -n "$done" ] && break sleep 2 done browser4-cli agent result ``` **Status codes reference:** | statusCode | processState | Meaning | |-----------|-------------|---------| | (null) | `"created"` | Queued, not yet picked up | | 102 | `"in_progress"` | Agent is actively working | | 200 | `"done"` | Task completed successfully | | 417 | `"done"` | Expectation failed (e.g., missing LLM key) | | 4xx/5xx | `"done"` | Task failed — inspect `message` for details | **CLI status labels:** - `queued` — task submitted, waiting to start - `processing` — agent is working on the task - `completed` — task finished successfully (call `agent result`) - `failed (NNN)` — task failed with HTTP status NNN **Listing tasks:** `browser4-cli agent list` shows all tracked tasks with ID, description, started/finished times, and status. See **[agent.md](references/agent.md)** for full details including LLM key configuration, error recovery, and `extract`/`summarize` synchronous variants. ## 7. Reference Map Organized by task — follow the link that matches what you're trying to do: **Interact with pages (accessibility tree & element refs):** [snapshot.md](references/snapshot.md) — `snapshot`, `snapshot grep`, `-v` viewport paging, `--auto-diff`, `-i` interactive mode, element refs **Extract data from pages:** [htmlsnapshot.md](references/htmlsnapshot.md) — `get`, `get all`, `query`, `grep`, `summary`, `inspect`, `export` [x-sql.md](references/x-sql.md) — X-SQL function reference (DOM, STR, ARRAY namespaces) [x-sql-dom-functions.md](references/x-sql-dom-functions.md), [x-sql-dom-load-select.md](references/x-sql-dom-load-select.md), [x-sql-dom-select-functions.md](references/x-sql-dom-select-functions.md), [x-sql-string-functions.md](references/x-sql-string-functions.md), [x-sql-array-functions.md](references/x-sql-array-functions.md) — X-SQL namespace sub-references [htmlsnapshot-scenarios.md](references/htmlsnapshot-scenarios.md) — end-to-end recipes; focused variants: [advanced](references/htmlsnapshot-scenarios-advanced.md), [amazon](references/htmlsnapshot-scenarios-amazon.md), [audit](references/htmlsnapshot-scenarios-audit.md), [extraction](references/htmlsnapshot-scenarios-extraction.md) **Run at scale (multiple pages/URLs):** [crawl.md](references/crawl.md) — recursive crawling, seed-file bulk fetch, X-SQL extraction [swarm.md](references/swarm.md) — parallel scraping across multiple browser contexts [loop.md](references/loop.md) — repeated task execution with persistence/resume **Manage browser state:** [storage-state.md](references/storage-state.md) — cookies, localStorage, sessionStorage, state save/load [webdb.md](references/webdb.md) — export cached pages, normalize URLs for database lookups [attach.md](references/attach.md) — connect to existing Chrome/Edge via CDP **Manage skills and agent instructions:** [skills.md](references/skills.md) — bundled skill files, backend skill management **AI-powered extraction:** [agent.md](references/agent.md) — `extract`, `summarize`, `agent run|status|result`, LLM provider config **Resilient selectors:** [power-dom.md](references/power-dom.md) — PowerCSS `:expr()` visual-feature selectors [css-selector-bridge.md](references/css-selector-bridge.md) — bridging snapshot refs to CSS selectors **Configure fetching:** [load-options-guide.md](references/load-options-guide.md) — cache control, quality requirements, interaction, portal crawling **Troubleshoot:** [shell-quoting.md](references/shell-quoting.md) — avoid shell-quoting breakage for complex JS/X-SQL on Windows / Git Bash **Developers:** [development.md](references/development.md) — build the CLI from source (Rust, Java 17+) ## Installation **Cross-platform (Node.js):** ```bash npm install -g browser4-cli browser4-cli install ``` **Windows (PowerShell):** ```powershell irm https://browser4.oss-cn-beijing.aliyuncs.com/scripts/install-browser4-cli.ps1 | iex ``` **Linux / macOS (bash):** ```bash curl -fsSL https://browser4.oss-cn-beijing.aliyuncs.com/scripts/install-browser4-cli.sh | bash ``` The bootstrap scripts also install the Browser4 backend (runtime bundle) automatically: `browser4-cli install` on a fresh machine, or `browser4-cli upgrade` when a backend already exists (add `--skip-backend` to install the CLI only).