Grafana CLI

Grafana CLI cheatsheet — install/remove plugins, reset admin password, upgrade. grafana-cli plugins install grafana-piechart-panel, grafana-cli admin reset-admin-password.

5 min read

What it is

The Grafana CLI is a command-line interface for managing Grafana instances, primarily used for installing and managing plugins and provisioning configurations.

Installation

Linux

Download the pre-compiled binary from the Grafana releases page.

wget https://dl.grafana.com/oss/release/grafana-10.0.0.linux-amd64.tar.gz
tar -zxvf grafana-10.0.0.linux-amd64.tar.gz
sudo mv grafana-10.0.0 /usr/local/grafana
sudo ln -s /usr/local/grafana/bin/grafana-cli /usr/local/bin/grafana-cli

macOS

Download the pre-compiled binary from the Grafana releases page.

wget https://dl.grafana.com/oss/release/grafana-10.0.0.darwin-amd64.tar.gz
tar -zxvf grafana-10.0.0.darwin-amd64.tar.gz
sudo mv grafana-10.0.0 /usr/local/grafana
sudo ln -s /usr/local/grafana/bin/grafana-cli /usr/local/bin/grafana-cli

Windows

Download the pre-compiled binary from the Grafana releases page. Extract the archive and add the bin directory to your system’s PATH.

Expand-Archive grafana-10.0.0.windows-amd64.zip -DestinationPath C:\grafana
# Add C:\grafana\bin to your system's PATH environment variable

Core Concepts

  • Plugins: Extensions that add functionality to Grafana, such as data sources (e.g., Prometheus, InfluxDB), panels (e.g., Graph, Stat), and app plugins.
  • Provisioning: The process of configuring Grafana settings, data sources, dashboards, and users using configuration files, rather than through the web UI. This is crucial for automated deployments and managing Grafana instances consistently.

Commands / Usage

Plugin Management

Installing a Plugin

grafana-cli plugins install prometheus

Installs the Prometheus data source plugin.

grafana-cli plugins install grafana-worldmap-panel

Installs the Worldmap panel plugin.

Listing Installed Plugins

grafana-cli plugins list

Lists all installed plugins and their versions.

Updating a Plugin

grafana-cli plugins update prometheus

Updates the Prometheus plugin to the latest version.

grafana-cli plugins update-all

Updates all installed plugins to their latest versions.

Uninstalling a Plugin

grafana-cli plugins uninstall prometheus

Uninstalls the Prometheus plugin.

Listing Available Plugins (for searching)

grafana-cli plugins list-remote

Lists plugins available for installation from the Grafana plugin catalog.

Provisioning

Provisioning Data Sources

This command is typically used in conjunction with configuration files. The CLI itself doesn’t directly "provision" in the sense of creating a data source via a single command, but it ensures Grafana can read provisioning files. You would place your data source configuration files in the designated provisioning/datasources directory within your Grafana configuration.

Example datasources/datasource.yml in conf/provisioning/:

apiVersion: 1

datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://localhost:9090
    isDefault: true

After placing this file, Grafana will pick it up on startup.

Provisioning Dashboards

Similar to data sources, dashboards are provisioned via configuration files placed in the provisioning/dashboards directory.

Example dashboards/dashboard.yml in conf/provisioning/:

apiVersion: 1

providers:
  - name: 'Default'
    orgId: 1
    folder: ''
    type: file
    disableDeletion: false
    editable: true
    options:
      folder: dashboards/default

And then place your dashboard JSON files in conf/provisioning/dashboards/default/.

Provisioning Notifiers (Alerting)

Configuration files for alert notifiers go into provisioning/notifiers.

Provisioning Configuration Files

The grafana-cli command itself doesn’t directly apply provisioning files; Grafana reads them on startup or when a reload is triggered. The CLI is more for managing plugins that might be used by provisioned resources, or for performing actions related to provisioning in automated contexts.

Server Management

Restarting Grafana

grafana-cli admin restart grafana

Restarts the Grafana server process. This is often useful after significant configuration changes or plugin installations that require a restart.

Server Restart requires sudo on Linux/macOS if Grafana is run as a service.

Configuration

Viewing Grafana Configuration

grafana-cli admin settings --json

Outputs the current Grafana configuration in JSON format.

User Management (Limited CLI Access)

While most user management is done via the UI or API, some basic operations might be supported depending on the Grafana version and plugins. The CLI is less focused on direct user manipulation compared to plugin management or provisioning setup.

Common Patterns

Automating Plugin Installation on Server Startup

This is often done via a systemd service file or a startup script that runs grafana-cli plugins install <plugin-name> before starting the Grafana server.

Example systemd service snippet:

[Service]
ExecStartPre=/usr/local/bin/grafana-cli plugins install prometheus
ExecStart=/usr/sbin/grafana-server -config=/etc/grafana/grafana.ini

Provisioning Data Sources and Dashboards in CI/CD

  1. Define data source and dashboard YAML files.
  2. Define dashboard JSON files.
  3. Package these files with your Grafana installation or configuration management tool.
  4. Ensure Grafana reads these files from the correct conf/provisioning directory on startup. The grafana-cli is not directly involved in applying these files but ensures the environment is ready (e.g., by installing necessary plugins).

Installing a Specific Plugin Version

grafana-cli plugins install grafana-influxdb@1.5.0

Installs version 1.5.0 of the InfluxDB plugin.

Installing a Plugin from a Local Path (for custom/private plugins)

grafana-cli plugins install /path/to/my-custom-plugin --local

Installs a plugin from a local directory.

Gotchas

  • Permissions: On Linux and macOS, commands that modify Grafana’s installation directory or its configuration files (like installing plugins or restarting the server) often require sudo.
  • Grafana Restart: Many operations, especially plugin installations and provisioning file changes, require a Grafana server restart to take effect. The grafana-cli admin restart grafana command is your friend here.
  • Plugin Compatibility: Always check plugin compatibility with your Grafana version. Installing an incompatible plugin can lead to Grafana instability or failure to start.
  • Provisioning File Location: Grafana looks for provisioning files in specific directories (conf/provisioning/datasources, conf/provisioning/dashboards, etc.) relative to its configuration directory. Ensure your files are placed correctly.
  • --local Flag: When installing plugins locally, the directory specified must contain a plugin.json file and be structured like a Grafana plugin.
  • Core Plugins: Some plugins are bundled with Grafana and cannot be installed or uninstalled via the CLI as they are part of the core distribution.