> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/grafana/k6/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<ParamField path="--address" type="string" default="localhost:6565">
  Address of the REST API server. Use empty string to disable.
</ParamField>

<ParamField path="--config" type="string" default="./k6.json">
  Path to the JSON configuration file.
</ParamField>

<ParamField path="--log-format" type="string" default="text">
  Log output format: `text` or `json`.
</ParamField>

<ParamField path="--log-output" type="string" default="stderr">
  Log output destination: `stderr`, `stdout`, or a file path.
</ParamField>

<ParamField path="--no-color" type="boolean">
  Disable colored output.
</ParamField>

<ParamField path="-q, --quiet" type="boolean">
  Disable progress updates.
</ParamField>

<ParamField path="-v, --verbose" type="boolean">
  Enable verbose logging.
</ParamField>

<ParamField path="--profiling-enabled" type="boolean">
  Enable profiling endpoints on the REST API.
</ParamField>

## Execution Options

### Virtual Users and Duration

<ParamField path="-u, --vus" type="int" default="1">
  Number of virtual users to run concurrently.

  ```bash theme={null}
  k6 run --vus 10 script.js
  ```
</ParamField>

<ParamField path="-d, --duration" type="duration">
  Test duration limit. Accepts units: `s` (seconds), `m` (minutes), `h` (hours).

  ```bash theme={null}
  k6 run --duration 30s script.js
  k6 run --duration 5m script.js
  k6 run --duration 1h30m script.js
  ```
</ParamField>

<ParamField path="-i, --iterations" type="int">
  Total number of script iterations to execute across all VUs.

  ```bash theme={null}
  k6 run --iterations 100 script.js
  ```
</ParamField>

### Ramping and Stages

<ParamField path="-s, --stage" type="string[]">
  Add an execution stage in the format `[duration]:[target]`. Can be specified multiple times.

  ```bash theme={null}
  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.
</ParamField>

<ParamField path="-p, --paused" type="boolean">
  Start the test in a paused state. Resume with `k6 resume`.

  ```bash theme={null}
  k6 run --paused script.js
  ```
</ParamField>

### Distributed Execution

<ParamField path="--execution-segment" type="string">
  Run only a segment of the test for distributed execution.

  Formats:

  * Percentage: `10%`
  * Fraction: `1/4`
  * Range: `0.25:0.5`

  ```bash theme={null}
  k6 run --execution-segment "0:1/3" script.js
  ```
</ParamField>

<ParamField path="--execution-segment-sequence" type="string">
  Define the segment sequence for distributed execution.

  ```bash theme={null}
  k6 run --execution-segment-sequence "0,1/3,2/3,1" --execution-segment "0:1/3" script.js
  ```
</ParamField>

## HTTP Options

<ParamField path="--max-redirects" type="int" default="10">
  Maximum number of HTTP redirects to follow.
</ParamField>

<ParamField path="--batch" type="int" default="20">
  Maximum number of parallel batch requests.
</ParamField>

<ParamField path="--batch-per-host" type="int" default="6">
  Maximum number of parallel batch requests per host.
</ParamField>

<ParamField path="--rps" type="int" default="0">
  Limit requests per second globally. `0` means unlimited.

  ```bash theme={null}
  k6 run --rps 100 script.js
  ```
</ParamField>

<ParamField path="--user-agent" type="string">
  User-Agent string for HTTP requests.

  ```bash theme={null}
  k6 run --user-agent "MyBot/1.0" script.js
  ```
</ParamField>

<ParamField path="--http-debug" type="string">
  Log HTTP requests and responses.

  * `--http-debug` or `--http-debug=headers` - Log headers only
  * `--http-debug=full` - Log headers and bodies

  ```bash theme={null}
  k6 run --http-debug=full script.js
  ```
</ParamField>

<ParamField path="--insecure-skip-tls-verify" type="boolean">
  Skip TLS certificate verification.

  ```bash theme={null}
  k6 run --insecure-skip-tls-verify script.js
  ```
</ParamField>

<ParamField path="--no-connection-reuse" type="boolean">
  Disable HTTP keep-alive (connection reuse).
</ParamField>

<ParamField path="--no-vu-connection-reuse" type="boolean">
  Don't reuse connections between iterations within a VU.
</ParamField>

<ParamField path="--min-iteration-duration" type="duration">
  Minimum time k6 will take to execute a single iteration.

  ```bash theme={null}
  k6 run --min-iteration-duration 1s script.js
  ```
</ParamField>

<ParamField path="-w, --throw" type="boolean">
  Throw warnings as errors (e.g., failed HTTP requests).
</ParamField>

<ParamField path="--discard-response-bodies" type="boolean">
  Read HTTP response bodies but don't save them. Reduces memory usage.
</ParamField>

## Network Configuration

<ParamField path="--blacklist-ip" type="string[]">
  Blacklist IP ranges from being called.

  ```bash theme={null}
  k6 run --blacklist-ip "10.0.0.0/8" --blacklist-ip "192.168.0.0/16" script.js
  ```
</ParamField>

<ParamField path="--block-hostnames" type="string[]">
  Block hostname patterns (case-insensitive, supports wildcards).

  ```bash theme={null}
  k6 run --block-hostnames "*.internal.example.com" script.js
  ```
</ParamField>

<ParamField path="--local-ips" type="string">
  Specify local IP addresses or ranges for VUs to use.

  ```bash theme={null}
  k6 run --local-ips "192.168.0.10-192.168.0.25" script.js
  ```
</ParamField>

<ParamField path="--dns" type="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`)

  ```bash theme={null}
  k6 run --dns "ttl=5m,select=random,policy=preferIPv4" script.js
  ```
</ParamField>

## Lifecycle Options

<ParamField path="--no-setup" type="boolean">
  Skip running the `setup()` function.

  ```bash theme={null}
  k6 run --no-setup script.js
  ```
</ParamField>

<ParamField path="--no-teardown" type="boolean">
  Skip running the `teardown()` function.

  ```bash theme={null}
  k6 run --no-teardown script.js
  ```
</ParamField>

<ParamField path="-l, --linger" type="boolean">
  Keep the REST API server running after the test finishes.

  ```bash theme={null}
  k6 run --linger script.js
  ```
</ParamField>

## Output Options

<ParamField path="-o, --out" type="string[]">
  Send metrics to an external output. Can be specified multiple times.

  ```bash theme={null}
  k6 run --out json=results.json --out influxdb=http://localhost:8086 script.js
  ```

  Available outputs: `json`, `csv`, `cloud`, `influxdb`, `statsd`, `datadog`, `prometheus`, `opentelemetry`
</ParamField>

<ParamField path="--summary-mode" type="string" default="compact">
  End-of-test summary display mode.

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

  ```bash theme={null}
  k6 run --summary-mode full script.js
  ```
</ParamField>

<ParamField path="--summary-export" type="string">
  Export the end-of-test summary to a JSON file.

  ```bash theme={null}
  k6 run --summary-export summary.json script.js
  ```
</ParamField>

<ParamField path="--summary-trend-stats" type="string[]">
  Define statistics to calculate for trend metrics.

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

  ```bash theme={null}
  k6 run --summary-trend-stats "avg,p(95),p(99)" script.js
  ```
</ParamField>

<ParamField path="--summary-time-unit" type="string">
  Time unit for displaying trend statistics: `s`, `ms`, or `us`.

  ```bash theme={null}
  k6 run --summary-time-unit ms script.js
  ```
</ParamField>

<ParamField path="--console-output" type="string">
  Redirect console logging to a file.

  ```bash theme={null}
  k6 run --console-output console.log script.js
  ```
</ParamField>

<ParamField path="--no-usage-report" type="boolean">
  Disable anonymous usage statistics reporting.
</ParamField>

## Metrics and Tags

<ParamField path="--system-tags" type="string[]">
  System tags to include in metrics.

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

  ```bash theme={null}
  k6 run --system-tags "proto,status,method" script.js
  ```
</ParamField>

<ParamField path="--tag" type="string[]">
  Add custom tags to all metrics.

  ```bash theme={null}
  k6 run --tag environment=staging --tag team=backend script.js
  ```
</ParamField>

<ParamField path="--no-thresholds" type="boolean">
  Disable threshold execution.

  ```bash theme={null}
  k6 run --no-thresholds script.js
  ```
</ParamField>

## Runtime Options

<ParamField path="-e, --env" type="string[]">
  Set or override environment variables for the script.

  ```bash theme={null}
  k6 run -e API_URL=https://api.example.com -e API_KEY=secret script.js
  ```
</ParamField>

<ParamField path="--include-system-env-vars" type="boolean">
  Pass all system environment variables to the test script.

  ```bash theme={null}
  k6 run --include-system-env-vars script.js
  ```
</ParamField>

<ParamField path="--compatibility-mode" type="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

  ```bash theme={null}
  k6 run --compatibility-mode base script.js
  ```
</ParamField>

<ParamField path="-t, --type" type="string">
  Override test type detection.

  * `js` - JavaScript test
  * `archive` - Test archive

  ```bash theme={null}
  k6 run --type js script.txt
  ```
</ParamField>

## Tracing Options

<ParamField path="--traces-output" type="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

  ```bash theme={null}
  k6 run --traces-output otel=collector:4317 script.js
  ```
</ParamField>

## Configuration File

See [Configuration File Format](/cli/configuration-file) for details on using `k6.json`.

## Environment Variables

See [Environment Variables](/cli/environment-variables) for the complete list of supported environment variables.

## See Also

* [k6 run](/cli/run)
* [Environment variables](/cli/environment-variables)
* [Configuration file](/cli/configuration-file)