Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow AI and machine learningbreadcrumb arrow Grafana Assistantbreadcrumb arrow Guidesbreadcrumb arrow Assistant CLI
Grafana Cloud

Use Grafana Assistant CLI

Note

Grafana Assistant CLI is currently in public preview. Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.

Grafana Assistant CLI brings Grafana Assistant into your terminal. You can chat interactively, run one-off prompts in scripts, and connect local projects so Assistant can read files on your machine during a session.

Before you begin

Before you use the CLI, confirm that Assistant is available in your Grafana Cloud stack and that you can run grafana-assistant on your machine.

  • For browser-based sign-in with grafana-assistant auth, you need the Assistant CLI User role. Users with the Grafana Editor role or above receive this automatically. Custom roles must include grafana-assistant-app.tokens:access.
  • For headless automation, use a service account token with the Editor role.
  • If you want to connect local files or commands, grafana-assistant auth also requests the tunnel:connect scope.
  • Use Pricing and limits for Assistant usage and billing guidance.

Install the CLI

You can run Grafana Assistant CLI with uvx, install it with pip or Homebrew, or download a release binary.

Run with uvx or install with pip

Use uvx if you want to run the CLI without installing it globally.

Bash 
uvx grafana-assistant

If you want a global Python install instead, use pip.

Bash 
pip install grafana-assistant

If you use uvx, replace grafana-assistant in the examples that follow with uvx grafana-assistant.

Install with Homebrew

Use Homebrew on macOS if you want a simple install path and easy upgrades.

Bash 
brew install grafana/grafana/grafana-assistant

If you prefer, add the tap first and then install:

Bash 
brew tap grafana/grafana
brew install grafana-assistant

Download a release binary

Download the archive for your platform from the Grafana Assistant CLI releases page, extract it, and place the grafana-assistant binary in a directory in your PATH.

On Windows, use the .zip archive and add grafana-assistant.exe to your PATH.

Understand how the CLI compares with Assistant

The CLI uses Grafana Assistant through the same backend service, so many core workflows stay the same while the terminal unlocks a few additional use cases.

Use the same Assistant capabilities

You can ask many of the same questions you ask in the web Assistant. For example, you can query metrics, logs, traces, and profiles, inspect alerts, find dashboards, and run investigation workflows with natural language. The CLI follows your Grafana access model, so it doesn’t bypass existing permissions.

Use CLI-only workflows

The CLI is a better fit when you want to work from a terminal or automate Assistant tasks.

  • Use grafana-assistant chat for a full-screen terminal chat experience.
  • Use grafana-assistant prompt --json in scripts, CI jobs, and shell pipelines.
  • Configure multiple Grafana instances and switch between them from the command line.
  • Run the tunnel so Assistant can read local project files and, optionally, run approved shell commands on your machine.

Choose the web Assistant for UI-native tasks

The web Assistant is still the better fit when you want direct Grafana UI context, such as the current dashboard, selected panel, or point-and-click actions inside Grafana Cloud.

Get help from the CLI

The CLI includes built-in help for the top-level command and every subcommand, so start there instead of memorizing flags.

Bash 
grafana-assistant --help
grafana-assistant chat --help
grafana-assistant prompt --help
grafana-assistant tunnel --help
grafana-assistant config --help

The main commands are auth, chat, prompt, config, tunnel, and agents-md. The help output shows available flags, defaults, and subcommands for your installed version.

Set up your first instance

Set up an instance before you start chat or prompt workflows. This creates a named connection to your Grafana Cloud stack and tells the CLI which stack to use by default.

Add an instance

Create a named instance with your Grafana Cloud URL.

Bash 
grafana-assistant config set-instance my-stack \
  --url https://my-stack.grafana.net

Select the default instance

Set the instance as your current default so later commands can use it automatically.

Bash 
grafana-assistant config use-instance my-stack

Authenticate with Grafana Cloud

Run browser-based authentication to sign in and authorize the CLI.

Bash 
grafana-assistant auth

The CLI opens your browser for a one-time sign-in flow. After authentication completes, you can use chat, prompt, and tunnel connect without passing a token each time.

Verify the setup

Confirm that the instance is configured and selected.

Bash 
grafana-assistant config current
grafana-assistant config list

If you want to work against a different stack for a single command, use --instance <INSTANCE_NAME>.

Use the CLI for common workflows

These workflows cover the fastest way to start using the CLI without trying to learn every command up front.

Start an interactive chat

Use interactive chat when you want a terminal-first experience with streaming responses and multi-turn conversations.

Bash 
grafana-assistant chat

You can continue the last conversation with --continue or resume a specific conversation with --context <CONTEXT_ID>.

Run one-off prompts in scripts

Use prompt when you want a single answer, machine-readable output, or shell automation.

Bash 
grafana-assistant prompt "List all firing alerts in namespace assistant" --json
grafana-assistant prompt "follow up on the same issue" --continue --json

Connect local projects with the tunnel

Use the tunnel when you want Assistant to inspect code or files from your machine during a conversation.

Bash 
grafana-assistant config add-project my-app ~/projects/my-app
grafana-assistant tunnel connect

The filesystem tool is read-only by default. You can also enable terminal access if you need Assistant to run local shell commands and you want to approve those requests.

Try example workflows

These examples show how to use the CLI for common terminal and automation tasks.

Query observability data

Use the same datasource-aware prompts you use in Assistant, but from the command line.

Bash 
grafana-assistant prompt \
  "Using ops-cortex for metrics, show CPU usage for namespace assistant over the last hour"

Continue a multi-step investigation

Use --continue when you want to keep the same context without passing a context ID manually.

Bash 
grafana-assistant prompt \
  "Using Grafana Logging for logs, show error logs from namespace assistant in the last 15 minutes"

grafana-assistant prompt \
  "Now correlate those errors with traces from Tempo Ops in the same time range" \
  --continue

Parse Assistant output in a script

Use --json when another tool needs to consume the response.

Bash 
grafana-assistant prompt \
  "List all firing alerts in namespace assistant" \
  --json

Next steps