--- title: "Use Grafana Assistant CLI | Grafana Cloud documentation" description: "Use Grafana Assistant CLI for terminal chat, automation, and local project access." --- # Use Grafana Assistant CLI > Note > > Grafana Assistant CLI is currently in [public preview](/docs/release-life-cycle/). 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`. - If you want to connect local files or commands, `grafana-assistant auth` also requests the `tunnel:connect` scope. - Use [Pricing and limits](/docs/grafana-cloud/machine-learning/assistant/pricing) 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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash uvx grafana-assistant ``` If you want a global Python install instead, use `pip`. Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash brew install grafana/grafana/grafana-assistant ``` If you prefer, add the tap first and then install: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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](https://github.com/grafana/assistant-cli/releases/latest), 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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash grafana-assistant config use-instance my-stack ``` ### Authenticate with Grafana Cloud Run browser-based authentication to sign in and authorize the CLI. Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash grafana-assistant config current grafana-assistant config list ``` If you want to work against a different stack for a single command, use `--instance `. ## 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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash grafana-assistant chat ``` You can continue the last conversation with `--continue` or resume a specific conversation with `--context `. ### Run one-off prompts in scripts Use `prompt` when you want a single answer, machine-readable output, or shell automation. Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash grafana-assistant prompt \ "List all firing alerts in namespace assistant" \ --json ``` ## Next steps - [Get started with Grafana Assistant](/docs/grafana-cloud/machine-learning/assistant/get-started) - [Understand Grafana Assistant pricing and usage](/docs/grafana-cloud/machine-learning/assistant/pricing) - [Manage Assistant access with RBAC](/docs/grafana-cloud/machine-learning/assistant/privacy-and-security/rbac)