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

# k6 run

> Run a load test script with k6

# k6 run

Run a load test script. This is the primary command for executing k6 tests.

## Synopsis

```bash theme={null}
k6 run [flags] <script>
```

## Description

The `k6 run` command starts a test and exposes a REST API to interact with it. The command loads a test script, initializes virtual users (VUs), and executes the test according to the configured options.

The script argument can be:

* A path to a JavaScript test file
* A path to a k6 archive (`.tar` file)
* `-` to read the script from stdin

## Examples

```bash theme={null}
# Run a single VU, once
k6 run script.js

# Run a single VU, 10 times
k6 run -i 10 script.js

# Run 5 VUs, splitting 10 iterations between them
k6 run -u 5 -i 10 script.js

# Run 5 VUs for 10 seconds
k6 run -u 5 -d 10s script.js

# Ramp VUs from 0 to 100 over 10s, stay there for 60s, then 10s down to 0
k6 run -u 0 -s 10s:100 -s 60s:100 -s 10s:0

# Send metrics to a remote storage using the OpenTelemetry output
k6 run -o opentelemetry script.js
```

## Flags

### Test Execution

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

<ParamField path="-d, --duration" type="duration">
  Test duration limit (e.g., `10s`, `5m`, `1h30m`)
</ParamField>

<ParamField path="-i, --iterations" type="int">
  Script total iteration limit (among all VUs)
</ParamField>

<ParamField path="-s, --stage" type="string[]">
  Add a stage in the format `[duration]:[target]` (e.g., `10s:100`). Can be specified multiple times.
</ParamField>

<ParamField path="-p, --paused" type="boolean">
  Start the test in a paused state
</ParamField>

<ParamField path="--execution-segment" type="string">
  Limit execution to a specified segment (e.g., `10%`, `1/3`, `0.2:2/3`)
</ParamField>

<ParamField path="--execution-segment-sequence" type="string">
  The execution segment sequence for distributed execution
</ParamField>

### Test Lifecycle

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

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

<ParamField path="-l, --linger" type="boolean">
  Keep the API server alive past test end
</ParamField>

### HTTP Options

<ParamField path="--max-redirects" type="int" default="10">
  Follow at most n redirects
</ParamField>

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

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

<ParamField path="--rps" type="int">
  Limit requests per second (0 = unlimited)
</ParamField>

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

<ParamField path="--http-debug" type="string">
  Log all HTTP requests and responses. Use `--http-debug=full` to include body.
</ParamField>

<ParamField path="--insecure-skip-tls-verify" type="boolean">
  Skip verification of TLS certificates
</ParamField>

<ParamField path="--no-connection-reuse" type="boolean">
  Disable keep-alive connections
</ParamField>

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

<ParamField path="--min-iteration-duration" type="duration">
  Minimum amount of time k6 will take executing a single iteration
</ParamField>

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

<ParamField path="--discard-response-bodies" type="boolean">
  Read but don't process or save HTTP response bodies
</ParamField>

### Network Configuration

<ParamField path="--blacklist-ip" type="string[]">
  Blacklist an IP range from being called
</ParamField>

<ParamField path="--block-hostnames" type="string[]">
  Block a case-insensitive hostname pattern (with optional leading wildcard)
</ParamField>

<ParamField path="--local-ips" type="string">
  Client IP ranges and/or CIDRs from which each VU will make requests
</ParamField>

<ParamField path="--dns" type="string">
  DNS resolver configuration. Format: `ttl=VALUE,select=VALUE,policy=VALUE`
</ParamField>

### Runtime Options

<ParamField path="-e, --env" type="string[]">
  Add/override environment variable with `VAR=value`
</ParamField>

<ParamField path="--include-system-env-vars" type="boolean">
  Pass the real system environment variables to the runtime
</ParamField>

<ParamField path="--compatibility-mode" type="string" default="extended">
  JavaScript compatibility mode: `extended` or `base`
</ParamField>

<ParamField path="-t, --type" type="string">
  Override test type: `js` or `archive`
</ParamField>

### Output and Metrics

<ParamField path="-o, --out" type="string[]">
  URI for an external metrics database (can be specified multiple times)
</ParamField>

<ParamField path="--summary-mode" type="string" default="compact">
  Summary display mode: `compact`, `full`, or `disabled`
</ParamField>

<ParamField path="--summary-export" type="string">
  Output the end-of-test summary report to a JSON file
</ParamField>

<ParamField path="--summary-trend-stats" type="string[]">
  Define stats for trend metrics (e.g., `avg,p(95),p(99)`)
</ParamField>

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

<ParamField path="--system-tags" type="string[]">
  Only include these system tags in metrics
</ParamField>

<ParamField path="--tag" type="string[]">
  Add a tag to be applied to all samples in the format `[name]=[value]`
</ParamField>

<ParamField path="--no-thresholds" type="boolean">
  Don't run thresholds
</ParamField>

<ParamField path="--console-output" type="string">
  Redirect console logging to the provided output file
</ParamField>

### Other Options

<ParamField path="--config" type="string">
  Path to config file (default: `./k6.json`)
</ParamField>

<ParamField path="--no-usage-report" type="boolean">
  Don't send anonymous usage statistics
</ParamField>

<ParamField path="--traces-output" type="string" default="none">
  Output for k6 traces: `none` or `otel[=host:port]`
</ParamField>

## Exit Codes

k6 uses specific exit codes to indicate different error conditions:

* `0` - Test passed successfully
* `99` - Test failed due to threshold violations
* `108` - Test marked as failed via `exec.test.status`
* Other non-zero codes indicate various errors

## REST API

When running a test, k6 exposes a REST API (by default on `localhost:6565`) that can be used to:

* Get test status
* Pause/resume execution
* Scale VUs dynamically
* Retrieve metrics

Use the global `--address` flag to configure the API server address.

## See Also

* [k6 archive](/cli/archive) - Create an archive of your test
* [k6 cloud](/cli/cloud) - Run tests in Grafana Cloud
* [CLI options reference](/cli/options)