Headless documentation

Browser control,
made useful.

Headless gives an agent a persistent browser through a small, safe CLI. Test a page, capture evidence, and inspect a failure.

01 / First run

Start a session.

Start the host, create a session, then visit the app. The session stays isolated until you close it.

headless start
headless session create qa
headless --session qa visit localhost:3000/designers/dashboard
headless --session qa inspect --interactive --text

02 / A QA workflow

Capture the proof.

Record the path you need, then stop and create a report.

headless --session qa record start --fps 10
headless --session qa click --role button --name Continue
headless --session qa wait --url /next --settled
headless --session qa record stop --output dashboard-flow.mp4
headless --session qa report create --output pr-report.json

03 / Command groups

Use intent, not pixels.

Navigation

visit, back, reload, wait

Move through a real browser session and wait for a URL, page text, or settled state.

Interaction

inspect, click, fill, press, scroll

Use accessibility roles and names instead of mouse coordinates or selectors.

Evidence

screenshot, record, visual compare, report

Create private PNG, MP4, diff, flow, and PR-report artifacts.

Diagnostics

console, network, styles, cookies, storage

Investigate only when something fails; sensitive values remain redacted by default.

04 / Safety by default

Keep the browser local.

Headless uses a private Unix socket, not a public DevTools port. Only HTTP(S) navigation is allowed. Diagnostic secrets are redacted.

Linux: use the supplied Docker runtime or native Chromium. Ubuntu Snap Chromium is not supported for repeated navigation.

macOS: build with Xcode Command Line Tools, then use the visible WKWebView host through the same CLI.