Run a performance test from the CLI

Grafana k6 is a command-line tool that you can use to write test files on your machine and execute them locally and on Grafana Cloud k6.

In this tutorial, learn how to use the k6 CLI to:

Run a test on your local machine
Run the same test on Grafana Cloud k6

Before you begin

To run a CLI test, you’ll need:

A machine with k6 installed.
A Grafana Cloud account.
A Grafana Cloud k6 personal API token or Grafana stack API token.
A test file.

For your test file, you can use the following script. In the directory where you want to run your test, save this as cloud_demo.js.

import { sleep } from 'k6';
import http from 'k6/http';

export const options = {
  cloud: {
    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, you can run your test locally or from the cloud.

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 an API 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:
bash
```
k6 cloud login --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 run command:

k6 cloud run cloud_demo.js

Next steps

This tutorial provides an overview of running tests using Grafana k6. For more details, including more options on how to run tests from the CLI behind a firewall, refer to Use the CLI.

For a next step, you can: