Crate browser_automation_cli 

browser-automation-cli

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

Lifecycle is always NASCE → EXECUTA → FINALIZE → MORRE 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 Camada 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 + Camada 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.

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 → EXECUTA → FINALIZE → EXIT.

native

Native CDP stack (browser, network, snapshot, heap). Native CDP/browser stack used by one-shot MVP path.

robots

robots.txt policy enforcement. robots.txt honor for one-shot invocations (no cross-process cache).

validation

Input and path validation helpers. Input validation helpers for CLI flags and paths.

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.