Repository navigation
Releases
Releases · danilo-aguiar-br/browser-automation-cli
v0.2.0
Added
scrapeenvelopes on both engines carryuser_agent_major_source, always present.projectedmeans the User-Agent is overridden and its major comes from the identity crate's table;host_binarymeans the major came from this host's Chrome, through the launch reply toBrowser.getVersion,--versionindoctor, or the major a seeded earlier launch stored;host_unprobedmeans the crate table stood in because no major was known and nothing was probed. It isnullunder--no-stealth, and on the browser engine also before a launchdoctor --fingerprintgains the mismatchua_data_brands_vs_user_agent, which compares only the Chrome major innavigator.userAgentData.brandswith the major in the User-Agent, and the live probe publishesua_data_brands
Changed
- The stealth patch no longer emulates
navigator.userAgentDatain any mode. Headed on the host profile, where no User-Agent override applies, the page exposes Chrome's native object, which agrees with the realsec-ch-ua, and the page User-Agent is the installed Chrome's. Headless launches and profiles that claim another platform get the object Chrome builds from theuserAgentMetadatathe override sends. As in a real Chrome, the object exists only in a secure context and isnullonabout:blank doctor --fingerprintreportsplanned_version_sourceasnullonly when the plan overrides the User-Agent. With stealth and no override it ischrome_binarywhen the binary was probed, as it already was under--no-stealth, andcrate_tablewhen the probe failed. With stealthplanned.ua_data_platformis alwaysnull, because theabout:blankprobe page exposes nouserAgentData. The documents that saidnullunder default stealth were wrong on Linux with Xvfb, whereautoresolves to headed- The HTTP engine shares the Chrome major of
user-agentandsec-ch-uawith the page, not the brand list. Without a seed the major comes from the crate table and Chrome is never looked for. With a seed it is the major the last launch stored, so the first run after a Chrome upgrade that sends HTTP before launching the browser in the same process can announce the old major. Known limit: the HTTPsec-ch-uais always the fixed list Chromium, Google Chrome and a GREASE brand, which may not match the native list of a browser without an override, such as a Chromium with no Google Chrome brand;user_agent_major_sourcedescribes only where the major came from stealth_seed_fieldsno longer listschrome.build, and the--stealth-seedhelp no longer says the seed varies the Chrome build. With a User-Agent override the build is the full version the identity crate associates with the major, and without one it is the installed Chrome's own- The host major is stored in
state_dir/stealth/host-major-<hash>.txt, read and written only with stealth on and--stealth-seedor XDGstealth_seed. Without a seed nothing goes to disk, and under--no-stealthnever, so a run without a seed still leaves no residue - The seeded script cache key is
{profile}-{major}forhost_binaryand{profile}-nativeforhost_unprobedandprojected. Scripts stored by an earlier version, which still emulateduserAgentData, are redrawn once - The warning
Chrome cache directory exists but no Chrome binary found insideleft the default stderr and appears only as a WARN line under--debug
Fixed
- The User-Agent override sent incomplete
userAgentMetadata, so Chrome leaked the real binary's version insec-ch-ua-full-version,sec-ch-ua-full-version-listandgetHighEntropyValues, while the JavaScript emulation published a GREASE brand and randomly drawn builds that differed from the headers. The override now sendsbrandsandfullVersionListfrom the same source, afullVersionthe identity crate associates with the User-Agent major,platformVersion(empty on Linux,10.0on Windows),bitness64andwow64false. JavaScript,getHighEntropyValuesand the headerssec-ch-ua,sec-ch-ua-full-version,sec-ch-ua-full-version-list,sec-ch-ua-platform-version,sec-ch-ua-bitnessandsec-ch-ua-wow64now tell the same version - The legacy
chrome_legacy_oxide_launchpath records the major of the Chrome it launched too. It has no pipe bridge to read the readiness reply from, so its patch script was built from the crate table while the page showed the host User-Agent v019_identity_gatepins--headlessor--headed, so its assertions no longer depend on whatautoresolves to on the host- The screen test compares against the envelope, where
screen_source: flooris intentional - The round-trip test
rqrr_decodes_what_qrcode_encodesguards therqrrAPI thatqr decodedepends on, because nothing else in the suite decoded a QR across the dependency bumps - A headed Chrome launched into the private Xvfb display no longer opens a window on the operator's Wayland desktop. Measured on Fedora 44 under Wayland with Chromium 152: the renderers ran with
--ozone-platform=waylandalthough the child receivedDISPLAYfor the Xvfb server, so the window was drawn on the real compositor while Xvfb drew nothing. The cause is notWAYLAND_DISPLAY: Chromium'sSetOzonePlatformForLinuxIfNeededpicks Wayland fromXDG_SESSION_TYPE, andInspectWaylandDisplayfinds$XDG_RUNTIME_DIR/wayland-0when the variable is missing, which a launch with the variable removed and no switch reproduced.build_chrome_argspins--ozone-platform=x11, which that function honours before any detection; a platform switch already in the argument list is kept, but no flag or XDG key fills that list, so--no-xvfbis the way to keep the host display.SpawnRequestgainsenv_removeand the spawn still dropsWAYLAND_DISPLAY, so wrappers such as Fedora's/etc/chromium/chromium.confdo not add Wayland-only GPU switches - Two concurrent headed launches no longer share one private display. Measured with four simultaneous runs: two lost the race for
:99and drew into another run's server, and the loser's teardown deleted the winner's lock and socket. Readiness now requires the lock file to name the pid of the server this launch started, a server that exits is retried on the next free number, and the lock and socket are removed only when this launch owns them - The private Xvfb is stopped with
SIGTERMand a grace period beforeSIGKILL, so the server removes its own lock and socket.SIGKILLleft both behind, which is what made the manual cleanup above necessary - A display number whose lock names a dead process is reused. A CLI killed with
SIGKILLkills its Xvfb the same way, which leaves the lock and socket behind, and the search used to skip that number for good; the X server started on it replaces the stale lock, and readiness still requires the lock to name the pid this launch spawned - The private Xvfb writes to the null device instead of a pipe nobody read. It was measured writing 2340 bytes over two sessions, and a full pipe blocks the writer
- The
--ozone-platform=x11pin follows whether the private display actually started, not whether it was requested. A missing Xvfb used to force X11 onto a launch with no X server, which failed withMissing X server or $DISPLAY; the legacychromiumoxidelaunch path, which never starts Xvfb, no longer receives the pin either display_backendreports the display that was used. With every display number taken it still saidxvfbwhile Chrome ran on the host display- The extension launch path starts the private display too. It passed
--headlessto the display decision and skipped Xvfb on every headed extension run - A launch cancelled between the fork and the first readiness wait no longer leaves a live Chrome without an owner until the process exits. The owner that kills on drop is now built inside the blocking spawn task
- A failed Chrome launch kills Chrome's whole process group, not only its pid. The lifecycle ledger learns the group only after a successful launch, so FINALIZE signalled nothing, and a descendant that stayed in the group was measured outliving the CLI with the DevTools and output pipes still open. The teardown of a failed launch also runs on a blocking thread now, so
--timeoutends the command with exit 124 instead of 69 while it runs - The X11 pin test no longer changes the process-wide browser mode, which races with every other test reading it
doctor'svirtual_displaymessage saidautoresolves to headless on a host where its ownbrowser_mode_auto_resolvesfield said headed. The sentence now names the resolved value, and sixteen documents carrying the same stale claim now state the Linux-with-Xvfb exception
Security
- The private Xvfb requires a
MIT-MAGIC-COOKIE-1. It ran with no access control, and a client with no cookie was measured connecting to it; the cookie now lives in a mode 0600 file removed at teardown, passed to the server with-authand to Chrome throughXAUTHORITY. The file name carries the creator's pid, so the next launch removes a cookie left by a CLI killed withSIGKILL - BREAKING: a self-spawned Chrome no longer opens a DevTools TCP port. Any local process could read
/json/versionon the loopback port and drive the browser for as long as the command lived. Chrome now runs with--remote-debugging-pipe, and a loopback WebSocket bridge that relays exactly one valid client, on a path holding the 122 random bits of a v4 UUID, between the pipe andchromiumoxide. The bridge caps each message at 256 MiB and waits at most two seconds for its pipe threads at teardown, because a descendant of Chrome that inherits the pipe was measured holding a--timeout 10command for 40 seconds. The stdout and stderr drainers of Chrome and Lightpanda got the same two-second bound: a descendant holding the output, as thecathelpers of Fedora'schromium-browser.shdo, held the same command for 30 seconds. The Lightpanda engine...
v0.1.9
[0.1.9] - 2026-09-04
Added
tests/schema_input_drift_gate.rs: everydocs/schemas/<cmd>.schema.jsonmust describe the same INPUT surfaceschema --cmdpublishes. The capability existed asscripts/generate_command_schemas.sh --check, whichcargo testnever runs, so the files went stale in silence:config.schema.jsonlisted neitheruser_data_dirnorinput_typo_permille, both of which had reached the binary,config list-keysanddocs/CONFIGURATION.md. The gate comparespropertiesandrequiredonly — a whole-document comparison makes all 72 files diverge on envelope alone, which measures the instrument rather than the artifact. Live gate count 88 to 89.tests/screen_source_doc_gate.rs: every tokenscreen_sourcecan emit must be named indocs/COOKBOOK.mdanddocs/COOKBOOK.pt-BR.md. The gate readsScreenSource::ALL, so it cannot fall behind the enum the way a copied list would.screen_sourceis an OUTPUT contract and the schemas describe only the--screenINPUT, so until now the token set had no owner in any live document: the sole enumeration lived ingaps.md, whichdoc_binary_numeral_gateexcludes on purpose as a dated audit log. Live gate count 87 to 88.screen_sourceand its five tokens documented in both cookbooks, including whatfloormeans for a caller who reads only the number.input_typo_permilleXDG key: chance in a thousand that a character is typed wrong, erased withBackspaceand retyped, so the field still ends up holding exactly the requested text.0by default, and the only humanisation key that is: every other one disperses TIMING, which a page cannot read as a different value, while this one changes the CHARACTER STREAM aninputlistener sees. The wrong key is always a physical neighbour on the QWERTY row. Live key count 216 to 217.- Per-bigram typing speed in
src/native/interaction/kinematics/qwerty.rs: the gap between two characters now scales with the QWERTY finger pair, soth(alternating hands) is faster thanqz(one finger, two rows). Derived from the layout rather than copied from a digraph table, because a table measures one corpus while the finger pair is the cause behind it. No knob: there is no value an operator could sensibly choose differently. tests/csp_init_script_gate.rs: proves that a page publishingContent-Security-Policy: script-src 'none'does not reach the stealth payload. It exists because the row it backs cites no line of this tree — it rests on a behaviour of Chrome, and a claim with no code behind it has nothing that can fail when it stops being true.user_data_dirXDG key: a persistent Chrome profile, opt-in and unset by default. Unset is what keeps residual-zero true for every caller who did not ask; setting it deliberately trades that invariant away, because a detector that attests SESSION cannot be satisfied by one-shot processes that each present as a different machine. Created with mode 0700 on Unix.--profileon argv still wins. Live key count 215 to 216.runtime_enable_usedin the policy witness, so the claim that the default launch no longer enables theRuntimedomain is checkable from outside rather than taken on the word of a comment.serp_endpointin thesearchenvelope, reportingknownorunknownfor the configuredsearch_base_url. Published on the failure envelope too, underdataalongsidesearch_base_url, so an unknown endpoint is distinguishable from an empty web.tests/doc_binary_numeral_gate.rs: every configuration-key count published in live prose is compared againstconfig list-keys.CHANGELOGandgaps.mdare excluded because a dated measurement is history. It found four sites indocs/MIGRATION*still claiming 206 that a manual sweep for the previous figure could not have found.tests/bilingual_flag_parity_gate.rs: every translated document pair must enumerate the same long flags. It found twenty-seven asymmetries on its first run, two of them with the ENGLISH side deficient, a direction no earlier audit had supposed possible.- The error envelope carries
retryable. It already told an agentkind,message,exit_codeandsuggestion, and left the one decision an agent actually has to make — try again or route around — to be guessed from prose. Derived from the message rather than the kind, because the kind is too coarse:unavailablecovers both "chrome is not installed", which no amount of retrying fixes, and "connection reset", which is exactly what a retry is for. Emitted unconditionally,falseincluded, for the reasonscrape_local::disclosurealready states about its own fields — a key that appears only when true is indistinguishable from a key that was never implemented scrapedisclosestransport_fingerprint, on BOTH engines.tls_impersonation: falsesaid the JA3 had not been forged and left open what it actually was, so a caller correlating a block against a fingerprint database had to guess the library. Thehttpengine reportsrustlsand thebrowserenginechrome-boringssl; emitting it on only one would have created a key that cannot be filtered on, which is the defect that module exists to preventscripts/supply-chain-check.shrunscargo auditand thencargo deny check. Twenty-nine verifiers measured this repository and not one read a dependency advisory, so that debt was invisible by construction and surfaced only when a human thought to ask. The two are not redundant and the order is not arbitrary:cargo auditasks about the LOCKFILE andcargo denyabout the RESOLVED GRAPH, which is why the second one stayed silent aboutpasteandproc-macro-error2— both are written inCargo.lockand neither is in the graph. The difference between the two lists is therefore a stale-lockfile detector for free. The verdict comes from the exit code and never from parsing, so a transitive advisory warns and only a vulnerability fails: a gate that fails for a debt the operator cannot pay is a gate the first person to hit it switches off, and switched off it no longer sees the vulnerability either--headlessand--browser-mode <auto|headless|headed>join--headed, so every window mode is reachable from argv. Until now headless was obtainable only by asking for nothing, which made "I require headless" and "I said nothing" the same command line — and a requirement that cannot be expressed cannot be verified. Callers worked around it by strippingDISPLAYfrom the environment, a defence by absence that protects only the paths someone remembered to strip. The three spellings are mutually exclusive and the parser refuses more than one, so the conflict costs exit 2 and never a surprising launch- The resolved window mode now records WHICH precedence step chose it.
PolicySourcemoved out ofstealth.rs, where it had been describing--stealth-profilealone, into a shared module: the three steps it names are the same three every policy here resolves through, and keeping it private to one policy is what letstealth_profilebe able to state its provenance whilebrowser_mode— the decision with a security consequence — could not docs/COOKBOOK.mdhas a recipe forsitemapandfeed, in both languages. Both verbs were already in the file's flat inventory and neither had an executable line, which is the same defect one layer up from the one they were added to close: a name in a list that no prose explains. The gap was invisible to a keyword sweep because--use-sitemap, a flag ofmap, matchessitemapREADMEandCONTRIBUTINGinstall and build withoutcd, in both languages.cargo install --path <dir>andcargo build --manifest-path <dir>/Cargo.tomldo the same work while leaving the reader's working directory where it was, which matters for a copy-pasted block whose next line the reader did not readCONTRIBUTING.pt-BR.mdnamesselect-option,pick,localeandmanin the inventory-tip line, which only the English twin listed.scripts/audit_bilingual_docs.shnever saw it: the auditor compares CLI INVOCATIONS inside fenced blocks, and an inventory sentence in prose carries nonesrc/commands/dispatch/scrape.rsis dispatch for the fetch-and-render verbs only;sitemapandfeedmoved tosrc/commands/dispatch/discovery.rs. The two pushed the file past the 300-line production ceilingscripts/filesize-check.shenforces, and the seam taken is the one that already existed — discovery by declared document against fetch-and-render — rather than an arithmetic cut at line 300clippy.tomlandrustfmt.tomlexist, and both are documented as decisions rather than defaults.clippy.tomldeliberately does NOT setmsrv, because Clippy readspackage.rust-versionsince 1.74 and declaring it twice invites drift, and deliberately does not raisetoo-many-arguments-threshold: the 42 local#[allow]attributes sit on functions carrying 7 to 33 parameters, so a threshold that retired them would have to be 33, which switches the lint off for the whole crate including every function written from here on.rustfmt.tomlsets every value to the current default, so it reformats nothing; what it buys is pinningstyle_edition, which otherwise follows the crate edition and would silently reformat the tree in the same commit that bumps to edition 2024deny.tomlruns at maximum coverage withunmaintained = "all", which widens the scan from the registry's own crates to every source.RUSTSEC-2025-0057is the one ignore, with the reason recorded inline:fxhashis unmaintained with no safe upgrade, arrives throughscraper 0.22thenselectors 0.26, and nothing in this crate selects itretry_blockingandretry_asyncclampmax_attemptswith.max(1). A configured zero meant a loop that never ran and a function that had to return an error it could not construct, becauseEis opaque and there is no error value to invent — a panic reachable purely from con...
v0.1.4
browser-automation-cli 0.1.4
Hard-close GAP-001…025. Agent-first surface with 61 command names via commands --json.
Install
cargo install browser-automation-cli --version 0.1.4Highlights
run --json-steps— NDJSON one line per step for agent observabilitywaitmulti-selector OR +url/url_contains/navigationselect-option/pickmulti-step cmds (HIG badge/popover /role=option)- Assert kinds
console_empty/console_no_match schema <cmd>positional; MITMcapture-url; scrape multi-formatbatch/crawl--engine browser- Clap usage JSON envelope when
--jsonis on argv view --allow-empty;print-pdfblank refuse; dialog--if-present- BeforeUnload accept|dismiss on
goto/reload
Docs
Public bilingual docs + EN/PT skills synchronized to the 61-command surface.
See CHANGELOG.md for the full list.
v0.1.3
browser-automation-cli v0.1.3
One-shot browser automation CLI for AI agents (Chrome CDP). 59 top-level commands.
Install
cargo install browser-automation-cli --locked --version 0.1.3Highlights
- Hard-close GAP-A001–A012: residual FINALIZE,
run --scriptNDJSON or JSON array,sheet-write,sg-scan/sg-rewrite,find-paths --glob, Redisrediss://fail-closed - Redis live RESP mock + optional
redis-server; Lighthouse envelopebinary_source(flag → XDG → PATH) - XDG 16 keys +
config list-keys; liveschema --cmd configincludeslist-keysand cache keys - Docs, bilingual skills, and public root synchronized to the 59-command surface
- Dependency bumps:
rustls-webpki,quinn-proto,crossbeam-epoch
Links
v0.1.2 — agent surface hard-close
browser-automation-cli 0.1.2
Hard-close of the agent-first surface after gaps.md audit.
Highlights
- 56 top-level commands (print-pdf, monitor, qr, find-paths + prior surface)
- Scrape multi-format works on engine
browserandhttp(markdown/html/links/metadata/raw-html/screenshot) - Scroll accepts
dy/dxaliases inrunNDJSON - goto schema includes init_script, handle_before_unload, navigation_timeout_ms
- i18n suggestions honor
--lang/ XDGlang(pt-BR) - run fail-fast error envelopes include partial
data.steps - XDG keys (13): lang, timeout, artifacts_dir, ignore_robots, namespace, encryption_key, color, log_level, chrome_path, lighthouse_path, openrouter_api_key, llm_base_url, llm_model
- extract --llm with optional
--schema-json(XDG LLM keys) - parse PDF/DOCX/XLSX/ODS +
--redact-pii - Skills EN/PT, schemas, bilingual docs, llms*.txt updated
Install
cargo install browser-automation-cli --locked --version 0.1.2Verify
browser-automation-cli version --json
browser-automation-cli commands --json
browser-automation-cli doctor --offline --quick --jsonbrowser-automation-cli 0.1.1
browser-automation-cli 0.1.1
One-shot Chrome CDP automation for AI agents. BORN, EXECUTE, FINALIZE, DIE.
Highlights
- XDG config (
config path|init|show|set|get) without product env vars - Local MITM on
127.0.0.1(hudsucker): init-ca, start, list, get, har, export - Workflow journal DAG: run / resume / status (resume skips ok steps)
- Firecrawl-parity local: scrape formats/engines, batch-scrape, crawl, map, search, parse
- wait multi
--textOR semantics - Full 52-command schemas + EN/PT skills with executable formulas
- Public docs aligned; no CI / no GitHub Actions
Install
cargo install browser-automation-cli --lockedVerify
browser-automation-cli doctor --offline --quick --json
browser-automation-cli version --jsonSee CHANGELOG.md.