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
--collectionRequired. Path to Postman collection JSON.
--environmentPath to Postman environment JSON.
--patternTest pattern: load, stress, spike, soak, ramp, burst, breakpoint, custom, ratelimit (default: burst).
--requestsTotal requests for burst/ratelimit (default: 200).
--concurrencyMax concurrent connections (default: 20).
--rpsTarget requests per second (default: 50).
--durationTest duration in seconds (default: 300).
--var KEY=VALUEVariable override. Repeatable.
--save-responsesSave response bodies in the report.
--outputDirectory to write reports to (default: reports/).
--formatReport format: html, json, csv (default: html).
--stagesCustom stages JSON array.
--timeoutPer-request timeout in seconds (default: 30.0).
--no-verify-sslSkip SSL certificate verification.
--assert EXPRAssertion threshold, e.g. p95_latency_ms<500. Repeatable.
--junit PATHWrite JUnit XML report to this path.
--open-reportOpen HTML report in browser after the run.
--config PATHPath 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
--collectionRequired. Path to Postman collection JSON.
--environmentPath to Postman environment JSON.
--iterationsNumber of times to iterate through the collection (default: 1).
--delayDelay between requests in milliseconds (default: 0).
--var KEY=VALUEVariable override. Repeatable.
--outputOutput directory for reports (default: .).
--timeoutRequest timeout in seconds (default: 30.0).
 
overload sequential --collection api.json --iterations 3 --delay 1000

Exit Codes