# Agents (https://projects.piyushgambhir.com/grafana-cli/docs/agents)

Grafana CLI exposes global controls intended for scripts and coding agents.

## The output contract [#the-output-contract]

- Use `-o json` when the result will be parsed.
- Use `--quiet` to suppress informational output where a command supports it.
- Prefer stable UIDs for dashboards, folders, datasources, and alerting resources.
- Inspect first, then mutate with an explicit resource ID or UID.

## Safety flags [#safety-flags]

| Flag | Effect |
|---|---|
| `--read-only` | Blocks commands annotated as mutating, including create, update, delete, restore, switch, and reload operations |
| `--no-input` | Disables interactive prompts; commands fail instead of waiting for input |
| `--quiet` | Suppresses informational output |
| `--verbose` | Enables verbose HTTP logging for diagnostics |

```bash
# Safe, non-interactive reads for an agent
grafana dashboard list --read-only --no-input --quiet -o json
grafana alert rule list --read-only --no-input --quiet -o json
```

`GRAFANA_NO_INPUT=1`, `GRAFANA_QUIET=1`, and `GRAFANA_VERBOSE=1` provide the
same non-interactive, quiet, and verbose controls through the environment.

The once-a-day "new version" notice is printed on stderr only when stderr is a
terminal, so it never appears in agent or CI output. `GRAFANA_NO_UPDATE_NOTIFIER=1`
(or `NO_UPDATE_NOTIFIER=1`) turns it off everywhere. To update the CLI itself
without a prompt, run `grafana update --yes`.

<Callout type="warn">
  `--no-input` does not approve destructive actions. A delete or reset command
  still needs its real `--confirm` flag; `--read-only` blocks the operation even
  when confirmation is present.
</Callout>

## Connection via environment [#connection-via-environment]

Agents do not need to run the interactive login flow:

```bash
export GRAFANA_URL=https://grafana.example.com
export GRAFANA_TOKEN=glsa_xxxxxxxxxxxxxxxxxxxx
grafana user current --read-only --no-input -o json
```

## Agent references [#agent-references]

- [`docs/llms.txt`](https://github.com/piyush-gambhir/grafana-cli/blob/main/docs/llms.txt): the full command manual
- [`llms.txt`](https://projects.piyushgambhir.com/grafana-cli/llms.txt) indexes these docs, and
  [`llms-full.txt`](https://projects.piyushgambhir.com/grafana-cli/llms-full.txt) contains all of them in one file
- [Claude Code skill](https://github.com/piyush-gambhir/grafana-cli/blob/main/grafana/SKILL.md)


# Authentication (https://projects.piyushgambhir.com/grafana-cli/docs/authentication)

Grafana CLI supports bearer tokens and basic authentication. Configuration is
resolved in this order: **CLI flags > environment variables > config profile >
defaults**.

## Methods [#methods]

| Method | Credentials | Best for |
|---|---|---|
| Token | Grafana service account token or compatible API token | Grafana Cloud, self-hosted instances, CI, and automation |
| Basic auth | Grafana username and password | Local or self-hosted instances with built-in basic auth enabled |

<Callout type="info">
  Service account tokens are the recommended option. They are not tied to a
  person's login and can be assigned the Grafana role needed by the workflow.
</Callout>

## Logging in [#logging-in]

`grafana login` prompts for the Grafana URL, `token` or `basic`, the matching
credential, and a profile name. It tests the connection before saving the
profile.

```bash
grafana login
```

The config file is `~/.config/grafana-cli/config.yaml`, or
`$XDG_CONFIG_HOME/grafana-cli/config.yaml` when `XDG_CONFIG_HOME` is set.

## Environment variables [#environment-variables]

For non-interactive use, no login step is required:

```bash
export GRAFANA_URL=https://grafana.example.com
export GRAFANA_TOKEN=glsa_xxxxxxxxxxxxxxxxxxxx
grafana user current -o json
```

Basic auth uses `GRAFANA_USERNAME` and `GRAFANA_PASSWORD` instead of
`GRAFANA_TOKEN`. Set `GRAFANA_ORG_ID` to send requests in a specific organization.

## One-off flags [#one-off-flags]

Every command accepts connection overrides:

```bash
grafana dashboard list \
  --url https://grafana.example.com \
  --token "$GRAFANA_TOKEN" \
  --org-id 2

grafana dashboard list \
  --url http://localhost:3000 \
  --username admin \
  --password admin
```

## Named profiles [#named-profiles]

```bash
grafana login
grafana config list-profiles
grafana config use-profile production
grafana dashboard list --profile staging
```

Use `--profile <name>` for one command without changing the active profile.


# Access & automation (https://projects.piyushgambhir.com/grafana-cli/docs/commands/access)

## Users and organizations [#users-and-organizations]

```bash
grafana user current -o json
grafana user lookup admin@example.com -o json
grafana user list --all -o json

grafana org current -o json
grafana org list --page 1 --limit 50 -o json
grafana org user list 1 --role Admin --query "ops" -o json
```

Most server-wide user and organization operations require Grafana server-admin
permissions. `grafana org switch <org-id>` changes the authenticated user's active
organization.

## Teams [#teams]

```bash
grafana team list --query "platform" -o json
grafana team get <team-id> -o json
grafana team member list <team-id> -o json
grafana team member add <team-id> <user-id>
grafana team preferences get <team-id> -o json
```

## Service accounts and tokens [#service-accounts-and-tokens]

```bash
grafana service-account list --query "ci" -o json
grafana service-account create -f service-account.json -o json
grafana service-account token list <service-account-id> -o json
grafana service-account token create <service-account-id> -f token.json -o json
grafana service-account token delete <service-account-id> <token-id> --confirm
```

<Callout type="warn">
  A newly created service account token key is shown only once. Capture the
  structured creation result immediately and store the key in a secret manager.
</Callout>


# Administration & utilities (https://projects.piyushgambhir.com/grafana-cli/docs/commands/administration)

## Server administration [#server-administration]

```bash
grafana admin settings -o json
grafana admin stats -o json
grafana admin reload dashboards
grafana admin reload alerting
```

`admin reload` accepts `dashboards`, `datasources`, `plugins`, `access-control`,
or `alerting` and requires the matching Grafana administrative permissions.

## Snapshots and playlists [#snapshots-and-playlists]

```bash
grafana snapshot list --limit 10 -o json
grafana snapshot get <snapshot-key> -o json
grafana snapshot create -f snapshot.json

grafana playlist list --query "operations" --limit 10 -o json
grafana playlist get <playlist-uid> -o json
grafana playlist create -f playlist.json
```

## Preferences and configuration [#preferences-and-configuration]

```bash
grafana preferences get -o json
grafana preferences update -f preferences.yaml

grafana config view
grafana config list-profiles
grafana config use-profile staging
grafana config set defaults.output json
```

## CLI maintenance [#cli-maintenance]

```bash
grafana version
grafana update --check
grafana completion zsh
```

Running `grafana update` without `--check` asks `Update now? [Y/n]` before
replacing the current binary on macOS, Linux, or Windows. Pass `--yes` to skip
the prompt; with `--no-input` or without a terminal, `--yes` is required.
`grafana update --check -o json` reports `current_version`, `latest_version`,
`update_available`, `release_url`, and `install_method`. `--read-only` blocks
installing but not `--check`. See
[Updating](https://projects.piyushgambhir.com/grafana-cli/docs/installation#updating)
for the update notice and how to turn it off.


# Alerting & events (https://projects.piyushgambhir.com/grafana-cli/docs/commands/alerting)

## Alert rules [#alert-rules]

```bash
grafana alert rule list --folder <folder-uid> --group "High CPU" -o json
grafana alert rule get <rule-uid> -o json
grafana alert rule create -f rule.json
grafana alert rule update <rule-uid> -f updated-rule.yaml
grafana alert rule delete <rule-uid> --confirm
```

## Notification routing [#notification-routing]

```bash
grafana alert contact-point list -o json
grafana alert contact-point create -f contact-point.json

grafana alert policy get -o json
grafana alert policy update -f policy.json
grafana alert policy reset --confirm
```

<Callout type="warn">
  `alert policy update` replaces the entire policy tree. Read the current tree
  with `grafana alert policy get -o json` before updating it.
</Callout>

## Silences, mute timings, and templates [#silences-mute-timings-and-templates]

```bash
grafana alert silence list -o json
grafana alert silence create -f silence.json
grafana alert silence delete <silence-id> --confirm

grafana alert mute-timing list -o json
grafana alert mute-timing get "weekends" -o json

grafana alert template list -o json
grafana alert template update "on-call" -f template.json
```

## Annotations [#annotations]

```bash
grafana annotation list --tags deploy,production --limit 100 -o json
grafana annotation list --from 2026-07-01T00:00:00Z --to 2026-07-02T00:00:00Z -o json
grafana annotation create -f annotation.json
grafana annotation tags --tag deploy -o json
```

Annotation time filters accept RFC3339, Unix seconds, epoch milliseconds, or
epoch nanoseconds.


# Dashboards & data (https://projects.piyushgambhir.com/grafana-cli/docs/commands/dashboards-data)

## Dashboards [#dashboards]

```bash
# Search and inspect
grafana dashboard list --query "production" --tag monitoring -o json
grafana dashboard get <dashboard-uid> -o json

# Back up and restore dashboard definitions
grafana dashboard export <dashboard-uid> --output-file dashboard.json
grafana dashboard import -f dashboard.json --folder <folder-uid> --overwrite

# Inspect and restore version history
grafana dashboard versions <dashboard-uid> --limit 10
grafana dashboard restore <dashboard-uid> 3
```

Dashboard `create`, `update`, and `import` read JSON or YAML with `-f/--file`.
Use `dashboard permissions get|update` for dashboard access control.

## Folders and reusable elements [#folders-and-reusable-elements]

```bash
grafana folder list --page 1 --limit 50 -o json
grafana folder permissions get <folder-uid> -o json
grafana library-element list --kind 1 --search "CPU" -o json
grafana library-element connections <element-uid> -o json
```

Library element kind `1` selects panels and kind `2` selects variables.

## Datasources and proxy queries [#datasources-and-proxy-queries]

```bash
grafana datasource list --type prometheus --name "prod" -o json
grafana datasource get <datasource-uid> -o json

# Prometheus instant query
grafana datasource query <prometheus-uid> --expr 'up' --query-type instant -o json

# Loki range query over the last 30 minutes
grafana datasource query <loki-uid> --expr '{app="api"} |= "error"' --last 30m --limit 100 -o json
```

`datasource query` supports Loki and Prometheus. Use `--from` and `--to` for
RFC3339 or Unix-epoch bounds, `--step` for Prometheus range resolution, and
`--direction` for Loki ordering.

## Correlations [#correlations]

```bash
grafana correlation list -o json
grafana correlation get <source-uid> <correlation-uid> -o json
grafana correlation create <source-uid> -f correlation.json
```


# Overview (https://projects.piyushgambhir.com/grafana-cli/docs/commands)

Every command supports `-h`/`--help`. The global `-o/--output` flag accepts
`table`, `json`, or `yaml`.

## Connection check [#connection-check]

```bash
grafana user current -o json
grafana org current -o json
```

## Groups [#groups]

<Cards>
  <Card title="Dashboards & data" href="https://projects.piyushgambhir.com/grafana-cli/docs/commands/dashboards-data" description="Dashboards, folders, datasources, queries, library elements, and correlations." />
  <Card title="Alerting & events" href="https://projects.piyushgambhir.com/grafana-cli/docs/commands/alerting" description="Rules, contact points, policies, silences, mute timings, templates, and annotations." />
  <Card title="Access & automation" href="https://projects.piyushgambhir.com/grafana-cli/docs/commands/access" description="Organizations, users, teams, service accounts, and tokens." />
  <Card title="Administration & utilities" href="https://projects.piyushgambhir.com/grafana-cli/docs/commands/administration" description="Server admin, snapshots, playlists, preferences, config, and updates." />
</Cards>

<Callout type="info">
  This is a curated tour. The full reference is the CLI's own help output and the
  [`docs/llms.txt`](https://github.com/piyush-gambhir/grafana-cli/blob/main/docs/llms.txt) manual in the repository.
</Callout>


# Compatibility (https://projects.piyushgambhir.com/grafana-cli/docs/compatibility)

Checked 2026-09-06. These are documentation and local-test baselines, not certification against every server deployment.

## Build requirements [#build-requirements]

- Go 1.27 or later; this checkout selects Go 1.27.2 using `toolchain` in `cli-go/go.mod`.
- Go 1.27 builds for macOS require macOS 13 or later. See the [Go 1.27 release notes](https://go.dev/doc/go1.27).
- Docs: Node.js 24.21.0 and pnpm 12.11.2. Install with `pnpm install --frozen-lockfile` in `web/`.
- YAML uses the maintained [YAML organization v3 implementation](https://github.com/yaml/go-yaml), preserving the v3 configuration API.

## Upstream API baseline [#upstream-api-baseline]

API reference baseline: [Grafana 13.2 HTTP API](https://grafana.com/docs/grafana/v13.2/developer-resources/api-reference/http-api/). Upstream release checked: [13.2.1](https://github.com/grafana/grafana/releases/tag/v13.2.1).

This CLI currently uses Grafana's legacy `/api` endpoints. Grafana documents these as deprecated in favor of the versioned `/apis` resource APIs. Updating the Go dependencies does not migrate the wire protocol. Dashboard, folder, and other legacy commands require those routes to remain available on your deployment. Full migration to `/apis` requires response adapters and integration testing; this checkout does not claim that migration is complete.

## Maintaining this baseline [#maintaining-this-baseline]

Dependabot is configured to propose weekly Go, npm, and GitHub Actions updates. Review migrations before merging; CI verifies the Go tests, race checks, security/static analysis, command documentation, and docs build.

Run `go list -m -u all` from `cli-go/` and `pnpm outdated` from `web/` to check newer releases. Commit `go.mod` with `go.sum`, and `package.json` with `pnpm-lock.yaml`. Keep `fumadocs-core` and the `fumadocs-ui` alias to `@fumadocs/base-ui` on matching versions.

The website's static search uses Fumadocs' default search engine. After building, run `pnpm test:search` to verify that the exported index can be loaded and queried by the installed client.


# Introduction (https://projects.piyushgambhir.com/grafana-cli/docs)

**Grafana CLI** is a command-line interface for managing Grafana instances over
the HTTP API. Search and move dashboards, query datasources, configure unified
alerting, and administer organizations, users, teams, and service accounts.

It is designed for human operators, scripts, and coding agents. The global
`-o/--output` flag supports `table`, `json`, and `yaml`, while `--read-only` and
`--no-input` make automated exploration safer.

<Callout type="info">
  The full command manual for agents and LLMs is
  [`docs/llms.txt`](https://github.com/piyush-gambhir/grafana-cli/blob/main/docs/llms.txt) in the repository.
  This site's [`llms.txt`](https://projects.piyushgambhir.com/grafana-cli/llms.txt) indexes these docs, and
  [`llms-full.txt`](https://projects.piyushgambhir.com/grafana-cli/llms-full.txt) contains all of them in one file.
</Callout>

## Features [#features]

- **Dashboards:** list, inspect, create, update, delete, import, export, restore,
  and manage dashboard or folder permissions.
- **Datasources:** manage datasource definitions and query Loki or Prometheus
  through Grafana's datasource proxy.
- **Unified alerting:** rules, contact points, notification policies, mute
  timings, notification templates, and silences.
- **Access management:** organizations, users, teams, service accounts, and
  service account tokens.
- **More Grafana resources:** annotations, snapshots, playlists, library
  elements, correlations, preferences, and server administration.
- **Automation controls:** named profiles, environment configuration,
  `-o json|yaml`, `--read-only`, `--no-input`, and `--quiet`.

## Next steps [#next-steps]

<Cards>
  <Card title="Installation" href="https://projects.piyushgambhir.com/grafana-cli/docs/installation" description="Install the prebuilt binary or build from source." />
  <Card title="Authentication" href="https://projects.piyushgambhir.com/grafana-cli/docs/authentication" description="Connect with a token or basic auth and manage named profiles." />
  <Card title="Quick start" href="https://projects.piyushgambhir.com/grafana-cli/docs/quickstart" description="Connect and inspect your first Grafana resources." />
  <Card title="Agents" href="https://projects.piyushgambhir.com/grafana-cli/docs/agents" description="Structured output, safety flags, and non-interactive operation." />
</Cards>

<Callout type="info">
  **Independent project.** Not affiliated with, endorsed by, or sponsored by Grafana Labs.
  All product names, logos, and trademarks are the property of their respective
  owners and are used for identification purposes only.
</Callout>


# Installation (https://projects.piyushgambhir.com/grafana-cli/docs/installation)

## Install script (recommended) [#install-script-recommended]

Installs the latest prebuilt binary for your OS/arch. No Go toolchain is required:

```bash
curl -sSfL https://raw.githubusercontent.com/piyush-gambhir/grafana-cli/main/install.sh | sh
```

Pin a version or change the install directory:

```bash
curl -sSfL https://raw.githubusercontent.com/piyush-gambhir/grafana-cli/main/install.sh | VERSION=0.2.7 sh
curl -sSfL https://raw.githubusercontent.com/piyush-gambhir/grafana-cli/main/install.sh | INSTALL_DIR=~/.local/bin sh
```

The script installs to `/usr/local/bin` by default and asks for elevated
permissions when that directory is not writable.

## Download a release manually [#download-a-release-manually]

Prebuilt archives are attached to each
[GitHub Release](https://github.com/piyush-gambhir/grafana-cli/releases). Download
the archive for your OS and architecture, extract it, and put `grafana` on your
`PATH`:

```bash
# example (macOS arm64): adjust the asset name for your platform
curl -sSfL https://github.com/piyush-gambhir/grafana-cli/releases/latest/download/grafana-cli_darwin_arm64.tar.gz | tar xz
sudo mv grafana /usr/local/bin/
```

The install script expects assets named `grafana-cli_<os>_<arch>.tar.gz`, where
`<os>` is `darwin` or `linux` and `<arch>` is `amd64` or `arm64`.

Windows builds ship as `grafana-cli_windows_amd64.zip` containing `grafana.exe`.
The install script does not support Windows: extract `grafana.exe` from the
`.zip` and put it on your `PATH`. After that, `grafana update` keeps it current.

## Build from source [#build-from-source]

Building locally requires Go:

```bash
git clone https://github.com/piyush-gambhir/grafana-cli.git
cd grafana-cli/cli-go
make install
```

The binary is `grafana`. `make install` writes it to `go env GOBIN`, or to
`$(go env GOPATH)/bin` when GOBIN is unset.

## Updating [#updating]

```bash
grafana update                   # show v<current> -> v<latest>, ask "Update now? [Y/n]", install
grafana update --yes             # install without the prompt
grafana update --check           # report current and latest versions
grafana update --check -o json   # the same, as JSON
```

`grafana update` works on macOS, Linux, and Windows. It downloads the release
archive for your platform, verifies its SHA-256 against the release's
`checksums.txt`, and replaces the running binary. On Windows the old
`grafana.exe` is renamed to `grafana.exe.old` and deleted on a later start. If
the binary's directory is not writable, re-run with `sudo` or reinstall with the
install script into a writable directory; the old binary keeps working.

A `grafana` built from source into a Go bin directory (`$GOBIN`, `$GOPATH/bin`,
or `~/go/bin`) is not replaced. Update it with `git pull && make install` in
your `grafana-cli/cli-go` checkout.

### Update notice [#update-notice]

When a newer release exists, `grafana` prints a notice on stderr after the
command's output, at most once a day per version:

```text
A new version of grafana is available: v0.2.9 -> v0.2.10
Update with: grafana update
Release notes: https://github.com/piyush-gambhir/grafana-cli/releases/tag/v0.2.10
```

The release check runs at most once a day and only when stderr is a terminal,
so scripts, CI, and coding agents never see it. To turn it off, set
`GRAFANA_NO_UPDATE_NOTIFIER=1` or `NO_UPDATE_NOTIFIER=1`. It is also skipped
when `CI` is set and with `--quiet` (or `GRAFANA_QUIET=1`).

## Verify [#verify]

```bash
grafana version
```


# Output formats (https://projects.piyushgambhir.com/grafana-cli/docs/output-formats)

The global `-o/--output` flag accepts three formats:

- `-o table`: default, human-readable
- `-o json`: structured JSON for programs and agents
- `-o yaml`: structured YAML

<Callout type="info">
  **Agents: prefer `-o json`.** Add `--quiet` when a command may also emit
  informational messages that are not needed by the caller.
</Callout>

```bash
grafana user current -o json | jq -r .login
grafana dashboard list -o json | jq -r '.[].uid'
grafana datasource list -o yaml
```

## Set a default [#set-a-default]

Save a preferred output format in the CLI config:

```bash
grafana config set defaults.output json
```

A per-command `-o` flag overrides that default.

## File input and exports [#file-input-and-exports]

Create and update commands commonly use `-f/--file` with JSON, YAML, or `-` for
stdin. This is independent of the selected output format:

```bash
grafana folder create -f folder.yaml -o json
echo '{"title":"Operations"}' | grafana folder create -f - -o json
```

`grafana dashboard export <uid>` is a dedicated JSON export command. Use
`--output-file <path>` to write the dashboard model directly to a file.


# Quick start (https://projects.piyushgambhir.com/grafana-cli/docs/quickstart)

## 1. Authenticate [#1-authenticate]

A service account token is the recommended setup:

```bash
grafana login
```

Or non-interactively for CI/agents:

```bash
export GRAFANA_URL=https://grafana.example.com
export GRAFANA_TOKEN=glsa_xxxxxxxxxxxxxxxxxxxx
```

## 2. Confirm connectivity [#2-confirm-connectivity]

```bash
grafana user current -o json
grafana org current
```

## 3. Inspect resources [#3-inspect-resources]

```bash
# Find dashboards by title
grafana dashboard list --query "production" -o json

# Inspect a dashboard and its version history
grafana dashboard get <dashboard-uid> -o json
grafana dashboard versions <dashboard-uid>

# List datasources and alert rules
grafana datasource list --type prometheus -o json
grafana alert rule list --folder <folder-uid> -o json
```

## Discovering commands [#discovering-commands]

Every command has `-h`/`--help`:

```bash
grafana --help
grafana dashboard --help
grafana datasource query --help
```

<Cards>
  <Card title="Output formats" href="https://projects.piyushgambhir.com/grafana-cli/docs/output-formats" description="table, JSON, YAML, and default output selection." />
  <Card title="Commands" href="https://projects.piyushgambhir.com/grafana-cli/docs/commands" description="A curated command tour grouped by Grafana resource area." />
</Cards>