---
title: "Use the CLI | Grafana Cloud documentation"
description: "Use Grafana k6 to write a script and run a performance test in your machine and in Grafana Cloud k6."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Use the CLI

There are several ways you can use the Grafana k6 command-line tool (CLI) to run a k6 performance test. In this page, you’ll learn how to use each method and how they differ from each other.

## Before you begin

To run a CLI test, you’ll need:

- A machine with [k6 installed](/docs/k6/latest/get-started/installation/).
- A test file or archive.

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

- A [Grafana Cloud account](/auth/sign-up/create-user).
- A [Grafana Cloud k6 personal API token or Grafana stack API token](/docs/grafana-cloud/testing/k6/author-run/tokens-and-cli-authentication/).

## 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](/docs/k6/latest/using-k6/checks/) and [thresholds](/docs/k6/latest/using-k6/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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
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](/docs/grafana-cloud/testing/k6/author-run/tokens-and-cli-authentication/) 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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
k6 cloud run cloud_demo.js
```

## Run a test locally and stream the results to Grafana Cloud k6

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 performance 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 cloud run --local-execution`:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
k6 cloud run --local-execution cloud_demo.js
```

## Run a test in Grafana Cloud k6 and delete sensitive data

When executing a test in Grafana Cloud k6 with the `k6 cloud run` command, the k6 CLI runs and uploads the test script to Grafana Cloud.

You can use the `deleteSensitiveData` option in your test script to have Grafana Cloud k6 delete the script and any data files after the test is executed.

To use the options, include the following snippet in your test script:

js ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```js
export const options = {
  cloud: {
    deleteSensitiveData: true,
  },
};
```

And run the test with:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
k6 cloud run cloud_demo.js
```

> Note
> 
> The deleteSensitiveData option is unavailable in default subscriptions. If you want to activate it, [contact support](mailto:support@k6.io).

## Run a test in your infrastructure with the k6 Operator

k6 Operator is a Kubernetes operator that you can use to run distributed k6 tests in your Kubernetes cluster.

A couple of reasons why you might want to do this:

- You run your application in Kubernetes and would like k6 to be executed in the same fashion as all your other infrastructure components.
- You want to run your tests within your private network for security or privacy reasons.

To set up and run a test using the k6 Operator, refer to [Set up distributed k6](/docs/k6/latest/set-up/set-up-distributed-k6/).

## Run a test in your infrastructure with the k6 Operator and stream the results to Grafana Cloud k6

Similar to how you can run a test locally using the k6 CLI and stream results to Grafana Cloud, you can also do the same with the k6 Operator. k6 Operator is a Kubernetes operator that you can use to run distributed k6 tests in your Kubernetes cluster.

A couple of reasons why you might want to do this:

- You run your application in Kubernetes and would like k6 to be executed in the same fashion as all your other infrastructure components.
- You want to run your tests within your private network for security or privacy reasons.

When using this execution method:

- You can visualize the results of the test using the Grafana Cloud UI.
- Grafana Cloud doesn’t have access to the script in the cloud, and you can’t start tests using the Grafana Cloud UI.

Refer to [Use the k6 Operator with Grafana Cloud k6](/docs/k6/latest/set-up/set-up-distributed-k6/usage/k6-operator-to-gck6/) for more details.

## Run a test locally with a Private Load Zone

Private Load Zones (PLZ) are load zones that you can host inside your network by using the k6 Operator. That means that the test execution happens in your infrastructure, but your team can view the test result data in Grafana Cloud. PLZs also appear in Grafana Cloud in the same way as any default load zone location, and you can start tests in the PLZ by using the Grafana Cloud UI or by referencing the PLZ name in your test script.

Refer to [Set up Private Load Zones](/docs/grafana-cloud/testing/k6/author-run/private-load-zone/) for more details.

## Run a CLI test in a specific project

By default, when you run a test from the CLI, k6 uses the default project of your configured default stack. 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](/docs/grafana-cloud/testing/k6/author-run/cloud-scripting-extras/cloud-options/) in your script:

JavaScript ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

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

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
K6_CLOUD_PROJECT_ID=PROJECT_ID k6 cloud run test.js
```

## Run a CLI test in a specific stack

> Note
> 
> The `stackID` option is available in k6 v1.6.0 and later. While the stack parameter is currently optional, it’s recommended to start providing stack information now. In future versions, specifying a stack will become required.

By default, when you run a test from the CLI, the test runs in your default stack. You can configure the default stack by [authenticating with the k6 CLI](/docs/grafana-cloud/testing/k6/author-run/tokens-and-cli-authentication/). To create and run tests in a specific stack, you can set the `Stack ID` when running your script.

In Grafana Cloud, you can find the `Stack ID` value in **Testing & synthetics** -> **Performance** -> **Settings**, and then under **Access** -> [**Stack ID**](/launch/a/k6-app/settings/stack-id).

You can pass the `Stack ID` to k6 in two ways:

- Specify the [`stackID` option](/docs/grafana-cloud/testing/k6/author-run/cloud-scripting-extras/cloud-options/) in your script:

JavaScript ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```javascript
export const options = {
  cloud: {
    stackID: 123456,
  },
};
```

- Set the `K6_CLOUD_STACK_ID` environment variable when running your test. For example:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
K6_CLOUD_STACK_ID=STACK_ID k6 cloud run test.js
```

## Upload a test script to Grafana Cloud k6

You can upload a test script to Grafana Cloud k6 by using the `k6 cloud upload` command. For example:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
k6 cloud upload 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](/docs/grafana-cloud/testing/k6/author-run/schedule-a-test/), but don’t want it to run at the same time.