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

> Run and manage tests in Grafana Cloud

# k6 cloud

Run and manage tests in Grafana Cloud k6.

## Synopsis

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

<Note>
  Running tests directly with `k6 cloud <file>` is deprecated. Use `k6 cloud run <file>` instead.
</Note>

## Subcommands

### k6 cloud login

Authenticate with Grafana Cloud k6.

```bash theme={null}
k6 cloud login [flags]
```

See [k6 login](/cli/login) for details.

### k6 cloud run

Run a test in Grafana Cloud.

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

### k6 cloud upload

Upload a test to Grafana Cloud without running it.

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

## Examples

```bash theme={null}
# 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)

<ParamField path="--show-logs" type="boolean" default="true">
  Enable showing of logs when a test is executed in the cloud
</ParamField>

<ParamField path="--exit-on-running" type="boolean">
  Exit when test reaches the running status (don't wait for completion)
</ParamField>

### Test Configuration Flags

All standard test configuration flags from `k6 run` are available:

<ParamField path="-u, --vus" type="int">
  Number of virtual users
</ParamField>

<ParamField path="-d, --duration" type="duration">
  Test duration
</ParamField>

<ParamField path="-i, --iterations" type="int">
  Total iteration limit
</ParamField>

<ParamField path="-s, --stage" type="string[]">
  Add execution stages
</ParamField>

See [k6 run](/cli/run) for all available options.

## Environment Variables

<ParamField path="K6_CLOUD_TOKEN" type="string">
  Grafana Cloud k6 authentication token
</ParamField>

<ParamField path="K6_CLOUD_HOST" type="string">
  Grafana Cloud k6 API host (default: `https://ingest.k6.io`)
</ParamField>

<ParamField path="K6_CLOUD_PROJECT_ID" type="int">
  Project ID for organizing tests
</ParamField>

<ParamField path="K6_CLOUD_STACK_ID" type="int">
  Stack ID for the Grafana Cloud instance
</ParamField>

<ParamField path="K6_SHOW_CLOUD_LOGS" type="boolean" default="true">
  Show cloud logs during test execution
</ParamField>

<ParamField path="K6_EXIT_ON_RUNNING" type="boolean">
  Exit when test starts running
</ParamField>

## Authentication

Before running cloud tests, you must authenticate using one of these methods:

### Interactive Login (Recommended)

```bash theme={null}
k6 cloud login
```

This opens a browser for authentication and saves your token.

### Token Authentication

```bash theme={null}
export K6_CLOUD_TOKEN=your-token-here
k6 cloud run script.js
```

### Script Configuration

Add to your script:

```javascript theme={null}
export const options = {
  cloud: {
    token: 'your-token-here',
    projectID: 12345,
  },
};
```

<Warning>
  Don't commit tokens to version control. Use environment variables instead.
</Warning>

## Project Configuration

Tests can be organized into projects:

```bash theme={null}
# 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:

```javascript theme={null}
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

* [k6 login](/cli/login) - Authentication details
* [k6 run](/cli/run) - Local test execution
* [k6 archive](/cli/archive) - Create test archives
* [Grafana Cloud k6 Documentation](https://grafana.com/docs/grafana-cloud/testing/k6/)