Grafana CLI (grafanactl)

Grafana CLI (grafanactl) is a command-line tool used to interact with Grafana instances via their REST API. It is designed for terminal-based management, automation, and scripting.

Key capabilities include:

• Authentication: Securely authenticate with Grafana instances.
• Environment Management: Manage multiple Grafana environments (e.g., switching between staging and production).
• Administrative Tasks: Perform various administrative operations through the CLI.
• Automation: Ideal for integrating Grafana management into CI/CD pipelines.

The grafanactl CLI searches for a configuration file in a specific order of precedence. Once a file is found, no other locations are considered:

1. --config flag: If the --config <path> flag is provided, this file is used exclusively.
2. $GRAFANACTL_CONFIG environment variable: If set, this file is used exclusively.
3. $XDG_CONFIG_HOME: Uses $XDG_CONFIG_HOME/grafanactl/config.yaml (e.g., /home/user/.config/grafanactl/config.yaml).
4. $HOME: Uses $HOME/.config/grafanactl/config.yaml (e.g., /home/user/.config/grafanactl/config.yaml).
5. $XDG_CONFIG_DIRS: Uses $XDG_CONFIG_DIRS/grafanactl/config.yaml (e.g., /etc/xdg/grafanactl/config.yaml).

Grafana CLI stores configuration in a YAML file. The CLI determines the file location using the following precedence:

1. The file specified by the --config flag.
2. The path defined by $XDG_CONFIG_HOME/grafanactl/config.yaml.
3. The path defined by $HOME/.config/grafanactl/config.yaml.
4. The path defined by $XDG_CONFIG_DIRS/grafanactl/config.yaml.

You can use grafanactl config check to identify which configuration file is currently being used.

To build grafanactl from source, you must have git installed and go version 1.24 or greater. You can install the latest version directly using the go install command.

go install github.com/grafana/grafanactl/cmd/grafanactl@latest

The grafanactl tool is being deprecated in favor of a new CLI tool called gcx. To migrate your existing workflows:

1. Perform a search-and-replace of grafanactl with gcx in your scripts and commands.
2. For the specific command grafanactl resources serve, use the new equivalent: gcx dev serve.

# Migration mapping
# Old command
 grafanactl resources serve

# New command
 gcx dev serve

Use the grafanactl resources serve command to start a local server for exploring and reviewing Grafana resources.

While the resources themselves are loaded from your local disk or generated via scripts, the server uses the Grafana instance defined in your current grafanactl context to access necessary data (for example, to execute queries when previewing dashboards).

Important Note on Watch Mode: If you are using NFS or SMB protocols, file watching (--watch) may not work because these protocols often lack network-level support for file notifications via fsnotify.

# Serve resources from a directory:
grafanactl resources serve ./resources

Grafana CLI supports multiple contexts, allowing you to switch easily between different Grafana instances. By default, the CLI uses the default context.

You can define settings for a specific context using the grafanactl config set contexts.<context-name>.grafana.<key> <value> pattern.

# Configure the default context
grafanactl config set contexts.default.grafana.server http://localhost:3000
grafanactl config set contexts.default.grafana.org-id 1
grafanactl config set contexts.default.grafana.token service-account-token

# Create and configure a new context named 'staging'
grafanactl config set contexts.staging.grafana.server https://staging.grafana.example
grafanactl config set contexts.staging.grafana.org-id 1

Environment variables are best suited for CI environments as they can only describe a single context at a time. To interact with a Grafana instance via its REST API, you must provide the server URL and an organization ID.

Minimum required variables:

• GRAFANA_SERVER: The URL of the Grafana instance.
• GRAFANA_ORG_ID: The organization ID to use (required for OSS/Enterprise, skip when targeting Grafana Cloud).

Optional authentication variables:

• GRAFANA_TOKEN: Use this if using a Grafana service account (recommended).
• GRAFANA_USER and GRAFANA_PASSWORD: Use these for basic authentication.

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

The grafanactl resources edit command allows you to modify a resource (such as a dashboard) directly in your terminal using your system's default text editor. This avoids the need to manually pull, edit, and push the resource.

Workflow:

1. Run the edit command with the resource path.
2. The command opens your configured editor (defined by the EDITOR environment variable, or defaulting to vi on Linux and notepad on Windows).
3. Make your changes and save the file.
4. Close the editor. The CLI will automatically attempt to update the resource in the targeted Grafana instance.

Important Notes:

• The update will be cancelled if you close the editor without making any changes.
• The update will be cancelled if the resulting file is empty.

grafanactl resources edit dashboard/edit-me-please

You can use grafanactl resources get dashboards combined with a tool like jq to inspect dashboard metadata and identify which data source UIDs are being used in their panels. This is useful for auditing production environments to ensure dashboards are not pointing to non-production data sources.

To list dashboard UIDs and their associated data source UIDs, use the following pattern:

# Replace 'prod' with your target context
grafanactl resources get dashboards --context prod | jq '.items | map({ uid: .metadata.name, datasources: .spec.panels | map(.datasource.uid)  })'