CLI Options Reference

Complete reference for k6 command-line options

CLI Options Reference

Comprehensive reference for all k6 command-line options.

Overview

k6 accepts configuration through multiple sources (in order of precedence):

1. Command-line flags
2. Environment variables
3. Configuration file (k6.json)
4. Script options (export const options = {})

CLI flags have the highest priority and will override all other sources.

Global Flags

These flags are available for all k6 commands:

--address · string · default: "localhost:6565"

Address of the REST API server. Use empty string to disable.

--config · string · default: "./k6.json"

Path to the JSON configuration file.

--log-format · string · default: "text"

Log output format: text or json.

--log-output · string · default: "stderr"

Log output destination: stderr, stdout, or a file path.

--no-color · boolean

Disable colored output.

-q, --quiet · boolean

Disable progress updates.

-v, --verbose · boolean

Enable verbose logging.

--profiling-enabled · boolean

Enable profiling endpoints on the REST API.

Execution Options

Virtual Users and Duration

-u, --vus · int · default: "1"

Number of virtual users to run concurrently.

k6 run --vus 10 script.js

-d, --duration · duration

Test duration limit. Accepts units: s (seconds), m (minutes), h (hours).

k6 run --duration 30s script.js
k6 run --duration 5m script.js
k6 run --duration 1h30m script.js

-i, --iterations · int

Total number of script iterations to execute across all VUs.

k6 run --iterations 100 script.js

Ramping and Stages

-s, --stage · string[]

Add an execution stage in the format [duration]:[target]. Can be specified multiple times.

k6 run -s 10s:50 -s 30s:50 -s 10s:0 script.js

This ramps to 50 VUs over 10s, maintains 50 VUs for 30s, then ramps down to 0 over 10s.

-p, --paused · boolean

Start the test in a paused state. Resume with k6 resume.

k6 run --paused script.js

Distributed Execution

--execution-segment · string

Run only a segment of the test for distributed execution.

Formats:

• Percentage: 10%
• Fraction: 1/4
• Range: 0.25:0.5

k6 run --execution-segment "0:1/3" script.js

--execution-segment-sequence · string

Define the segment sequence for distributed execution.

k6 run --execution-segment-sequence "0,1/3,2/3,1" --execution-segment "0:1/3" script.js

HTTP Options

--max-redirects · int · default: "10"

Maximum number of HTTP redirects to follow.

--batch · int · default: "20"

Maximum number of parallel batch requests.

--batch-per-host · int · default: "6"

Maximum number of parallel batch requests per host.

--rps · int · default: "0"

Limit requests per second globally. 0 means unlimited.

k6 run --rps 100 script.js

--user-agent · string

User-Agent string for HTTP requests.

k6 run --user-agent "MyBot/1.0" script.js

--http-debug · string

Log HTTP requests and responses.

• --http-debug or --http-debug=headers - Log headers only
• --http-debug=full - Log headers and bodies

k6 run --http-debug=full script.js

--insecure-skip-tls-verify · boolean

Skip TLS certificate verification.

k6 run --insecure-skip-tls-verify script.js

--no-connection-reuse · boolean

Disable HTTP keep-alive (connection reuse).

--no-vu-connection-reuse · boolean

Don’t reuse connections between iterations within a VU.

--min-iteration-duration · duration

Minimum time k6 will take to execute a single iteration.

k6 run --min-iteration-duration 1s script.js

-w, --throw · boolean

Throw warnings as errors (e.g., failed HTTP requests).

--discard-response-bodies · boolean

Read HTTP response bodies but don’t save them. Reduces memory usage.

Network Configuration

--blacklist-ip · string[]

Blacklist IP ranges from being called.

k6 run --blacklist-ip "10.0.0.0/8" --blacklist-ip "192.168.0.0/16" script.js

--block-hostnames · string[]

Block hostname patterns (case-insensitive, supports wildcards).

k6 run --block-hostnames "*.internal.example.com" script.js

--local-ips · string

Specify local IP addresses or ranges for VUs to use.

k6 run --local-ips "192.168.0.10-192.168.0.25" script.js

--dns · string

DNS resolver configuration.

Format: ttl=VALUE,select=VALUE,policy=VALUE

• ttl: Cache TTL (inf, 0, or duration like 30s)
• select: IP selection (first, random, roundRobin)
• policy: IP version policy (preferIPv4, preferIPv6, onlyIPv4, onlyIPv6, any)

k6 run --dns "ttl=5m,select=random,policy=preferIPv4" script.js

Lifecycle Options

--no-setup · boolean

Skip running the setup() function.

k6 run --no-setup script.js

--no-teardown · boolean

Skip running the teardown() function.

k6 run --no-teardown script.js

-l, --linger · boolean

Keep the REST API server running after the test finishes.

k6 run --linger script.js

Output Options

-o, --out · string[]

Send metrics to an external output. Can be specified multiple times.

k6 run --out json=results.json --out influxdb=http://localhost:8086 script.js

Available outputs: json, csv, cloud, influxdb, statsd, datadog, prometheus, opentelemetry

--summary-mode · string · default: "compact"

End-of-test summary display mode.

• compact - Condensed summary (default)
• full - Detailed summary with all metrics
• disabled - No summary

k6 run --summary-mode full script.js

--summary-export · string

Export the end-of-test summary to a JSON file.

k6 run --summary-export summary.json script.js

--summary-trend-stats · string[]

Define statistics to calculate for trend metrics.

Available: avg, min, med, max, count, p(N) where N is 0-100

k6 run --summary-trend-stats "avg,p(95),p(99)" script.js

--summary-time-unit · string

Time unit for displaying trend statistics: s, ms, or us.

k6 run --summary-time-unit ms script.js

--console-output · string

Redirect console logging to a file.

k6 run --console-output console.log script.js

--no-usage-report · boolean

Disable anonymous usage statistics reporting.

Metrics and Tags

--system-tags · string[]

System tags to include in metrics.

Available tags: proto, subproto, status, method, url, name, group, check, error, tls_version, scenario, service, expected_response

k6 run --system-tags "proto,status,method" script.js

--tag · string[]

Add custom tags to all metrics.

k6 run --tag environment=staging --tag team=backend script.js

--no-thresholds · boolean

Disable threshold execution.

k6 run --no-thresholds script.js

Runtime Options

-e, --env · string[]

Set or override environment variables for the script.

k6 run -e API_URL=https://api.example.com -e API_KEY=secret script.js

--include-system-env-vars · boolean

Pass all system environment variables to the test script.

k6 run --include-system-env-vars script.js

--compatibility-mode · string · default: "extended"

JavaScript runtime compatibility mode.

• extended - Sobek with global alias for globalThis
• base - Pure Sobek (ECMAScript)
• experimental_enhanced - TypeScript and ES6+ via esbuild

k6 run --compatibility-mode base script.js

-t, --type · string

Override test type detection.

• js - JavaScript test
• archive - Test archive

k6 run --type js script.txt

Tracing Options

--traces-output · string · default: "none"

Configure distributed tracing output.

• none - No tracing (default)
• otel - OpenTelemetry to default endpoint (localhost:4317)
• otel=host:port - OpenTelemetry to specified endpoint

k6 run --traces-output otel=collector:4317 script.js

Configuration File

See Configuration File Format for details on using k6.json.

Environment Variables

See Environment Variables for the complete list of supported environment variables.

See Also

• k6 run
• Environment variables
• Configuration file