---
title: "Set up Grafana CLI | Grafana documentation"
description: "Configuration guide for Grafana CLI, a command line tool for managing Grafana resources as code."
---

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

# Set up Grafana CLI

You can configure Grafana CLI in two ways: using environment variables or through a configuration file.

- **Environment variables** are ideal for CI environments and support a single context. A full list of supported environment variables is available in the [reference documentation](https://github.com/grafana/grafanactl/blob/main/docs/reference/environment-variables/index.md#environment-variables-reference).
- **Configuration files** can manage multiple contexts, making it easier to switch between different Grafana instances.

> Note
> 
> Configuration items may change depending on your set-up. For example, use `org-id` for Grafana on-prem, but use `stack-id` for Grafana Cloud.

## Configure Grafana CLI with environment variables

Grafana CLI communicates with Grafana via its REST API, which requires authentication credentials.

At a minimum, set the URL of your Grafana instance and the organization ID:

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

```bash
GRAFANA_SERVER='http://localhost:3000' GRAFANA_ORG_ID='1' grafanactl config check
```

Depending on your authentication method, you may also need to set:

- A [token](https://github.com/grafana/grafanactl/blob/main/docs/reference/environment-variables/index.md#grafana_token) for a [Grafana service account](/docs/grafana/latest/administration/service-accounts/) (recommended)
- A [username](https://github.com/grafana/grafanactl/blob/main/docs/reference/environment-variables/index.md#grafana_user) and [password](https://github.com/grafana/grafanactl/blob/main/docs/reference/environment-variables/index.md#grafana_password) for basic authentication

To persist your configuration, consider [creating a context](#use-configuration-contexts).

### Use configuration contexts

Contexts allow you to easily switch between multiple Grafana instances.

By default, the CLI uses a context named `default`. To configure it use:

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

```bash
grafanactl config set contexts.default.grafana.server http://localhost:3000
grafanactl config set contexts.default.grafana.org-id 1

# Authenticate with a service account token
grafanactl config set contexts.default.grafana.token service-account-token

# Or use basic authentication
grafanactl config set contexts.default.grafana.user admin
grafanactl config set contexts.default.grafana.password admin
```

You can define additional contexts in the same way:

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

```bash
grafanactl config set contexts.staging.grafana.server https://staging.grafana.example
grafanactl config set contexts.staging.grafana.org-id 1
```

> Note
> 
> In these examples, `default` and `staging` are the names of the contexts.

## Configure Grafana CLI with configuration files

Grafana CLI stores its configuration in a YAML file. The CLI determines the configuration file location in the following order:

1. If the `--config` flag is provided, the specified file is used.
2. If `$XDG_CONFIG_HOME` is set: `$XDG_CONFIG_HOME/grafanactl/config.yaml`
3. If `$HOME` is set: `$HOME/.config/grafanactl/config.yaml`
4. If `$XDG_CONFIG_DIRS` is set: `$XDG_CONFIG_DIRS/grafanactl/config.yaml`

> Note
> 
> Use `grafanactl config check` to display the configuration file currently in use.

## Useful commands

Check the current configuration:

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

```bash
grafanactl config check
```

> Note
> 
> This command is useful to troubleshoot your configuration.

List all available contexts:

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

```bash
grafanactl config list-contexts
```

Switch to a specific context:

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

```bash
grafanactl config use-context staging
```

View the full configuration:

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

```bash
grafanactl config view
```