Command-line reference¶

The Textual TUI is the default experience. Every interactive choice has an equivalent flag, so pulse is fully scriptable for CI, batch jobs, and one-off ad-hoc runs.

Synopsis¶

pulse [--headless] [--quick | --full] [--repeat N]
      [--list] [--doctor [--doctor-json]]
      [--only NAME ...] [--skip NAME ...] [--with NAME ...]
      [--install {ask,yes,no}] [-y]
      [--publish | --no-publish]
      [--name NAME] [--email EMAIL] [--relay-url URL]
      [--out DIR] [--verbose]
      [--no-history] [--history-dir DIR]
      [--baseline FILE] [--baseline-fail-on-regression]

--headless engages automatically when stdin or stdout is not a TTY, so piped invocations (CI, SSH bash -c …, container jobs) just work.

Common scripts¶

Local one-shot, no publish¶

pulse --headless --quick --no-publish

Runs the fast subset (~1-2 min), writes results.yaml + results.md + results.json + results.csv + run.log to the platform user-data directory, then exits.

CI smoke test¶

pulse --headless --quick \
      --skip compile,browser,docker,gpu,7zip,openssl \
      --install no \
      --no-publish \
      --out ./artifacts/pulse

--install no keeps CI hermetic — anything that needs a system package gets marked skipped instead of triggering sudo.

Unattended cloud benchmark with auto-publish¶

pulse --headless \
      --install yes \
      --publish \
      --name "Production fleet bot" \
      --email "[email protected]"

Auto-installs missing toolchain, runs the full suite, POSTs results to the relay, opens an MR. Exit code 0 = MR opened, 2 = relay unavailable (fallback URL is printed; submit manually).

Run only one benchmark category¶

pulse --headless --only cpu --no-publish
pulse --headless --only compile_redis,compile_sqlite --no-publish

--only and --skip take comma-separated substrings matched against the benchmark name field shown by pulse --list.

Opt in to a heavyweight benchmark¶

pulse --headless --with compile_chromium --install yes

--with enables one of the off-by-default heavy benchmarks (e.g. compile_chromium, compile_kernel).

Regression-gate a CI pipeline¶

pulse --headless --quick \
      --baseline ./baselines/golden-results.yaml \
      --baseline-fail-on-regression \
      --no-publish

Exits non-zero (code 3) if any tracked metric regressed against the baseline file. Use this to fail PRs that slow the box down.

Flag reference¶

Mode¶

flag	env	description
`--headless`	`PULSE_HEADLESS`	Skip the TUI, render with rich progress, exit. Auto-on without a TTY.
`--list`	—	List available benchmarks and exit.
`--doctor`	—	Print preflight diagnostic (host, capabilities, will-run vs will-skip) and exit.
`--doctor-json`	—	With `--doctor`, emit structured JSON instead of pretty tables.
`--quick`	—	Fast subset (smaller workloads, fewer iterations). ~1-2 min.
`--full`	—	Include heavyweights like a Linux-kernel build. ~30-60 min. Mutually exclusive with `--quick`.
`--repeat N`	—	Run each benchmark N times; report median / stdev / min per metric (default `1`).

Filtering¶

flag	description
`--only NAME`	Substring filter — only run benchmarks whose name contains any of these. Repeatable; commas split.
`--skip NAME`	Substring filter — skip benchmarks whose name matches. Repeatable; commas split.
`--with NAME`	Enable an opt-in heavyweight benchmark by name. Repeatable; commas split.

Dependencies¶

The runner detects missing system tools (cc, make, 7z, javac, openssl, …) and can install them via the host package manager (apt / dnf / pacman / apk / brew / pkg / winget).

flag	description
`--install ask` (default)	Prompt interactively. In a non-TTY, behaves like `no`.
`--install yes` / `-y`	Install without asking. The exact `sudo apt-get install -y …` line is still printed first.
`--install no`	Don't install anything; mark dependent benchmarks as skipped.

Publishing¶

In headless mode, publishing is opt-in. The TUI uses a Publish button instead.

flag	env	description
`--publish`	`PULSE_AUTO_PUBLISH`	POST results to the relay (`PULSE_RELAY_URL`) and open an MR.
`--no-publish`	—	Force-disable, even if `PULSE_AUTO_PUBLISH` is set.
`--name NAME`	`PULSE_SUBMITTER_NAME`	Submitter name attached to the MR + report.
`--email EMAIL`	`PULSE_SUBMITTER_EMAIL`	Submitter email attached to the MR + report.
`--relay-url URL`	`PULSE_RELAY_URL`	Override the relay endpoint (handy for testing your own worker).

Output¶

flag	env	description
`--out DIR`	`PULSE_OUT`	Override the run directory. Default: `~/.local/share/pulse/runs/<TIMESTAMP>` (XDG / platformdirs).
`--verbose` / `-v`	—	Set the rich console handler to DEBUG. The file log is always DEBUG.

History and baselines¶

Pulse keeps a per-machine history snapshot so consecutive runs surface regressions automatically.

flag	description
`--no-history`	Disable writing & comparing against the per-machine history snapshot.
`--history-dir DIR`	Override the history location (defaults to `<user_data_dir>/history`).
`--baseline FILE`	Compare current results against a specific prior `results.json` / `results.yaml`.
`--baseline-fail-on-regression`	In headless mode, exit non-zero if `--baseline` shows regressions.

Exit codes¶

code	meaning
`0`	Run completed; if `--publish`, MR opened.
`2`	Run completed but publishing failed (no relay reachable, or relay returned an error). Fallback URL is printed; submit manually.
`3`	`--baseline-fail-on-regression` and the baseline diff showed regressions.
other non-zero	Hard error (CLI parse failure, unhandled exception).

Individual benchmark failures do not fail the process — they're recorded in the report with status: failed.