CLI Reference

Complete command line guide for Overload.

Global Options

Flag	Description
`--version`	Prints the Overload version.
`--debug`	Enables DEBUG logging.

You can also enable debug logging using the environment variable: OVERLOAD_DEBUG=1 overload

`overload` / `overload ui`

Starts the browser UI. This is the default command if you run overload without arguments.

Flag	Description
`--port`	Port number (default: 3000)
`--host`	Host to bind to (default: 127.0.0.1)
`--no-browser`	Don't open the browser automatically

overload ui --port 8080
overload ui --host 0.0.0.0 --no-browser

`overload run`

Runs a load test from the CLI (headless mode). This is ideal for CI/CD environments.

Flag	Description
`--collection`	Required. Path to Postman collection JSON.
`--environment`	Path to Postman environment JSON.
`--pattern`	Test pattern: load, stress, spike, soak, ramp, burst, breakpoint, custom, ratelimit (default: burst).
`--requests`	Total requests for burst/ratelimit (default: 200).
`--concurrency`	Max concurrent connections (default: 20).
`--rps`	Target requests per second (default: 50).
`--duration`	Test duration in seconds (default: 300).
`--var KEY=VALUE`	Variable override. Repeatable.
`--save-responses`	Save response bodies to `responses.json` in the run folder (first 10 KB per response).
`--output`	Directory to write reports to (default: reports/).
`--format`	Report format: html, json, csv (default: html).
`--stages`	Custom stages JSON array.
`--timeout`	Per-request timeout in seconds (default: 30.0).
`--no-verify-ssl`	Skip SSL certificate verification.
`--assert EXPR`	Assertion threshold, e.g. p95_latency_ms<500. Repeatable.
`--junit PATH`	Write JUnit XML report to this path.
`--open-report`	Open HTML report in browser after the run.
`--exceed-multiplier`	Phase 2 multiplier for ratelimit pattern — how many times the cap to send (2 = 2×, 3 = 3×, etc., default: 2).
`--data PATH`	CSV file for data-driven testing. Each row fills `{{placeholders}}` in URLs, headers, body, query params, and auth fields (round-robin).
`--config PATH`	Path to overload.config.yaml.

Examples:

# Burst test
overload run --collection api.json --pattern burst --requests 500

# Load test with assertions and JUnit output
overload run --collection api.json --pattern load --rps 100 --duration 60 \
  --assert "p95_latency_ms<300" --assert "error_rate_pct==0" \
  --junit results.xml

# Custom variables
overload run --collection api.json --var base_url=https://prod.api.com --var token=abc

`overload sequential`

Runs collection requests sequentially, one at a time, in order. Useful for functional testing workflows.

Flag	Description
`--collection`	Required. Path to Postman collection JSON.
`--environment`	Path to Postman environment JSON.
`--iterations`	Number of times to iterate through the collection (default: 1).
`--delay`	Delay between requests in milliseconds (default: 0).
`--var KEY=VALUE`	Variable override. Repeatable.
`--output`	Output directory for reports (default: .).
`--timeout`	Request timeout in seconds (default: 30.0).

overload sequential --collection api.json --iterations 3 --delay 1000

`overload mcp`

Starts a stdio MCP server so Claude Code, Codex CLI, GitHub Copilot, and other MCP clients can drive load tests conversationally.

Requires: pip install "overload-cli[mcp]"

Registration (one-time setup)

# Claude Code
claude mcp add overload -- overload mcp

# Codex CLI
codex mcp add overload -- overload mcp

GitHub Copilot (VS Code) — add to settings.json:

{
  "mcpServers": {
    "overload": { "command": "overload", "args": ["mcp"] }
  }
}

Available MCP tools

Tool	Description
`list_patterns`	Returns all 10 test types with descriptions.
`describe_collection(path)`	Parses a Postman collection; returns request list and detected `{{placeholders}}`.
`run_load_test(...)`	Starts a test and returns a `run_id` immediately. Guardrails: concurrency ≤ 200, total_requests ≤ 10,000.
`get_run_status(run_id)`	Polls phase, completed_requests, and elapsed time.
`get_run_results(run_id)`	Returns final stats (p50/p95/p99, RPS, error rate), verdict, and report path.
`stop_run(run_id)`	Graceful stop — generates a partial report from collected data.

Exit Codes

0: Success (all assertions passed, or no assertions configured)
1: Assertion failure (one or more assertions failed)
2: Invalid configuration or assertion expression