CLI
Every LoadWave command and flag — run, serve, agent, validate, demo and version.
One binary, six commands. loadwave <command> --help prints the same
information you will find here.
| Command | What it does |
|---|---|
loadwave demo | Run a self-contained demo against a built-in target. Nothing to configure. |
loadwave run | Run a test to completion and print a report. Add --ui for the dashboard. |
loadwave serve | Long-lived coordinator and dashboard; runs are started from the browser or the API. |
loadwave agent | Join a coordinator and generate load on this machine. |
loadwave validate | Check a configuration without running it. Belongs in a pre-commit hook. |
loadwave version | Print version and build information. |
Global flags
Available on every command.
| Flag | Default | Meaning |
|---|---|---|
--log-level | info | debug, info, warn or error. |
--log-format | text | text or json. Use json when something is collecting the output. |
loadwave run
Runs a load test to completion. Starts a coordinator, an agent and its worker
processes in one command, prints a report, and exits 2 if any threshold was
breached — which is what makes it usable as a CI gate.
loadwave run [config.yaml] [flags]# Run a configuration file
loadwave run test.yaml
# Quick check with no file
loadwave run --url https://example.com --vus 50 --duration 30s
# Ramp up, watch it live, fail the build if the p95 exceeds 500ms
loadwave run test.yaml --ui --threshold 'http_req_duration:p95<500'Shaping the load
| Flag | Default | Meaning |
|---|---|---|
-u, --url | — | Base URL for relative request paths. Overrides baseURL. |
--name | — | Name for this test, shown in the dashboard. |
--vus | — | Virtual users to hold (constant-vus). |
-d, --duration | — | How long to hold the load, e.g. 30s or 5m. |
--stages | — | Ramping profile as duration:target pairs: 30s:100,5m:100,30s:0. |
--iterations | — | Stop after this many iterations in total. |
--rate | — | Cap iterations started per second across the whole run. |
--between-requests | 1s | Pause after every request, e.g. 1s or 500ms-2s; "0" for none. |
--graceful-stop | 30s | How long in-flight iterations may take to finish when stopping. |
--scenario | all | Scenario to run, as name or name=weight. Repeatable. |
Requests and assertions
| Flag | Default | Meaning |
|---|---|---|
-H, --header | — | Header sent with every request, as Name: value. Repeatable. |
--timeout | 30s | Per-request timeout. |
--insecure | false | Skip TLS certificate verification. |
--tag | — | Tag applied to every metric, as key=value. Repeatable. |
--threshold | — | Pass/fail assertion, e.g. http_req_duration:p95<500. Repeatable. |
Output
| Flag | Default | Meaning |
|---|---|---|
-o, --out | — | Write the run summary as JSON to this file. |
--report | — | Write a self-contained HTML report, with charts, to this file. |
-q, --quiet | false | Suppress the live progress line. |
--ui | false | Serve the live dashboard during the run. |
--ui-addr | :8088 | Dashboard listen address. |
Fleet and resolution
| Flag | Default | Meaning |
|---|---|---|
-w, --workers | cores − 1 | Worker processes per agent. |
--max-vus | 1000 per core | Virtual user ceiling this machine advertises. |
--agents | 1 | Number of agents to wait for before starting. |
--wait-agents | 30s | How long to wait for those agents to connect. |
--resolution | 1s | Metric bucket width, and therefore the chart's time resolution. |
--agents is how you make a distributed run wait for its fleet rather than
starting with whoever happens to have connected. Set it to the number of load
hosts you expect; --wait-agents bounds how long that patience lasts.
loadwave serve
Starts a long-lived coordinator with the dashboard attached. Runs are started from the browser or through the REST API rather than from the command line.
A local agent is started too, so a single machine works out of the box.
# Everything on one machine
loadwave serve
# A coordinator for a fleet, generating no load itself
loadwave serve --listen 0.0.0.0:8090 --local-agent=false| Flag | Default | Meaning |
|---|---|---|
--listen | 0.0.0.0:8090 | Address agents connect to. |
--ui-addr | :8088 | Dashboard listen address. |
--local-agent | true | Also run an agent on this machine. |
-w, --workers | cores − 1 | Worker processes for the local agent. |
--max-vus | 1000 per core | Virtual user ceiling the local agent advertises. |
--read-only | false | Serve the dashboard without allowing runs to be started or stopped. |
--allow-shutdown | false | Let the dashboard's Power off control stop this process. |
--allowed-origin | — | Extra browser origin allowed to open the live stream. Repeatable. |
--resolution | 1s | Metric bucket width. |
--window | 1h | How much chart history to retain. |
--read-only is the right flag when showing a run to an audience, or when the
dashboard is reachable by more people than should be able to start load against
production. It is not a security boundary — the control plane is
unauthenticated. See Securing it.
loadwave agent
Runs an agent that joins a coordinator elsewhere. It spawns worker processes on this host and runs whatever share of the load the coordinator assigns it.
It dials out, so it needs no inbound ports and works from behind NAT.
loadwave agent --coordinator loadwave.internal:8090
loadwave agent --coordinator 10.0.0.5:8090 --workers 8 --label region=eu-west-1| Flag | Default | Meaning |
|---|---|---|
-c, --coordinator | — | Required. Coordinator address, e.g. loadwave.internal:8090. |
-w, --workers | cores − 1 | Worker processes to spawn. |
--max-vus | 1000 per core | Virtual user ceiling to advertise. |
--label | — | Label advertised to the coordinator, as key=value. Repeatable. |
--node-id | hostname and pid | Identifier for this agent. |
The binary must be the same one the rest of the fleet is running. For a test written with the Go SDK the scenarios are compiled into it, so the binary is the test.
loadwave validate
Parses a configuration, resolves its scenarios and describes what it would do. Nothing is executed and no load is generated.
loadwave validate test.yamlThis is what belongs in a pre-commit hook or a pull-request check: it catches a misspelled field, a scenario name that does not exist in this binary, or a threshold on a metric that will never be produced — all in milliseconds, long before anyone waits out a real run to discover it.
It accepts the same load-shaping flags as run (--url, --vus, --duration,
--stages, --iterations, --rate, --between-requests, --graceful-stop,
--scenario, --header, --timeout, --insecure, --tag, --threshold,
--name, --workers), so you can validate exactly the invocation CI will make.
loadwave demo
Runs a demo test with the dashboard, against a target LoadWave starts itself. A small HTTP server is started in this process with a few endpoints of differing speed and a sprinkling of errors, and a two-scenario test is run against it.
loadwave demo # dashboard on :8088, runs for 10 minutes
loadwave demo --duration 2m --vus 50
loadwave demo --headless # no dashboard, just the report| Flag | Default | Meaning |
|---|---|---|
-d, --duration | 10m | How long to run. Long enough by default to click around the dashboard. |
--vus | 25 | Peak virtual users. |
--headless | false | Skip the dashboard and just print the report. |
--ui-addr | :8088 | Dashboard listen address. |
--report | — | Write a self-contained HTML report to this file. |
-q, --quiet | false | Suppress the live progress line. |
The demo server is a toy. Its numbers say nothing about your hardware — it is the fastest way to see what the dashboard shows, and a good end-to-end check of a fresh build.
loadwave version
Prints version and build information.
loadwave versionExit codes
The run completed and every threshold passed.
LoadWave could not do what was asked: bad configuration, no agents, unreachable coordinator.
The run completed, but a threshold was breached.
Ctrl-C, or a SIGINT from whatever supervises the process.
The distinction between 1 and 2 is deliberate: "the tool broke" and "the
service was too slow" call for very different responses from a pipeline. See
Using it in CI.
Shell completion
Cobra's generator is wired up, so completions work the usual way:
loadwave completion bash > /etc/bash_completion.d/loadwave
loadwave completion zsh > "${fpath[1]}/_loadwave"
loadwave completion fish > ~/.config/fish/completions/loadwave.fish