graf

An agent-first command-line interface for Grafana.

graf talks to a Grafana instance through a single credential and exposes its metrics, logs, traces, and resources as structured commands. It is built for AI coding agents first — JSON output by default, self-describing, no interactive prompts — and stays pleasant for humans with a --output table mode.

One Grafana service-account token reaches everything:

• Metrics — Prometheus (PromQL) through the datasource proxy
• Logs — Loki (LogQL) through the datasource proxy
• Traces — Tempo (trace by ID) through the datasource proxy
• Resources — dashboards, datasources, and alert rules via the Grafana API

Install

Homebrew:

brew install seethruhead/tap/graf

From source (requires Bun):

git clone https://github.com/SeeThruHead/graf
cd graf
bun install
bun run build        # produces ./dist/graf

Configure

graf needs a Grafana URL and a credential. Resolution order is environment variables first, then ~/.config/graf/config.json.

Environment:

export GRAFANA_URL="https://grafana.example.com"
export GRAFANA_TOKEN="glsa_xxx"            # a Grafana service-account token
# or, for instances behind basic auth:
export GRAFANA_USER="admin"
export GRAFANA_PASSWORD="..."

Config file (~/.config/graf/config.json, or point GRAF_CONFIG elsewhere):

{
  "url": "https://grafana.example.com",
  "token": "glsa_xxx"
}

Credentials are held as Redacted values internally and never appear in logs or error output.

Creating a service-account token

In Grafana: Administration → Service accounts → Add service account, give it the role you want graf to act with (Admin for full management), then Add token and copy the glsa_... value.

Usage

graf health

graf query metric 'up'
graf query metric 'rate(http_requests_total[5m])' --output table
graf query metric-range 'up' --start=now-1h --end=now --step=60
graf query logs '{container="api"} |= "error"' --limit=200 --since=2h
graf query trace 4f0e1b...

graf dashboards list
graf dashboards get <uid>

graf datasources list

graf alerts rules

Every command accepts --output, -o (json is the default; table gives a terminal-friendly view).

Agent mode

When graf detects it is running inside an AI coding agent (via environment variables such as CLAUDECODE or CURSOR), it keeps output strictly machine-readable. Agents can discover the command surface with --help on any command, and errors are returned as structured { ok: false, error, message } envelopes.

Development

bun run typecheck
bun run test          # @effect/vitest
bun run build         # single-file binary via bun build --compile

The codebase is Effect-based: a Grafana service with the HTTP client and configuration injected as layers, which keeps every unit fully testable against fake layers. See CLAUDE.md for conventions.

License

MIT © Shane Keulen