grafana-assistant-cli

grafana-assistant CLI

CLI tool for interacting with Grafana Assistant via the A2A API.

Prerequisites

The grafana-assistant binary must already be installed and available on $PATH. Do not attempt to install it automatically. If the command is not found, stop and tell the user to install it first.

Installation instructions and pre-built binaries: github.com/grafana/assistant-cli

A Docker image is also available: github.com/grafana/assistant-cli/pkgs

Configuration

Config file locations (first found wins)

1. GRAFANA_ASSISTANT_CONFIG env var (if set)
2. ./grafana-assistant.yaml (current directory, use --local flag)
3. ~/.config/grafana-assistant/config.yaml

Config file format

current-instance: prod

instances:
  localhost:
    url: http://localhost:3000
    token: glsa_abcd1234
  prod:
    url: https://mystack.grafana.net
    token: ${GRAFANA_PROD_TOKEN}  # env var expansion supported

projects:
  - name: my-app
    path: ~/projects/my-app

tunnel:
  tools:
    filesystem:
      allowed_paths: [/var/log/myapp]
      deny_paths: ["**/*.key", "**/secrets.yaml"]
    terminal:
      allowed_commands: [git, kubectl, docker]
      deny_commands: ["rm -rf"]
      passthrough_env: [AWS_PROFILE, KUBECONFIG]

Environment variables

Variable	Description
GRAFANA_URL	Grafana instance URL (overrides config)
GRAFANA_SA_TOKEN	Service account token (overrides config)
GRAFANA_ASSISTANT_CONFIG	Override config file path

Credential resolution priority

1. --url and --token flags
2. GRAFANA_URL and GRAFANA_SA_TOKEN env vars
3. --instance <name> flag
4. current-instance from config file

Quick setup

grafana-assistant config set-instance mystack --url https://mystack.grafana.net
grafana-assistant config use-instance mystack
grafana-assistant auth                    # opens browser for PKCE auth
grafana-assistant chat                    # start interactive chat

The Assistant CLI User role is required for browser auth. Users with Editor role or above get this automatically. For custom roles, include the grafana-assistant-app.tokens:access permission.

Managing instances

grafana-assistant config set-instance <name> -u <url> -t <token>
grafana-assistant config use-instance <name>
grafana-assistant config current
grafana-assistant config list
grafana-assistant config delete-instance <name>
grafana-assistant config path

Token supports env var references: -t '${MY_TOKEN_VAR}'

Managing projects

Projects are named directories the assistant can access via the tunnel.

grafana-assistant config add-project <name> <path>
grafana-assistant config list-projects
grafana-assistant config remove-project <name>

Prompting (non-interactive, primary mode for agent use)

grafana-assistant prompt sends a single message and returns the response. This is the primary command to use from Cursor.

grafana-assistant prompt "your message here"
grafana-assistant prompt "your message" --json            # JSON output with contextId
grafana-assistant prompt "your message" -c <context-id>   # continue a conversation
grafana-assistant prompt "your message" -a <agent-id>     # specific agent
grafana-assistant prompt "your message" --wait=false      # fire and forget

Keeping conversation context

Each prompt starts a new, independent conversation by default. To thread follow-up messages into the same conversation (so the assistant remembers prior context), you must:

1. Use --json on the first prompt to capture the contextId
2. Pass -c <contextId> on all subsequent prompts

# First message — capture contextId
grafana-assistant prompt "Show me metrics for the assistant service in ops-eu-south-0" --json
# Response: { "contextId": "62a8823a-...", "status": "completed", "response": "..." }

# Follow-ups — pass contextId
grafana-assistant prompt "Now break those down by handler label" -c 62a8823a-... --json

Caveats:

• Without -c, every prompt is a brand new conversation with no memory.
• If context threading fails (e.g. "context was not created by CLI"), include relevant prior findings directly in the prompt text instead.
• For long multi-step investigations, including key findings inline is often more reliable than depending on context threading.

JSON output format

{
  "taskId": "a2a-xxx",
  "contextId": "uuid",
  "agentId": "grafana_assistant_cli",
  "status": "completed",
  "response": "The assistant's full text response..."
}

Possible status values: completed, failed, timeout, canceled, unknown.

Chatting (interactive)

Opens a full-screen TUI. Context is maintained automatically within the session.

grafana-assistant chat
grafana-assistant chat -i <instance>          # specific instance
grafana-assistant chat -a <agent-id>          # specific agent
grafana-assistant chat --continue             # resume previous session
grafana-assistant chat -c <context-id>        # resume specific conversation
grafana-assistant chat --timeout 600          # custom timeout (default: 300s)

In-chat commands: /clear or /new (new conversation), /exit or /quit or Ctrl+C (quit), /help.

Listing agents

grafana-assistant agents
grafana-assistant agents --json
grafana-assistant agents -i <instance>

Generating AGENTS.md

Generate an AGENTS.md file for AI coding agents:

grafana-assistant agents-md <target-directory>
grafana-assistant agents-md <target-directory> --dry-run    # preview to stdout
grafana-assistant agents-md <target-directory> -o AGENTS.md  # custom output name
grafana-assistant agents-md <target-directory> --force        # overwrite existing
grafana-assistant agents-md <target-directory> --non-interactive  # skip prompts

Assistant Tunnel

The tunnel allows Grafana Assistant to execute tools on your local machine.

grafana-assistant tunnel auth                    # authenticate (opens browser)
grafana-assistant tunnel connect                 # foreground connection (filesystem enabled by default)
grafana-assistant tunnel connect --all           # all authenticated instances
grafana-assistant tunnel connect --terminal      # enable terminal tool

Daemon management

grafana-assistant tunnel daemon install          # install as system service
grafana-assistant tunnel daemon install --all    # connect all instances
grafana-assistant tunnel daemon install --start-on-login=false
grafana-assistant tunnel daemon start|stop|restart|status
grafana-assistant tunnel daemon logs [--follow]
grafana-assistant tunnel daemon uninstall

Default security

Filesystem: read-only, project-scoped, blocks ~/.ssh, ~/.gnupg, ~/.aws/credentials, **/.env, **/secrets.yaml, **/*.pem, **/*.key. File size limit: 1MB.

Terminal: blocks dangerous commands (rm -rf /, mkfs, dd, fork bombs), minimal environment by default. Configurable via allow/deny lists in config.

Practical patterns for agent use

Shell permissions

The CLI makes HTTPS requests to Grafana. Always use required_permissions: ["all"] in Shell tool calls — this avoids TLS certificate verification failures from sandbox restrictions.

Timeout handling

Prompts can take 30s–300s depending on how many tools the assistant invokes. Set block_until_ms to at least 300000 (5 min) for complex queries.

What the CLI agent can do

The CLI agent is a read-only Grafana Assistant. It queries and analyzes data but cannot modify anything in Grafana.

Capabilities:

• Query metrics (PromQL, Graphite), logs (LogQL), traces (TraceQL), profiles, SQL, and more across all configured datasources
• Discover datasources, metric names, label values, and log streams
• Search dashboards and read panel definitions
• Search Grafana docs and blog posts
• Query alert history, on-call schedules, and incidents
• Query Asserts entity health, graph, and RCA patterns
• Query infrastructure memory service

Workflows it follows:

• Quick data query: discovers datasources → discovers metric/log names → executes query → presents findings
• Investigation: follows signals across metrics → logs → traces to find probable cause
• Q&A / doc search: answers Grafana/observability questions using docs

Not available in CLI (web/Slack only):

• Dashboard creation/modification
• Alert rule and silence management
• Navigation to Grafana pages