browser-automation-cli 0.1.2

One-shot browser automation CLI for AI agents via Chrome CDP. BORN EXECUTE FINALIZE DIE. No daemon, no npm, no telemetry.
Documentation

English | Português Brasileiro

browser-automation-cli

One-shot Chrome CDP automation for AI agents. BORN, EXECUTE, FINALIZE, DIE.

docs.rs crates.io License MSRV Downloads Rust GitHub

What is it

  • Single-process browser automation CLI for AI agents
  • Talks to system Chrome or Chromium through chromiumoxide CDP
  • No daemon, no npm packaging, no remote telemetry
  • Lifecycle is always BORN, EXECUTE, FINALIZE, DIE
  • JSON envelopes on stdout for programmatic agents
  • XDG config and paths via config commands only

The Pain

  • Agent workflows need multi-step browser work without a sticky daemon
  • Node and npm browser stacks add runtime weight and supply-chain surface
  • Session-based tools leave orphan Chrome processes and unclear ownership
  • JSON contracts often drift from real CLI flags and exit codes
  • Product settings outside XDG config make agent prompts fragile

Why browser-automation-cli

  • One process owns one Chrome lifecycle from launch to kill fallback
  • Multi-step work uses run --script NDJSON in the same process
  • Accessibility snapshot refs @eN stay valid only inside that process
  • --json envelopes are stable for programmatic agents
  • Install path is pure Rust via cargo
  • v0.1.2 ships config, mitm, workflow, local scrape/crawl/map/search/parse, print-pdf, monitor, qr, find-paths, LLM extract, and expanded schema discovery

Superpowers

  • Navigation and page lifecycle: goto, back, forward, reload, page
  • Input: press, write, type, keys, hover, drag, fill-form, upload
  • Observation: view, grab, extract, text, attr, scroll, assert
  • Wait: multi --text values resolve as OR (any text wins)
  • Scrape: scrape with --format text|markdown|html|links|metadata|raw-html|screenshot|summary|product|branding and --engine http|browser (browser engine applies formats via outerHTML)
  • Local scrape/crawl/map/search/parse surface: batch-scrape, crawl, map, search (cleans uddg= SERP redirects), parse (PDF/DOCX/xlsx/ods + --redact-pii)
  • Extract LLM: extract --llm --question --schema-json (XDG openrouter_api_key, llm_base_url, llm_model)
  • Capture: console and net with optional global capture flags
  • DevTools depth: eval, emulate, resize, perf, lighthouse (XDG lighthouse_path), heap
  • PDF print: print-pdf one-shot CDP Page.printToPDF
  • Monitor: monitor check --url --baseline [--write-baseline]
  • Utilities (no Chrome): qr encode|decode, find-paths
  • Assert aliases: url_contains / text_contains; attr falls back to DOM properties
  • Scroll aliases in run: dy/dx for delta_y/delta_x
  • Optional categories: memory, extensions, third-party, webmcp
  • Experimental: vision click-at, screencast with ffmpeg export
  • MITM one-shot: mitm start binds 127.0.0.1 only (hudsucker)
  • Workflow DAG: workflow run|resume|status with SQLite journal (resume skips ok)
  • XDG config: config path|init|show|set|get for config.toml
  • Discovery: doctor (incl. XDG browsers_dir), commands (56 names), schema --cmd (goto/eval/type/scroll/assert expanded), completions
  • Fail-fast multi-step: run returns partial data.steps on error envelopes

Quick Start

cargo install --path . --locked
browser-automation-cli --version
browser-automation-cli doctor --offline --quick --json
browser-automation-cli goto https://example.com --json
browser-automation-cli view --json

Installation

  • Local development install:
git clone https://github.com/danilo-aguiar-br/browser-automation-cli
cd browser-automation-cli
cargo install --path . --locked
  • From crates.io after the first publish:
cargo install browser-automation-cli --locked
  • Runtime needs Chrome or Chromium on the shell path (or config set chrome_path)
  • Optional: ffmpeg for screencast file export
  • Optional: lighthouse binary for lighthouse audits (or config set lighthouse_path)

Usage

  • Always pass --json for agent pipelines
  • Keep human diagnostics on stderr with -q when piping
  • Use --timeout for wall-clock process budget in seconds
  • Use run --script for multi-step sessions that need shared @eN refs
  • Prefer CLI flags for one-off agent calls; use config for durable XDG defaults
  • Logging detail: --verbose / --debug / -q, or config set log_level
  • Localize human suggestions with --lang pt-BR or config set lang pt-BR
  • Optional scrape --webhook-url posts the result once to an operator URL (not product telemetry)
browser-automation-cli config set openrouter_api_key sk-or-...
browser-automation-cli --json goto https://example.com
browser-automation-cli --json wait --text Hello --text Welcome --ms 5000
browser-automation-cli --json scrape https://example.com --format markdown --engine http
browser-automation-cli --json scrape https://example.com --format markdown --engine browser
browser-automation-cli --json scrape https://example.com --format markdown --engine http --webhook-url https://example.com/hook
browser-automation-cli --json extract --llm --question "What is the title?" https://example.com
browser-automation-cli --capture-network --json net list --resource-types Document,XHR
browser-automation-cli --category-memory heap summary --path snap.heapsnapshot --json
browser-automation-cli --json mitm start --seconds 30
browser-automation-cli --json workflow resume --manifest workflow.toml
browser-automation-cli --json print-pdf --url https://example.com --path /tmp/browser-automation-cli-artifacts/page.pdf
browser-automation-cli --json monitor check --url https://example.com --baseline /tmp/browser-automation-cli-artifacts/base.txt --write-baseline
browser-automation-cli --json parse ./doc.pdf --redact-pii
browser-automation-cli --json parse ./doc.ods
browser-automation-cli --json qr encode --text "hello" --path /tmp/browser-automation-cli-artifacts/qr.png
browser-automation-cli --json qr decode --path /tmp/browser-automation-cli-artifacts/qr.png
browser-automation-cli --json find-paths /path/to/tree

Commands

  • Discovery: doctor, commands, schema, version, completions
  • Config: config path, config init, config show, config set, config get
  • Navigate: goto, back, forward, reload
  • Snapshot and input: view, press, write, type, keys, wait, hover, drag, fill-form, upload
  • Content: extract, text, scroll, attr, assert, grab
  • Scrape and discovery: scrape, batch-scrape, crawl, map, search, parse
  • PDF and monitor: print-pdf, monitor
  • Utilities: qr, find-paths
  • Tabs and dialogs: page, dialog, cookie
  • Capture: console, net
  • MITM: mitm status|list|get|har|export|domains|apis|init-ca|start
  • Workflow: workflow run|resume|status
  • Advanced: eval, emulate, resize, perf, lighthouse, screencast, heap
  • Categories: extension, devtools3p, webmcp
  • Multi-step: run, exec
  • Inventory: 56 top-level command names (commands --json), including DevTools parity tools plus print-pdf, monitor, qr, find-paths, scrape surface, MITM, workflow, and config

Configuration

  • Prefer CLI flags for one-off agent calls
  • Use config path|init|show|set|get for XDG config.toml
  • Product settings only via flags and config set (XDG)
  • Logging: --verbose / --debug / -q, or XDG config set log_level
  • Color: config set color true|false
  • Chrome binary: shell path or XDG config set chrome_path
  • Lighthouse binary: shell path or XDG config set lighthouse_path
  • Config keys: lang, timeout, artifacts_dir, ignore_robots, namespace, encryption_key, color, log_level, chrome_path, lighthouse_path, openrouter_api_key, llm_base_url, llm_model
  • config init creates XDG layout and default config.toml
  • config path prints resolved config, data, cache, state, and browsers_dir paths
  • CLI flags override values stored in config.toml
  • Doctor reports XDG browsers_dir among readiness checks

Features

  • This crate has no Cargo feature flags
  • Optional categories are process flags, not compile-time features
  • --category-memory enables deep heap tools
  • --category-extensions enables extension tools
  • --category-third-party enables third-party DevTools helpers
  • --category-webmcp enables webmcp tools
  • --experimental-vision enables click-at
  • --experimental-screencast enables screencast export with ffmpeg

Targets

  • Documented for x86_64-unknown-linux-gnu
  • Documented for x86_64-apple-darwin
  • Documented for aarch64-apple-darwin
  • Documented for x86_64-pc-windows-msvc
  • Documented for aarch64-unknown-linux-musl
  • Not supported on wasm32-unknown-unknown (Chrome CDP requires a desktop browser)
  • docs.rs metadata declares these targets explicitly after the 2026-05-01 multi-target change

MSRV

  • Minimum Supported Rust Version is 1.88.0
  • Policy: bump MSRV only in minor or major releases with CHANGELOG note
  • Local docs: timeout 180 cargo doc --no-deps

Integration Patterns

  • Claude Code, Codex, Cursor, and shell agents spawn one process per action
  • Multi-step agent plans must use run --script instead of chaining separate processes
  • Parse stdout with jaq and ignore stderr unless diagnosing failures
  • Persist durable defaults with config set under XDG
  • See INTEGRATIONS.md and docs/AGENTS.md

Performance

  • Cold start is dominated by Chrome launch, not Rust binary size
  • Prefer doctor --offline --quick for install checks without network
  • Reuse multi-step scripts to avoid repeated Chrome launches
  • Prefer scrape --engine http when CDP is not required
  • Use batch-scrape concurrency for parallel HTTP fetches

Memory Requirements

  • Expect Chrome process memory far above the CLI binary itself
  • Heap tools need --category-memory and larger snapshots increase RAM use
  • Screencast export may invoke ffmpeg as an external helper
  • Workflow journals and MITM captures land under XDG state/data paths

Troubleshooting FAQ

  • Chrome not found: install Chromium or Google Chrome, ensure it is on the shell path, or config set chrome_path, then re-run doctor
  • Config / XDG: run config init then config path to inspect layout; use config set|get for values
  • Product settings only via flags and config set (XDG)
  • Exit 69 unavailable: browser binary missing, blocked, or not launchable
  • Exit 124 timeout: raise --timeout or shorten the script
  • Exit 2 usage: re-check flags with browser-automation-cli help <cmd>
  • @eN refs invalid across commands: keep steps inside one run process; refs do not span processes
  • Network empty: pass --capture-network on the same process that navigates
  • Wait multi-text: repeat --text for OR semantics (any listed text unblocks)
  • MITM bind: mitm start listens on 127.0.0.1 only with an ephemeral port
  • Workflow resume: workflow resume skips steps already ok in the journal
  • Scrape browser formats: --engine browser applies --format (markdown/html/links/metadata/raw-html/screenshot/summary/product/branding) via outerHTML
  • Scroll aliases: in run scripts use dy/dx as aliases for delta_y/delta_x
  • Schema discovery: schema --cmd goto|eval|type|scroll|assert exposes expanded tool-ref flags
  • Lang: --lang pt-BR or config set lang pt-BR localizes human suggestions
  • Fail-fast partial steps: failed run error envelopes may include partial data.steps
  • Lighthouse path: config set lighthouse_path /path/to/lighthouse when not on the shell path
  • Search redirects: search cleans uddg= wrappers to destination URLs
  • Parse documents: parse supports PDF/DOCX/xlsx/ods and --redact-pii
  • Extract LLM: requires XDG openrouter_api_key (optional llm_base_url, llm_model)
  • Print PDF: print-pdf --url <url> --path <file> one-shot CDP
  • Monitor baseline: monitor check --url <url> --baseline <file> [--write-baseline]
  • Assert aliases: url_contains / text_contains; attr uses DOM property fallback when HTML attribute is null
  • Inventory size: commands --json lists 56 top-level names (not only the 52 DevTools parity tools)

Exit Codes

  • 0 success
  • 2 usage or clap parse failure
  • 65 data error
  • 66 no input
  • 69 unavailable
  • 70 software, browser, or protocol failure
  • 74 I/O failure
  • 78 config error
  • 124 timeout
  • 130 cancelled by SIGINT
  • 141 broken pipe
  • 255 unexpected fatal path

Documentation Map

Contributing

Security

Changelog

License