browser-automation-cli 0.1.1

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 without product environment variables

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 scattered across env vars 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.1 ships config, mitm, workflow, batch-scrape, crawl, map, search, and parse

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 and --engine http|browser
  • Firecrawl-parity local surface: batch-scrape, crawl, map, search, parse
  • Capture: console and net with optional global capture flags
  • DevTools depth: eval, emulate, resize, perf, lighthouse, heap
  • 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, schema, completions

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 PATH
  • Optional: ffmpeg for screencast file export
  • Optional: lighthouse binary for lighthouse audits

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
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 --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

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
  • 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

Configuration

  • Prefer CLI flags for one-off agent calls
  • Use config path|init|show|set|get for XDG config.toml
  • Product settings are NOT read from BROWSER_AUTOMATION_CLI_* environment variables
  • OS-level only: RUST_LOG (tracing), NO_COLOR / color via config, PATH for Chrome/ffmpeg/lighthouse
  • 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
  • Nightly docsrs cfg: RUSTDOCFLAGS="--cfg docsrs" timeout 180 cargo +nightly 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, not product env vars
  • 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 PATH, then re-run doctor
  • Config / XDG: run config init then config path to inspect layout; use config set|get for values
  • 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
  • Product env not supported: do not set BROWSER_AUTOMATION_CLI_* for settings; use flags or config
  • 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

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