Terminal
Terminal/Skill
Guides use of the grafana-assistant CLI to send questions to Grafana Assistant and keep conversation context.
By Grafana Labs
Works with
npx skills add grafana/ai-marketplace --skill grafana-assistant-cliCLI tool for interacting with Grafana Assistant via the A2A API.
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
GRAFANA_ASSISTANT_CONFIG env var (if set)./grafana-assistant.yaml (current directory, use --local flag)~/.config/grafana-assistant/config.yamlcurrent-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]
| Variable | Description |
|---|---|
GRAFANA_URL | Grafana instance URL (overrides config) |
GRAFANA_SA_TOKEN | Service account token (overrides config) |
GRAFANA_ASSISTANT_CONFIG | Override config file path |
--url and --token flagsGRAFANA_URL and GRAFANA_SA_TOKEN env vars--instance <name> flagcurrent-instance from config filegrafana-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.
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}'
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>
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
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:
--json on the first prompt to capture the contextId-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:
-c, every prompt is a brand new conversation with no memory.{
"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.
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.
grafana-assistant agents
grafana-assistant agents --json
grafana-assistant agents -i <instance>
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
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
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
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.
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.
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.
The CLI agent is a read-only Grafana Assistant. It queries and analyzes data but cannot modify anything in Grafana.
Capabilities:
Workflows it follows:
Not available in CLI (web/Slack only):