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

This crate has no Cargo feature flags. 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).

§Safety

No remote telemetry is emitted by this crate
Local tracing stays on stderr only
docs.rs builds pass --cfg docsrs and may enable doc_cfg on nightly
Unix paths may call libc for signal defaults and last-resort process kill

§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

Modules§

browser: Chrome one-shot session: launch, actions, reap. One-shot browser session: launch-only + actions + reap (PR3–PR6).
cli: Clap derive surface and global flags. Clap derive surface for browser-automation-cli (PRD Layer L).
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 (paths leves + Layer A/B browser one-shot).
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. Minimal en/pt-BR message helpers for critical errors.
install: Install path helpers for doctor and packaging checks. Chrome cache discovery for one-shot launches (no download / no apt).
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.
qr_local: One-shot QR encode/decode (no Chrome). One-shot QR encode/decode (no Chrome, pure-Rust path).
robots: robots.txt policy enforcement. robots.txt honor for one-shot invocations (no cross-process cache).
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).
validation: Input and path validation helpers. Input validation helpers for CLI flags and paths.
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§

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 argv and run the one-shot CLI.