DocumentationGrafana CloudTest applications and servicesPerformance TestingAuthor and run testsUse the CLI

Use the CLI

There are several ways you can use the Grafana k6 command-line tool (CLI) to run a k6 performance test. You can:

• Run a test on your local machine
• Run a test on Grafana Cloud k6
• Run a test locally and stream the results to the cloud
• Run a test in a specific Grafana Cloud k6 project
• Upload a test script to Grafana Cloud k6

To run tests from the CLI, the first step is to open your terminal and navigate to the directory where you created your script.

Before you begin

To run a CLI test, you’ll need:

• A machine with k6 installed.
• A test file.

To run CLI tests in Grafana Cloud k6, you’ll also need:

• A Grafana Cloud account.
• A Grafana Cloud k6 personal API token or Grafana stack API token.

Run a test on your local machine

Running tests locally is a great way to incrementally test your script as you write it. For example, you can make sure that your checks and thresholds are configured correctly before you run a test with more VUs in Grafana Cloud k6.

To run a test locally, use the k6 run command:

bash Copy

k6 run script.js

Run a test on Grafana Cloud k6

To run a cloud test from the CLI, you’ll need an API token for authenticating the k6 CLI with the Grafana Cloud k6 application.

With the CLI authentication configured, you can run cloud tests by using the k6 cloud command:

bash Copy

k6 cloud cloud_demo.js

Run a test locally and stream the results to the cloud

You can also run a test from a local machine and stream the results for storage and visualization on Grafana Cloud. A common use case for this feature is to run load tests in a CI/CD environment, or on networks that aren’t accessible from the public internet.

To run a test locally and stream the results to Grafana Cloud k6, use the k6 run --out cloud:

bash Copy

k6 run --out cloud cloud_demo.js

Run a CLI test in a specific project

By default, when you run a test from the CLI, the test runs in your default project. To create and run tests in a specific project, you can set the Project ID when running your script.

In Grafana Cloud, you can find the Project ID value below the project name on the project view:

You can pass the Project ID to k6 in two ways:

• Specify the projectID option in your script:

JavaScript Copy

export const options = {
  cloud: {
    projectID: 3479144,
  },
};

• Set the K6_CLOUD_PROJECT_ID environment variable when running your test. For example:

bash Copy

K6_CLOUD_PROJECT_ID=PROJECT_ID k6 cloud test.js

Upload a test script

You can upload a test script to Grafana Cloud k6 by using the --upload-only flag. For example:

bash Copy

k6 cloud --upload-only cloud_demo.js

That command uploads the test script to the default project, or the project ID specified in your test script configuration, without starting a new test run.

This can be useful if you want to update a test that’s running on a schedule but don’t want it to run at the same time.