CLI workflows
These recipes build on the CLI tutorial. Start the local example server, then work in a scratch directory. Save the named files before running their commands.
1. Fill a form with actions
Section titled “1. Fill a form with actions”Save this ordered action list as actions.json:
[ {"action":"fill", "selector":"#name", "text":"Ada"}, {"action":"click", "selector":"button[type=submit]"}, {"action":"wait-selector", "selector":"#result"}]brimp fetch http://127.0.0.1:8765/ --actions actions.json \ --eval 'document.querySelector("#result").textContent'Expect "Hello, Ada". Actions target DOM nodes, without visibility checks or
coordinate hit-testing. An element’s presence does not imply it is visible.
Other actions are focus, hover, tap, type, press, drag, upload,
evaluate, wait, wait-network-idle and advance-time. Upload paths are
relative to the action file. Unknown operations or fields reject the input.
| Action | Fields in addition to action |
|---|---|
click, focus, hover, tap, wait-selector |
selector |
fill, type |
selector, text |
press |
selector, key, optional modifiers bitmask: Alt=1, Control=2, Meta=4, Shift=8 |
drag |
source, destination selectors |
upload |
selector, files |
evaluate |
source JavaScript |
wait |
seconds |
wait-network-idle |
milliseconds, default 500 |
advance-time |
milliseconds |
2. Supply a network fixture
Section titled “2. Supply a network fixture”Save routes.json:
[ { "pattern":"http://127.0.0.1:8765/api/*", "stage":"request", "decision":{ "action":"fulfill", "status":200, "headers":[["Content-Type","application/json"]], "body":"{\"source\":\"route\"}" } }]brimp fetch http://127.0.0.1:8765/ --routes routes.json \ --eval 'fetch("/api/status").then(response => response.json())'Expect {"source":"route"}. Rules are glob patterns, and the last matching
rule at a stage wins. A file response uses "file":"fixture.json" in place of
body; the path is relative to the routes file.
| Decision | Behavior |
|---|---|
block |
Abort; optional message |
fulfill |
Supply status, header pairs, and a text body or file |
continue |
Optional URL, method, headers, body and status overrides |
The stage defaults to request; response is also supported. Response-stage
continuation cannot change URL/method, and request-stage continuation cannot
change status. Supplied headers replace the routed header list. Response
interception buffers at most 32 MiB. Use --auth USER:PASSWORD for authentication
challenges; credentials are scoped to the initial target origin.
3. Install a bundled or custom plugin
Section titled “3. Install a bundled or custom plugin”Discover capabilities:
brimp plugins listbrimp plugins show canvasBrowser storage is core. Supply a URL to use origin-partitioned storage:
brimp run - --url http://127.0.0.1:8765 <<'JS'localStorage.setItem('theme', 'dark'); localStorage.getItem('theme')JSExpect "dark". Origin-partitioned browser storage survives navigation within the
session. Without an origin, storage is isolated to the current realm. CLI
host-storage is a separate extension for origin-partitioned atomic batches.
For a custom installer, save custom.js:
({global, options}) => { global.answer = options.answer; return () => { delete global.answer; };}brimp run - --plugin ./custom.js --plugin-options 'custom={"answer":42}' <<'JS'answerJSExpect 42. File plugin names come from the file stem. Repeat --plugin to
install in argument order; duplicate names reject. Installers run before page
scripts, may return Promises, and may provide cleanup. They receive
{global, host, options, profile, canvas}; profile registers configurable values
and capture recipes, and canvas registers context backends. Custom Python/Node
host handlers require the bindings.
Browser subsystem plugins, including canvas, graphics and audio, are enabled by
default. Supplying --plugin replaces that set; --no-plugins selects core only.
Canvas and graphics can be installed in either order and retain their documented
limits. Crypto is core.
4. Stream bytes to a file
Section titled “4. Stream bytes to a file”brimp fetch http://127.0.0.1:8765/download --stream --format raw \ --output streamed.bin --response-info response.jsonExpect a 53,248-byte file. Streaming neither navigates nor runs page scripts; it cannot accompany init/preparation scripts, actions, clock advancement or page waits. Metadata contains status, URL and headers. The result file is published only after the body finishes; stdout can contain partial data on failure.
5. Trace a job and control its clock
Section titled “5. Trace a job and control its clock”brimp run - --clock logical --epoch-ms 1700000000000 \ --advance-time 50ms --trace trace.jsonl --events events.jsonl \ --eval 'times' <<'JS'globalThis.times = [];setTimeout(() => times.push(Date.now()), 50);document.body.textContent = 'Clock example';nullJSExpect [1700000000050]. Inspect trace.jsonl for API diagnostics and
events.jsonl for page/network events. Use --trace-include PREFIX to filter
APIs and --trace-stack for stacks. Logs can include headers or request bodies.
Logical time controls realm clocks and timers. Network I/O, timeout and
cancellation deadlines still use real time. Pair logical time with routes when
you need controlled network responses. --max-tasks bounds advancement; awaited
timer Promises may auto-advance logical time.
Understand execution order
Section titled “Understand execution order”- Install plugins and register init scripts, routes and event observers.
- Navigate when a URL is supplied; init scripts precede document scripts.
- Apply
--waitand--wait-selector. - Run repeatable
--scriptpreparation files. - Run the main
runscript, then the action sequence. - Advance time, then produce the final evaluation or extracted output.
--wait load is the default and tracks document scripts, not image decoding.
domcontentloaded can return while async scripts remain outstanding.
networkidle uses a 500 ms quiet interval by default. A numeric wait is seconds.
The shared command timeout defaults to 30 seconds; Ctrl-C cancels active work.
Blocking OS file/terminal I/O is not a hard-real-time operation.
Output and failures
Section titled “Output and failures”htmlserializes the live DOM;rawpreserves response bytes.markdownandjsoninstall Defuddle and extract an article. Userawfor an HTTP JSON body..html,.htm,.md,.markdownand.jsoninfer the corresponding format.--eval/--eval-fileawait a JSON-compatible value; undefined becomes JSON null.- Evaluation and
--formatare mutually exclusive.--output -needs a format unless evaluating. - Existing result/log files need
--overwrite. Result files publish atomically; logs may retain partial records. --content,--remove-images,--languageand--extract-debugconfigure extraction output.
| Exit code | Meaning |
|---|---|
| 0 | Success |
| 2 | Invalid arguments/input |
| 10 | Transport failure |
| 11 | HTTP error when --fail-on-http-error is set |
| 12 | Navigation failure |
| 13 | JavaScript failure |
| 14 | Timeout |
| 15 | Cancellation |
| 16 | Unsupported operation |
| 17 | Closed object or stale handle |
| 18 | Extraction, host reentry or internal runtime failure |
The generated CLI reference lists all flags and defaults.