Run cloud tests from the CLI
While the Test Builder is a nice way to learn the API and prototype tests, testers usually prefer to write scripts in their local code editor. k6 is also a command-line tool, and you can use it to write test files on your machine and execute them on Grafana Cloud k6.
In this topic, learn how to use the CLI to:
- Run a test on your local machine
- Run that same test on Grafana Cloud k6
- Run the test locally and stream it to the cloud
Before you begin
To run a CLI test, you’ll need:
- A machine with k6 installed
- A k6 token
- A test file
For your test file, you can copy the script prototyped in Build your first test.
In the directory where you want to run your test, save this as cloud_demo.js
.
To keep demo run times short, the total test duration has been modified to be only 45 seconds.
import { sleep } from 'k6';
import http from 'k6/http';
export const options = {
ext: {
loadimpact: {
distribution: {
'amazon:us:ashburn': { loadZone: 'amazon:us:ashburn', percent: 34 },
'amazon:gb:london': { loadZone: 'amazon:gb:london', percent: 33 },
'amazon:au:sydney': { loadZone: 'amazon:au:sydney', percent: 33 },
},
},
},
thresholds: {},
scenarios: {
Scenario_1: {
executor: 'ramping-vus',
gracefulStop: '30s',
stages: [
{ target: 20, duration: '15s' },
{ target: 20, duration: '15s' },
{ target: 0, duration: '15s' },
],
gracefulRampDown: '30s',
exec: 'scenario_1',
},
},
};
export function scenario_1() {
let response;
// Get homepage
response = http.get('https://test.k6.io/');
// Automatically added sleep
sleep(1);
}
Run tests
To run tests from the CLI, the first step is to open your terminal and navigate to the directory where you created your script.
After you do that, there are three different ways you can run your test.
Local execution
Running tests locally is a great way to incrementally test your script as you write it.
To run locally, use the k6 run
command:
k6 run cloud_demo.js
Cloud execution
To run a cloud test from the CLI, you’ll need a token for authenticating the k6 CLI with the Grafana Cloud k6 application.
To get a personal token in Grafana Cloud:
Log in to your Grafana Cloud account.
Go to Performance testing > Settings.
Select Copy to clipboard to copy your personal API token.
Run the following command to authenticate with the k6 CLI, replacing
K6_CLOUD_API_TOKEN
with your personal API token:bashk6 login cloud --token K6_CLOUD_API_TOKEN
Note that you only need to authenticate once with your local k6 CLI. Alternatively, other authentication options are also available.
With the CLI authentication configured, you can run cloud tests by using the k6 cloud
command:
k6 cloud cloud_demo.js
Run locally and stream 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 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
:
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 set the test run in a different project, specify the projectID
option in the k6 script:
export const options = {
ext: {
loadimpact: {
projectID: 3479144,
},
},
};
In Grafana Cloud, you can find the projectID
value below the project name on the project view:
Was this page helpful?
Related resources from Grafana Labs


