Configuration

Configuration

loadbearer run takes its settings from three places, in this order of precedence:

1. Command-line switches — always win.
2. A --config TOML file — fills in anything not given on the command line.
3. Built-in defaults — used for anything neither of the above sets.

Only run reads the config file. compare, info, list and baseline don't take one.

The file

TOML, every key optional. Unknown keys are rejected with an error listing the valid ones, so a typo fails loudly instead of being ignored. A full example ships as loadbearer.example.toml.

Key	Type	Equivalent switch	Default
profile	string	--profile	"general"
duration	"short" | "normal" | "thorough"	--duration	"normal"
curve_k	float, 0.05–3.0	--curve-k	0.5
target_dir	path	--target-dir	the working directory
runs	integer	--runs	preset default (3 / 5 / 9)
seed	integer	--seed	a fixed built-in seed
only	array of strings	--only	all benchmarks

Output-mode flags (--plain, --json, --output) are command-line only — they're about how this invocation reports, not a standing preference.

Examples

A team standard

Check a loadbearer.toml into your repo so everyone runs the same assessment:

profile   = "dev-workstation"
duration  = "thorough"
target_dir = "/var/tmp"        # a real disk, not /tmp if that's tmpfs

loadbearer run --config loadbearer.toml --output "$(hostname).json"

CI smoke check

Fast, deterministic, machine-readable, and disk skipped so it doesn't hammer the runner's storage:

duration = "short"
seed     = 1
only     = ["cpu", "memory"]

loadbearer run --config ci.toml --json > result.json
jq -e '.overall.score >= 700' result.json

Overriding one thing

The config sets the defaults; a switch overrides just that key:

# ci.toml says duration=short, but do a proper run this once
loadbearer run --config ci.toml --duration thorough

Reproducibility

seed fixes the pseudo-random data the workloads are generated from (buffer contents, random I/O offsets), so two runs on the same machine and build differ only by genuine measurement noise, not by input. It does not make timings identical — that's what the repeated iterations and confidence flags are for. See Accuracy Notes.

Diagnostic logging

Every invocation writes a plain-text diagnostic log — one timestamped line per event: the resolved settings, each benchmark and subtest boundary, the GPU / battery / OpenCL probe outcomes, disk O_DIRECT fallbacks, the scratch-file sweep, the final grade, and any error. It is what to reach for when a run on one machine (or one machine in a fleet) behaves differently from the rest.

2026-08-29T10:12:18.480Z INFO  loadbearer::run       resolved settings: profile=general, preset=Short, …
2026-08-29T10:12:18.515Z INFO  loadbearer::gpu       probe: selected Intel(R) UHD Graphics 620 · integrated · …
2026-08-29T10:12:20.276Z DEBUG loadbearer::engine    subtest cpu/int_single done: median 548.8 Mops/s (cv 0.5%, high)
2026-08-29T10:12:30.427Z INFO  loadbearer::scoring   overall 188 [F] · profile general · … · 1 graded component(s)

Control	Effect
(default)	$XDG_CACHE_HOME/loadbearer/loadbearer.log on Linux, %LOCALAPPDATA%\loadbearer\loadbearer.log on Windows, the system temp dir otherwise. Appended to; rotated to loadbearer.log.old past ~2 MiB.
--log-file PATH	Write there instead.
--no-log	Write nothing.
--log-level LEVEL	off / error / warn / info (default) / debug / trace. debug = a line per subtest; trace = a line per timed iteration.
LOADBEARER_LOG=LEVEL	Same as --log-level; the flag wins.

All four are global — valid on any subcommand. The log lines sit at lifecycle boundaries and fallbacks, never inside a timed measurement, so logging does not affect the benchmark numbers even at info. A log file that can't be opened is a one-line stderr note, not a failure.