Documentation Grafana Cloud Testing and synthetics Performance testing Author and run tests Authenticate on the CLI

Authenticate on the CLI

To run cloud tests from the CLI, you need to authenticate your account. Authentication is required both for tests that run on the cloud service and for results that stream to the cloud service. To authenticate accounts, k6 provides an API token, which you can pass on the CLI or through the REST API.

You can generate two types of API tokens for k6 Cloud, depending on how you want to authenticate:

• Personal level API tokens grant access through your account with the Grafana Cloud k6 App.
• Stack level API tokens grant access for actions not tied to a user but to the Grafana Cloud Stack.

To generate API tokens, follow these steps.

Get a personal API token

A personal API token provides API access to your account with k6.

To get a personal API token:

1. Log in to your Grafana Cloud account and open a stack.
2. On the main menu, click Testing & synthetics -> Performance -> Settings.
3. Under Access, click Personal token. Here you can view, copy, and regenerate your personal API token.

Get a Grafana Stack API token

A Stack API token provides access to all projects within the Grafana Cloud Stack. You can use it to run tests without linking the run to a specific user, for example, when running tests from a CI platform.

To generate a token, follow these steps:

1. Log in to your Grafana Cloud account and open a stack.
2. On the main menu, click Testing & synthetics -> Performance -> Settings.
3. Under Access, click Stack token.

On this section, you can view, create, and regenerate any tokens.

By default, organizations can create a maximum of 5 tokens.

Note that you must specify the project where the test runs will be created when using a non-personal token. Refer to Cloud options to learn how to set the projectID.

Authenticate with the login command

To authenticate with an API token in the CLI, enter the following command:

Bash Copy

k6 cloud login --token $TOKEN

You can also provide a default stack to use, passing either a full URL (for example, https://my-team.grafana.net) or just a slug (for example, my-team):

Bash Copy

k6 cloud login --token <YOUR_API_TOKEN> --stack <YOUR_STACK_SLUG>

k6 cloud login stores your API token and your stack information in a local configuration file to authenticate with when running cloud commands. Unless your token changes or you run tests on multiple cloud accounts, you need to run k6 login only once.

Authenticate with an environment variable

You can also authenticate with your Grafana Cloud k6 authentication token via environment variables. Make sure you have set the K6_CLOUD_TOKEN as your authentication token, and k6 picks it up when running.

Bash Copy

## run a cloud test
K6_CLOUD_TOKEN=$TOKEN k6 cloud run script.js

## run locally and stream to the cloud
K6_CLOUD_TOKEN=$TOKEN k6 cloud run --local-execution script.js

You can also use an environment variable to set the stack you want to use, using your stack ID.

Bash Copy

## run a cloud test
K6_CLOUD_TOKEN=$TOKEN K6_CLOUD_STACK_ID=<YOUR_STACK_ID> k6 cloud run script.js

## run locally and stream to the cloud
K6_CLOUD_TOKEN=$TOKEN K6_CLOUD_STACK_ID=<YOUR_STACK_ID> k6 cloud run --local-execution script.js

To get your stack ID, follow these steps:

1. Log in to your Grafana Cloud account and open a stack.
2. On the main menu, click Testing & synthetics -> Performance -> Settings.
3. Under Access, click Stack ID.

Authenticate with a configuration file

You can also directly add your authentication token to a configuration file:

• On Linux:

  Bash Copy

  ${HOME}/.config/k6/config.json

• On Mac

  Bash Copy

  ${HOME}/Library/Application Support/k6/config.json

• On Windows

  Bash Copy

  C:\Users\<User>\AppData\Roaming\k6\config.json

Or, set the configuration path with the -c/--config PATH/TO/CONFIG_FILE CLI flag.

After your token has been added to the configuration file, it should look something like this:

JSON Copy

{
  "collectors": {
    "cloud": {
      "stackID": 12345,
      "stackURL": "https://stack-slug.grafana.net",
      "defaultProjectID": 123,
      "token": "YOUR_API_AUTH_TOKEN"
    }
  }
}

Authenticate in a Docker container

If you’re running k6 in a Docker container, the -c/--config CLI flag is the recommended approach. This ensures that the k6 configuration file where the API authentication information is stored is persisted via a Docker volume to the host machine.

Bash Copy

docker run --rm -i -v /path/on-host:/path/in-container/ grafana/k6 \
login cloud -c /path/in-container/config.json