Skip to main content

​
k6 cloud

Run and manage tests in Grafana Cloud k6.

​
Synopsis

k6 cloud <command>
k6 cloud [flags] <script>  # Deprecated

​
Description

The k6 cloud command provides subcommands for running and managing load tests in Grafana Cloud k6. Cloud execution offers:
  • Distributed load generation from multiple geographic locations
  • Scalability beyond single-machine limitations
  • Real-time metrics visualization
  • Historical test result storage
  • Team collaboration features
Running tests directly with k6 cloud <file> is deprecated. Use k6 cloud run <file> instead.

​
Subcommands

​
k6 cloud login

Authenticate with Grafana Cloud k6. 
k6 cloud login [flags]
See k6 login for details.

​
k6 cloud run

Run a test in Grafana Cloud. 
k6 cloud run [flags] <script>

​
k6 cloud upload

Upload a test to Grafana Cloud without running it. 
k6 cloud upload [flags] <script>

​
Examples

# Authenticate with Grafana Cloud
k6 cloud login

# Run a test script in Grafana Cloud
k6 cloud run script.js

# Run a test archive in Grafana Cloud
k6 cloud run archive.tar

# Upload without running
k6 cloud upload script.js

​
Flags (for k6 cloud run)

​
--show-logs
boolean
default:"true"
Enable showing of logs when a test is executed in the cloud
​
--exit-on-running
boolean
Exit when test reaches the running status (don’t wait for completion)

​
Test Configuration Flags

All standard test configuration flags from k6 run are available:
​
-u, --vus
int
Number of virtual users
​
-d, --duration
duration
Test duration
​
-i, --iterations
int
Total iteration limit
​
-s, --stage
string[]
Add execution stages
See k6 run for all available options.

​
Environment Variables

​
K6_CLOUD_TOKEN
string
Grafana Cloud k6 authentication token
​
K6_CLOUD_HOST
string
Grafana Cloud k6 API host (default: https://ingest.k6.io)
​
K6_CLOUD_PROJECT_ID
int
Project ID for organizing tests
​
K6_CLOUD_STACK_ID
int
Stack ID for the Grafana Cloud instance
​
K6_SHOW_CLOUD_LOGS
boolean
default:"true"
Show cloud logs during test execution
​
K6_EXIT_ON_RUNNING
boolean
Exit when test starts running

​
Authentication

Before running cloud tests, you must authenticate using one of these methods: 
k6 cloud login
This opens a browser for authentication and saves your token.

​
Token Authentication

export K6_CLOUD_TOKEN=your-token-here
k6 cloud run script.js

​
Script Configuration

Add to your script: 
export const options = {
  cloud: {
    token: 'your-token-here',
    projectID: 12345,
  },
};
Don’t commit tokens to version control. Use environment variables instead.

​
Project Configuration

Tests can be organized into projects: 
# Set project via environment variable
export K6_CLOUD_PROJECT_ID=12345
k6 cloud run script.js

# Set project via script option
export const options = {
  cloud: {
    projectID: 12345,
  },
};

​
Cloud Test Options

Additional cloud-specific options can be configured in your script: 
export const options = {
  cloud: {
    projectID: 12345,
    name: 'My Load Test',
    distribution: {
      'amazon:us:ashburn': { loadZone: 'amazon:us:ashburn', percent: 50 },
      'amazon:eu:dublin': { loadZone: 'amazon:eu:dublin', percent: 50 },
    },
  },
};

​
Monitoring Test Progress

When running a cloud test:
  1. The script is uploaded and validated
  2. A test URL is displayed for real-time monitoring
  3. Progress is shown in the terminal
  4. Logs are streamed (if --show-logs is enabled)
  5. The command exits when the test completes

​
Exit Codes

  • 0 - Test completed successfully
  • 99 - Thresholds failed
  • 108 - Test marked as failed
  • Other non-zero codes indicate errors

​
Stopping Cloud Tests

Press Ctrl+C to gracefully stop a running cloud test. The test will be marked as stopped in Grafana Cloud.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us