Crate browser_automation_cli

Expand description

§browser-automation-cli

One-shot Chrome CDP automation library and CLI for AI agents.

Lifecycle is always BORN → EXECUTE → FINALIZE → DIE in a single process. There is no daemon, no npm runtime, and no remote telemetry.

§Overview

Parse argv with clap (cli)
Dispatch one command or a multi-step run --script session
Launch system Chrome/Chromium through chromiumoxide CDP
Always attempt FINALIZE (Browser.close, wait, kill fallback)

§Quick Start

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

Library entry for embedding or tests:

use std::process::ExitCode;

fn main() -> ExitCode {
    browser_automation_cli::run()
}

§Features

Cargo features control optional locale packs only (MVP always includes en + pt-BR):

Feature	Purpose
`i18n-cjk`	Scaffold for zh-Hans / zh-Hant / ja / ko packs
`i18n-rtl`	Scaffold for ar / he (RTL) packs
`i18n-europe`	Scaffold for additional European packs
`i18n-full`	Enables all optional i18n scaffolds
`i18n-pseudo`	Pseudolocalization (dev only)

Rustdoc embeds Mermaid lifecycle diagrams via aquamarine on documented entry points. Optional CLI categories are process flags:

--category-memory — deep heap tools
--category-extensions — extension tools
--category-third-party — third-party DevTools helpers
--category-webmcp — webmcp tools
--experimental-vision — coordinate click
--experimental-screencast — screencast export (needs ffmpeg)

§Targets

Documented and tested for:

x86_64-unknown-linux-gnu
x86_64-apple-darwin
aarch64-apple-darwin
x86_64-pc-windows-msvc
aarch64-unknown-linux-musl

Chrome automation is not supported on wasm32-unknown-unknown.

§MSRV

Minimum Supported Rust Version is 1.88.0 (rust-version in Cargo.toml).

§Graceful shutdown (one-shot)

Detect → signal → await, scoped for a CLI one-shot (not a long-lived server):

Phase	Mechanism
Detect	`browser::shutdown_signal` — SIGINT/SIGTERM (Unix), Ctrl-C/Break (Windows)
Signal	`lifecycle::Lifecycle` `CancellationToken` → exit 130
Await	`OneShotSession::shutdown` (Browser.close + wait ≤5s + kill); residual SIGTERM→grace→SIGKILL
Pipeline	SIGPIPE default + BrokenPipe → exit 141; dual flush before DIE
Force	Second OS signal runs residual `lifecycle::Lifecycle::finalize`

Daemon-only rules (TaskTracker fleets, SIGHUP reload, readiness probes, sd_notify) are N/A by product law.

§Safety

No remote telemetry is emitted by this crate (no OTEL/OTLP/Sentry)
Local tracing: stderr by default; optional rotated JSON under XDG state (log_to_file); see telemetry
Unix paths may call libc for signal defaults and last-resort process kill
Windows paths may use Job Objects (win_job) for residual-zero process trees

§docs.rs / rustdoc feature gates (nightly)

docs.rs builds this crate with --cfg docsrs (see [package.metadata.docs.rs])
Under docsrs, the crate root enables #![feature(doc_cfg)] so #[doc(cfg(...))] and #[cfg_attr(docsrs, doc(cfg(...)))] render platform and feature badges on multi-target docs
doc_auto_cfg is not used: as of the October 2025 rustdoc consolidation, automatic cfg labels live under doc_cfg only; enabling the removed doc_auto_cfg feature gate risks nightly docs.rs failures
Stable cargo doc does not enable docsrs; platform items still compile via normal #[cfg(unix)] / #[cfg(windows)] without the experimental feature

§Error handling

Public errors use error::CliError with sysexits-style exit codes. JSON agents should parse the envelope from envelope.

§Examples

use browser_automation_cli::error::{CliError, ErrorKind};
use browser_automation_cli::exit_code_for;

let err = CliError::new(ErrorKind::Unavailable, "chrome not found");
assert_eq!(exit_code_for(&err), 69);

§See also

Crate README and docs/HOW_TO_USE.md
docs/schemas/ for JSON contracts
skill/browser-automation-cli-en/SKILL.md for agent skill surface
Local validation: scripts/docs-check.sh (HTML + optional rustdoc JSON; no CI/GHA)

Modules§

browser: Chrome one-shot session: launch, actions, reap. One-shot browser session: launch-only + actions + reap (PR3–PR6).
cache: HTTP/parse cache under XDG (one-shot L1 + SQLite L2). HTTP / parse cache under XDG (PRD 5AF / GAP-011 / GAP-023).
cli: Clap derive surface and global flags. Clap derive surface for browser-automation-cli (PRD Layer L).
clock: Injectable wall clock for deterministic tests. Injectable clock for deterministic tests (rules: dependency inversion).
color: ANSI color helpers for human stderr diagnostics. Color output utilities.
commands_prd: PRD command dispatch (meta paths and browser one-shot). PRD command dispatch (path-level + Layer A/B browser one-shot).
concurrency: Bounded parallelism budget (--max-concurrency, Semaphore, Rayon, join_bounded). Bounded parallelism and concurrency for the one-shot CLI.
config: Config surface (re-export of XDG; layout name for clap rules). Configuration loading surface (rules layout: src/config.rs).
constants: Shared constants (schema version, product name). Named constants for browser-automation-cli (anti-hardcode).
doctor: Local install diagnostics (doctor). Local diagnostics for one-shot installs (no multi-process daemon).
envelope: JSON success/error envelopes for agents. JSON envelope helpers (schema_version = 1).
error: Typed CLI errors and exit codes. Typed CLI errors with sysexits-style exit codes.
find_paths: One-shot filesystem path discovery (find-paths). One-shot filesystem path discovery (find-paths, fd-like UX; no Chrome).
i18n: Locale messaging helpers. Automatic multi-language UI for human-facing suggestions.
install: Install path helpers for doctor and packaging checks. Chrome cache discovery for one-shot launches (no download / no apt).
json_util: Shared JSON / NDJSON helpers (BOM strip, size ceilings, compact encode). Shared JSON / NDJSON helpers (RFC 8259 + I-JSON-oriented CLI contracts).
lifecycle: Cooperative cancel and FINALIZE ledger. One-shot lifecycle: INIT → EXECUTE → FINALIZE → EXIT.
llm_local: Optional one-shot LLM HTTP extract (XDG key only). One-shot optional LLM HTTP extract (XDG key only; no product env vars).
mitm_local: Local MITM capture, CA, and HAR export (one-shot). One-shot local MITM capture helpers (PRD §5E).
native: Native CDP stack (browser, network, snapshot, heap). Native CDP/browser stack used by one-shot MVP path.
output: Canonical stdout/stderr writers (BrokenPipe → 141, explicit flush). Canonical stdout/stderr writers for the agent contract.
platform: Cross-platform host helpers (PATH, console UTF-8/VT, sandbox, WSL/container). Cross-platform host helpers (PATH lookup, console, sandbox, environment).
qr_local: One-shot QR encode/decode (no Chrome). One-shot QR encode/decode (no Chrome, pure-Rust path).
residual: Owned residual path discovery (CLI marker + chromium tmp). Owned residual path discovery for one-shot Chrome (GAP-017 / GAP-020 / RES-01…12).
retry: Named retry policies with backoff and jitter. Named retry policy with budget, backoff, and jitter (rules_rust_retry_com_backoff / GAP-013).
robots: robots.txt policy enforcement. robots.txt honor for one-shot invocations (no cross-process cache).
runtime_util: Tokio runtime builders (budgeted multi-thread workers for CDP + HTTP fan-out). Tokio runtime builders tuned for one-shot CLI with bounded parallelism.
scrape_local: Local scrape/crawl/map/search/parse (HTTP + files; one-shot). Local scrape/crawl/map/search/parse (one-shot HTTP and file extract; no SaaS).
sg_local: Structural lint scan/rewrite one-shot (§5AC). One-shot structural lint / rewrite for product-forbidden patterns (§5AC / GAP-A011).
sheet_local: XLSX write-only path via rust_xlsxwriter (§5Z). One-shot XLSX write via rust_xlsxwriter (§5Z / GAP-A011).
telemetry: Local tracing init (stderr + optional XDG rotated JSON; no remote export). Local-only tracing init for the one-shot CLI (rules_rust_logs_com_tracing_e_rotacao).
validation: Input and path validation helpers. Input validation helpers for CLI flags and paths.
win_job: Windows Job Object helpers (stubs on non-Windows). Windows Job Object helpers for residual-zero Chrome reap (PRD 5W / GAP-009).
workflow_local: Workflow journal DAG (petgraph + SQLite), one-shot run/resume. One-shot workflow journal (PRD §5H): DAG + SQLite, no live Page/@eN across processes.
xdg: XDG Base Directory paths and config file (no .env at runtime). XDG Base Directory layout for browser-automation-cli (no .env at runtime).

Functions§

build_identity: Build identity for version and packaging diagnostics.
command_factory_debug_assert: Run clap debug_assert on the command tree (tests and diagnostics).
exit_code_for: Map a CliError to its process exit code without parsing argv.
run: Parse process argv and run the one-shot CLI.
run_from_args: Parse the given argv (including program name as first element) and run.