CLI Options Reference

Comprehensive reference for all k6 command-line options.

Overview

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

Command-line flags
Environment variables
Configuration file (k6.json)
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.

Commands

Configuration

CLI Options Reference

CLI Options Reference

Overview

Global Flags

Execution Options

Virtual Users and Duration

Ramping and Stages

Distributed Execution

HTTP Options

Network Configuration

Lifecycle Options

Output Options

Metrics and Tags

Runtime Options

Tracing Options

Configuration File

Environment Variables

See Also

Build docs developers (and LLMs) love

Commands

Configuration

​CLI Options Reference

​Overview

​Global Flags

​Execution Options

​Virtual Users and Duration

​Ramping and Stages

​Distributed Execution

​HTTP Options

​Network Configuration

​Lifecycle Options

​Output Options

​Metrics and Tags

​Runtime Options

​Tracing Options

​Configuration File

​Environment Variables

​See Also

Build docs developers (and LLMs) love

CLI Options Reference

Overview

Global Flags

Execution Options

Virtual Users and Duration

Ramping and Stages

Distributed Execution

HTTP Options

Network Configuration

Lifecycle Options

Output Options

Metrics and Tags

Runtime Options

Tracing Options

Configuration File

Environment Variables

See Also