[English](llms.txt) | [Português Brasileiro](llms.pt-BR.txt)
# browser-automation-cli
> One-shot Chrome CDP automation CLI for AI agents with no daemon and no remote telemetry.
browser-automation-cli is a single-process Rust CLI that launches system Chrome or Chromium through CDP, executes agent browser actions, then finalizes and exits. Lifecycle: BORN, EXECUTE, FINALIZE, DIE. Product settings use CLI flags and XDG `config` commands only.
## Primary Documentation
- [README](https://github.com/danilo-aguiar-br/browser-automation-cli/blob/main/README.md): product landing, install, commands, flags, config
- [HOW_TO_USE](https://github.com/danilo-aguiar-br/browser-automation-cli/blob/main/docs/HOW_TO_USE.md): first command in 60 seconds
- [AGENTS](https://github.com/danilo-aguiar-br/browser-automation-cli/blob/main/docs/AGENTS.md): agent integration contract
- [COOKBOOK](https://github.com/danilo-aguiar-br/browser-automation-cli/blob/main/docs/COOKBOOK.md): practical recipes
- [INTEGRATIONS](https://github.com/danilo-aguiar-br/browser-automation-cli/blob/main/INTEGRATIONS.md): orchestrator coverage
- [CROSS_PLATFORM](https://github.com/danilo-aguiar-br/browser-automation-cli/blob/main/docs/CROSS_PLATFORM.md): platform matrix
- [MIGRATION](https://github.com/danilo-aguiar-br/browser-automation-cli/blob/main/docs/MIGRATION.md): version migration
- [TESTING](https://github.com/danilo-aguiar-br/browser-automation-cli/blob/main/docs/TESTING.md): test categories
- [schemas](https://github.com/danilo-aguiar-br/browser-automation-cli/blob/main/docs/schemas/README.md): JSON schema index
- [SKILL en](https://github.com/danilo-aguiar-br/browser-automation-cli/blob/main/skills/browser-automation-cli-en/SKILL.md): imperative skill
- [CHANGELOG](https://github.com/danilo-aguiar-br/browser-automation-cli/blob/main/CHANGELOG.md): release history
- [SECURITY](https://github.com/danilo-aguiar-br/browser-automation-cli/blob/main/SECURITY.md): vulnerability reporting
- [llms-full](https://github.com/danilo-aguiar-br/browser-automation-cli/blob/main/llms-full.txt): expanded discovery map
- [llms-full pt-BR](https://github.com/danilo-aguiar-br/browser-automation-cli/blob/main/llms-full.pt-BR.txt): mapa expandido em português
## Command Surface (v0.1.4)
- Discovery: doctor (browsers_dir, lighthouse source, cache_redis), commands, schema (`schema <cmd>` or `schema --cmd`), version, completions
- Inventory: 61 agent names via `commands --json` (includes `select-option`, `pick`); clap top-level lists 59 without those two as standalone subcommands; 53 DevTools e2e tools
- Config XDG: config init|path|show|get|set|list-keys
- Navigate: goto (init-script, handle-before-unload accept|dismiss), back, forward, reload (CDP Page.reload + ignoreCache; init_script removed after nav)
- Local scrape/crawl/map/search/parse: scrape (multi-format --format CSV/repeatable; --engine http|browser; file:// + http → Usage), batch-scrape (--engine http|browser), crawl (--engine http|browser), map, search (uddg clean), parse (PDF/DOCX/xlsx/ods, --redact-pii)
- Interact: view (--allow-empty), press, write, type, keys, wait (multi --text OR; CSS multi-selector OR; run url/url_contains/navigation), hover, drag, fill-form, upload, click-at
- Multi-step only: select-option, pick (run/schema; not standalone clap)
- Observe: extract (--llm/--question/--schema-json), text, scroll (dy/dx aliases in run), attr (property fallback), assert (url_contains/text_contains; console_empty/console_no_match), grab --path
- PDF/monitor/utils: print-pdf (one-shot + run; refuse blank without content), monitor check, qr encode|decode, find-paths (--glob), sheet-write, sg-scan, sg-rewrite
- Tabs: page (incl. tab-id), dialog accept|dismiss (--if-present), cookie
- Capture: console (dump always valid JSON array), net
- MITM: mitm status|list|get|har|export|domains|apis|init-ca|start|capture-url|graphql|ws|block|allow|redact; global --mitm*
- Workflow: workflow run|resume|status
- Advanced: eval, emulate, resize, perf, lighthouse (flag→XDG→PATH; binary_source real|mock), screencast, heap, extension, devtools3p, webmcp
- Multi-step: run (NDJSON or JSON array; --json full steps[]; --json-steps stream; partial data.steps on fail-fast), exec
- Lifecycle: BORN, EXECUTE, FINALIZE (scavenge owned Chromium /tmp orphans), DIE
## Settings Contract
- Product settings: CLI flags + XDG via `config path|init|show|set|get|list-keys` only
- Config keys (16): lang, timeout, artifacts_dir, ignore_robots, namespace, encryption_key, color, log_level, log_to_file, chrome_path, lighthouse_path, openrouter_api_key, llm_base_url, llm_model, cache_backend, cache_redis_url
- Logging: `--verbose`/`--debug`/`-q` or `config set log_level` / `log_to_file`
- Color: `config set color true|false`
- Chrome / Lighthouse: shell path or `config set chrome_path|lighthouse_path` (lighthouse also flag)
- Cache Redis: `config set cache_backend redis` + `cache_redis_url` (`redis://` only; `rediss://` fail-closed)
- MITM globals: `--mitm`, `--mitm-ca-dir`, `--mitm-har`, `--mitm-hosts`, `--mitm-ws`, `--mitm-max-body-bytes`, `--mitm-no-media-bodies`, `--mitm-redact-secrets`
- Lang: `--lang pt-BR` or `config set lang` localizes suggestions