Skip to content
Back to search

gcx-marketplace

MarketplaceWorks with Claude CodeGitHub

Claude Code plugins for gcx

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/grafana--gcx/badge.svg)](/listings/grafana--gcx)

HTML

<a href="/listings/grafana--gcx"><img src="/api/listings/grafana--gcx/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

> For other installation options such as the binary or Go install, refer to the main [Installation](docs/sources/installation.md) doc.

The quickest way to install `gcx` in Linux or macOS is with the script, which downloads the latest release, verifies the SHA-256 checksum, and installs to `~/.local/bin`.

curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | sh

You can override the location with `GCX_INSTALL_DIR`:

curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | GCX_INSTALL_DIR=/usr/local/bin sh

To upgrade, run the same command again, then check `gcx --version`.

Windows

Run this command in PowerShell 7 or Windows PowerShell 5.1:

irm https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.ps1 | iex
gcx --version

The installer checks the SHA-256 checksum. It installs `gcx.exe` in `$env:LOCALAPPDATA\gcx\bin` and adds that directory to your user `PATH`. Run the command again to upgrade. Use `GCX_VERSION` or `GCX_INSTALL_DIR` to select a version or directory. See the [Windows install guide](docs/sources/installation.md#install-on-windows) for manual ZIP installation and uninstall steps. For WSL, use the Linux installer inside WSL.

Homebrew

To install `gcx` using Homebrew in Linux or macOS run:

brew install gcx

This installs the `gcx` formula from homebrew-core. Homebrew has a prebuilt bottle for macOS and Linux, so the install takes seconds and needs no tap.

To update to the latest version:

brew update && brew upgrade gcx

The Grafana tap also carries `gcx`. Use it if you want Homebrew to compile the binary on your machine, run:

brew install grafana/grafana/gcx

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines
  1. {
  2. "name": "gcx-marketplace",
  3. "description": "Claude Code plugins for gcx",
  4. "owner": {
  5. "name": "Grafana Labs"
  6. },
  7. "plugins": [
  8. {
  9. "name": "gcx",
  10. "source": "./claude-plugin",
  11. "description": "Debug, explore, and instrument with Grafana using gcx CLI",
  12. "version": "1.8.0"
  13. }
  14. ]
  15. }
README.md · README · 535 lines · 2 findings marked
  1. # gcx — Grafana CLI
  2. <p>
  3. <a href="https://github.com/grafana/gcx/actions/workflows/ci.yaml"><img src="https://github.com/grafana/gcx/actions/workflows/ci.yaml/badge.svg?branch=main" alt="CI"></a>
  4. <a href="https://go.dev/"><img src="https://img.shields.io/badge/go-1.27+-00ADD8?logo=go" alt="Go"></a>
  5. <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License"></a>
  6. <img src="https://img.shields.io/badge/status-generally%20available-green" alt="Generally Available">
  7. </p>
  8. ![gcx](./gcx.png)
  9. **`gcx` is Grafana in your terminal and your agentic coding environment.**
  10. With `gcx` you don't guess, but check the actual data. You can query production, investigate alerts, let the Assistant root-cause issues, or ship fixes with Observability built in, without ever leaving your editor.
  11. ## What is `gcx`?
  12. `gcx` is a CLI for Grafana Cloud, Enterprise, and OSS alike. It gives you and your AI coding agent structured access to your Grafana deployment's dashboards, alerts, SLOs, metrics, logs, traces, and more. Core features (resources, alerting, signal queries) work on Grafana 12 or higher, while Grafana Cloud adds product-specific commands on top. Refer to the [compatibility matrix](#compatibility-and-availability) for details on supported features.
  13. `gcx` works with any agentic coding tool. It ships with a suite of agent skills for common workflows like alert investigation, dashboard creation and GitOps, SLO management, and observability setup. Refer to [Use with your AI agent](#use-with-your-ai-agent) for further details.
  14. ## AI tools: Choose between `gcx`, Grafana MCP, and Grafana Assistant
  15. Grafana offers you a few AI tools to work with.
  16. **`gcx`** gives you and your coding agents access to Grafana through shell commands. Grafana MCP gives AI clients access through Model Context Protocol tools. Grafana Assistant is the Grafana AI agent, built into Grafana. Use `gcx` for terminal work, scripts, GitOps, and CI/CD pipelines. It [supports Grafana OSS, Enterprise, and Cloud](#compatibility-and-availability) and has [dedicated commands for Grafana Cloud products](#supported-grafana-cloud-products).
  17. The **Grafana MCP** is a Model Context Protocol server that gives AI assistants and LLM clients access to your Grafana instance, including clients without shell access. Choose between the [Grafana Cloud MCP](https://grafana.com/docs/grafana-cloud/ai-tools/mcp-servers/cloud-mcp/)(Grafana hosts the server) or the [Grafana OSS MCP](https://grafana.com/docs/grafana/latest/developer-resources/mcp/)(You run and configure the server).
  18. Finally, **Grafana Assistant** brings a purpose-built LLM into Grafana. Use it to troubleshoot issues, manage dashboards, and answer product questions in plain language. Some advanced features require the full Grafana Cloud feature set. In self-managed Grafana the Assistant app runs in your own deployment but connects to a Grafana Cloud Assistant backend, with a reduced feature set. Refer to the [Grafana Assistant](https://grafana.com/docs/grafana-cloud/platform/grafana-assistant/) documentation for an overview.
  19. > If your coding agent supports both shell commands and MCP, start with `gcx` for these workflows. Choose MCP when a specific tool or its connection model better meets your needs.
  20. ## Compatibility and availability
  21. ### Grafana version support
  22. `gcx` supports the current Grafana major version (currently 13.x), plus the previous major version for 3 months after the new one ships.
  23. | Grafana | Support level |
  24. |---------|---------------|
  25. | **Grafana Cloud** | **Full support.** Everything in this README, including Cloud-only products (SLO, Synthetic Monitoring, IRM, k6, Fleet, Adaptive Telemetry, Assistant). |
  26. | **Grafana 13+** (OSS / Enterprise) | **Full support** of self-hosted features. All app-platform API groups `gcx` relies on are enabled by default. |
  27. | **Grafana 12.x** (OSS / Enterprise) | **Not actively supported.** Most features will still work, but there'll only be patches with security updates. Features built on app-platform API groups that are not yet enabled by default need an explicit [feature toggle](#grafana-12-feature-toggles). |
  28. | **Grafana < 12** | **Not supported.** `gcx` detects the server version and exits with code 6 (version incompatible). |
  29. ### Feature availability by deployment
  30. Feature availability depends on your Grafana deployment:
  31. | Feature | Commands | OSS | Enterprise | Cloud | BYOC |
  32. |---------|----------|:---:|:----------:|:-----:|:----:|
  33. | Resource management (dashboards, folders) | `resources` | ✓ | ✓ | ✓ | ✓ |
  34. | Alert rules | `alert` | ✓ (1) | ✓ (1) | ✓ | ✓ |
  35. | Raw API passthrough | `api` | ✓ | ✓ | ✓ | ✓ |
  36. | Observability as Code | `dev` | ✓ | ✓ | ✓ | ✓ |
  37. | Signal queries (metrics, logs, traces, profiles) | `metrics`, `logs`, `traces`, `profiles` | ✓ (2) | ✓ (2) | ✓ | ✓ |
  38. | SLO, Synthetic Monitoring, IRM, k6, Fleet, etc. | `slo`, `synthetic-monitoring`, `irm`, `k6`, `fleet` | ✗ | ✗ | ✓ | (3) |
  39. | Adaptive Metrics / Logs / Traces | `metrics adaptive`, `logs adaptive`, `traces adaptive` | ✗ | ✗ | ✓ | (3) |
  40. | Grafana Assistant | `assistant` | ✗ | ✗ | ✓ | ✗ |
  41. (1) Alert rules (`gcx alert rules`, `gcx alert groups`) and ruler writes (`gcx alert ruler`) managed by data sources work on Grafana 12 or higher. To write Grafana-managed rules via the resources tier (`gcx resources pull/push alertrules`) you need Grafana 13 or higher. If you're using Grafana 12, refer to [Grafana 12 feature toggles](#grafana-12-feature-toggles).
  42. (2) Self-hosted signal queries (`gcx metrics query`, `gcx logs query`, `gcx traces query`, and `gcx profiles query`) work against self-hosted data sources (Prometheus, Loki, Tempo, Pyroscope), but you need to manually configure data source endpoints. In Grafana Cloud, your stack will auto-discover endpoints.
  43. (3) Bring Your Own Cloud runs the Grafana stack on your own infrastructure while connecting to the Grafana Cloud control plane. Core Grafana features (dashboards, alerts, signal queries) work in full. Cloud product availability (SLO, Synthetic Monitoring, IRM, etc.) depends on which plugins you've installed and configured in your BYOC stack.
  44. #### Grafana 12 feature toggles
  45. Grafana is progressively migrating APIs to app-platform (Kubernetes-style) API groups. Each group flips to enabled-by-default in a different release. When a command needs an API group your stack doesn't serve, upgrade or enable the corresponding feature toggle.
  46. - Track declaration of these requirements (min version, feature toggles) for each command in [#989](https://github.com/grafana/gcx/issues/989).
  47. - [Read more abut the new API model](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/#new-generation-http-apis).
  48. For example, writing Grafana-managed rules via the resources tier (`gcx resources pull/push alertrules`) requires Grafana 13 or higher, where the `rules.alerting.grafana.app` API is enabled by default. On Grafana 12 you must enable it explicitly with the `kubernetesAlertingRules` feature toggle:
  49. ```ini
  50. [feature_toggles]
  51. kubernetesAlertingRules = true
  52. ```
  53. This toggle is experimental in 12.x, requires a restart, and Unified Alerting must be enabled.
  54. ### Supported Grafana Cloud products
  55. `gcx` provides dedicated commands for each Grafana Cloud product:
  56. | Product | Command | Examples |
  57. |---------|---------|----------|
  58. | **Machine Learning** | `gcx ml` | `ml jobs list`, `ml holidays list`, `ml outlier-detectors list` |
  59. | **SLOs** | `gcx slo` | `slo definitions list`, `slo reports list` |
  60. | **Synthetic Monitoring** | `gcx synthetic-monitoring` | `synthetic-monitoring checks list`, `synthetic-monitoring probes list`, `synthetic-monitoring probes deploy` |
  61. | **IRM** | `gcx irm` | `irm oncall schedules list`, `irm oncall integrations list`, `irm incidents list`, `irm incidents create -f incident.yaml` |
  62. | **Alerting** | `gcx alert` | `alert rules list`, `alert groups list` |
  63. | **k6 Cloud** | `gcx k6` | `k6 load-tests list`, `k6 runs list` |
  64. | **Fleet Management** | `gcx fleet` | `fleet pipelines list`, `fleet collectors list` |
  65. | **Knowledge Graph** | `gcx kg` | `kg status`, `kg entities list`, `kg entities inspect`, `kg graph query` |
  66. | **Frontend Observability** | `gcx frontend` | `frontend apps list`, `frontend apps get` |
  67. | **App Observability** | `gcx appo11y` | `appo11y overrides get`, `appo11y settings get` |
  68. | **Agent Observability** | `gcx agento11y` | `agento11y conversations list`, `agento11y experiments pull`, `agento11y rules list` |
  69. | **Assistant** | `gcx assistant` | `assistant prompt`, `assistant investigations list`, `assistant mcp-servers list` |
  70. | **Adaptive Metrics** | `gcx metrics adaptive` | `metrics adaptive recommendations list`, `metrics adaptive rules list` |
  71. | **Adaptive Logs** | `gcx logs adaptive` | `logs adaptive patterns list`, `logs adaptive drop-rules list` |
  72. | **Adaptive Traces** | `gcx traces adaptive` | `traces adaptive recommendations list`, `traces adaptive policies list` |
  73. | **Profiles (Pyroscope)** | `gcx profiles` | `profiles query`, `profiles labels` |
  74. | **Traces (Tempo)** | `gcx traces` | `traces query`, `traces get`, `traces labels` |
  75. > **Keep in mind Grafana Cloud costs.** `gcx` itself is free, but some of these products are billed based on usage: Grafana Assistant is charged per token consumed (including requests made through `gcx`), Synthetic Monitoring per test execution, k6 per Virtual User Hour, and IRM per monthly active user. Queries and resource push/pull are not billed. Refer to [Costs and billing](docs/reference/costs.md) and the [Grafana Cloud Cost Management and Billing documentation](https://grafana.com/docs/grafana-cloud/cost-management-and-billing/) for more details.
  76. ## New to `gcx` or Grafana? Start here!
  77. ### Install `gcx`
  78. > For other installation options such as the binary or Go install, refer to the main [Installation](docs/sources/installation.md) doc.
  79. The quickest way to install `gcx` in Linux or macOS is with the script, which downloads the latest release, verifies the SHA-256 checksum, and installs to `~/.local/bin`.
  80. ```sh
  81. curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 119 on GitHub
  82. ```
  83. You can override the location with `GCX_INSTALL_DIR`:
  84. ```sh
  85. curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | GCX_INSTALL_DIR=/usr/local/bin sh
  86. ```
  87. To upgrade, run the same command again, then check `gcx --version`.
  88. #### Windows
  89. Run this command in PowerShell 7 or Windows PowerShell 5.1:
  90. ```powershell
  91. irm https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.ps1 | iex
  92. gcx --version
  93. ```
  94. The installer checks the SHA-256 checksum. It installs `gcx.exe` in
  95. `$env:LOCALAPPDATA\gcx\bin` and adds that directory to your user `PATH`.
  96. Run the command again to upgrade. Use `GCX_VERSION` or `GCX_INSTALL_DIR` to
  97. select a version or directory. See the [Windows install guide](docs/sources/installation.md#install-on-windows)
  98. for manual ZIP installation and uninstall steps. For WSL, use the Linux
  99. installer inside WSL.
  100. #### Homebrew
  101. To install `gcx` using Homebrew in Linux or macOS run:
  102. ```bash
  103. brew install gcx
  104. ```
  105. This installs the `gcx` formula from homebrew-core. Homebrew has a prebuilt bottle for macOS and Linux, so the install takes seconds and needs no tap.
  106. To update to the latest version:
  107. ```bash
  108. brew update && brew upgrade gcx
  109. ```
  110. The Grafana tap also carries `gcx`. Use it if you want Homebrew to compile the binary on your machine, run:
  111. ```bash
  112. brew install grafana/grafana/gcx
  113. ```
  114. ### Access Grafana
  115. If you're new to Grafana Cloud, use `gcx` to create a free account and connect to its first stack when you approve:
  116. ```sh
  117. gcx signup
  118. ```
  119. Next, log into your account from your terminal or agent:
  120. ```sh
  121. gcx login
  122. ```
  123. `login` creates or re-authenticates a context. It auto-detects whether the server is Grafana Cloud (`*.grafana.net`) or on-premise and adjusts the prompt accordingly.
  124. Refer to [Authentication](/docs/sources/authentication) for the available paths and options to authenticate.
  125. ## Use with your AI agent
  126. `gcx` is compatible with any AI agent. Agent mode uses known identity signals, including Codex and Gemini CLI. For tools without a native signal, set `GCX_AGENT_NAME` to a supported label. Refer to [agent detection and harness names](docs/design/environment-variables.md#agent-mode-variables) for details.
  127. If you're contributing a new Grafana domain capability to `gcx`, ask your coding agent to use [`contribute`](.agents/skills/contribute/SKILL.md) before choosing a command, provider, or data source path.
  128. ### Install agent skills
  129. `gcx` ships a portable agent skills bundle for setup, dashboard creation and GitOps, datasource exploration, alert investigation, structured debugging, SLO management, Synthetic Monitoring workflows, Knowledge Graph diagnosis, project scaffolding, resource generation and import, and end-to-end Observability rollout.
  130. Read the [full skill inventory](claude-plugin/README.md#skills) in the Claude plugin README, and refer to the [skill lifecycle](claude-plugin/README.md#skill-lifecycle) for the catalog and ownership limits.
  131. **For Claude Code**
  132. Use the dedicated [Claude Code plugin](claude-plugin/README.md):
  133. ```text
  134. /plugin marketplace add grafana/gcx
  135. /plugin install gcx@gcx-marketplace
  136. ```
  137. **For other `.agents`-compatible harnesses**
  138. For example: OpenAI Codex, OpenCode, and Pi. View the skills shipped in the bundle with:
  139. ```sh
  140. gcx agent skills list
  141. ```
  142. Install the bundle into `~/.agents/skills` with:
  143. ```sh
  144. gcx agent skills install --all
  145. ```
  146. ### List, update, or remove skills
  147. To see locally present retired skills and their replacements, run `gcx agent skills list`.
  148. To refresh skills that are already installed, run `gcx agent skills update`.
  149. Note that `update`:
  150. - Refreshes skills but doesn't add newly bundled skills. After upgrading `gcx`, install a new skill by name.
  151. - Warns about deprecated and retired skills, but never deletes retired files or installs replacements automatically.
  152. To refresh existing skills and add every newly bundled one, run:
  153. ```sh
  154. gcx agent skills update
  155. gcx agent skills install --all
  156. ```
  157. To remove an unwanted skill explicitly, run `gcx agent skills uninstall <skill>`. Retired names remain supported after their
  158. content leaves the bundle.
  159. ### The agentic workflow
  160. Investigation, fix, instrumentation, monitoring — without the developer ever leaving their editor. The Grafana Assistant provides the intelligence; gcx provides the interface. And because it all builds on everything you've already configured in Grafana — your dashboards, your alerts, your datasources — no other tool can give you this depth out of the box.
  161. Here's how your coding agent with access to production investigates alerts with Grafana Assistant and `gcx`:
  162. **1. An alert fires:** For example, a P95 latency on the checkout service crosses the SLO threshold.
  163. **2. The Assistant investigates:** Your coding agent calls the Grafana Assistant through `gcx`. The Assistant has already started its investigation, and is able to trace the issue to a missing index on `customer_id` causing full table scans under load.
  164. **3. It fixes the issue:** Drafts the migration, and adds the index.
  165. **4. It prevents recurrence:** Instruments the service with OpenTelemetry spans, sets up a Synthetic Monitoring check on the checkout flow, and creates an alert rule on query duration.
  166. **5. It ships!** The Assistant opens a PR, tests pass, deploys to production. The alert resolves.
  167. ```sh
  168. $ gcx assistant investigations list
  169. ID TITLE STATUS UPDATED
  170. abc1 Checkout P95 latency breach active 2m ago
  171. def2 Memory leak in payment-svc resolved 1h ago
  172. ```
  173. ### More AI workflows
  174. While the alerting example uses the Grafana Assistant, which requires Grafana Cloud, these workflows work on any Grafana setting:
  175. - **Resource GitOps**. Pull writable resource types to local files, let your agent edit them, push back to Grafana (`gcx resources pull` / `gcx resources push`).
  176. - **Explore your data**. Discover datasources, metrics, labels, and log streams before writing queries (`gcx datasources list`, `gcx metrics labels`).
  177. - **Bring Assistant context into your agent**. Read a conversation by ID or a shared Grafana Assistant URL, including AI SDK main-thread transcripts (`gcx assistant conversation get <id-or-url> -o json`). Legacy transcript JSON preserves tool calls, results, durations, thinking blocks, and panel artifacts.
  178. - **Look up product docs**. Search and read Grafana documentation from the terminal (`gcx docs search`, `gcx docs get`).
  179. - **SLO management**. Create, monitor, and investigate SLOs from your terminal (`gcx slo definitions list`, `gcx slo reports list`).
  180. - **Onboarding & setup**. Instrument a Kubernetes cluster and configure Grafana Cloud products (`gcx instrumentation setup`).
  181. - **Observability as Code**. Scaffold a project, import existing dashboards as Go code, lint, and deploy (`gcx dev scaffold`, `gcx dev import`).
  182. ## What can I do with gcx?
  183. Here's a glimpse of what you can do with `gcx`. Refer to the [user guides](./docs/sources/guides/) for extended use cases.
  184. ### Query production metrics from your terminal
  185. ```sh
  186. $ gcx metrics query 'sum by (handler)(rate(grafana_http_request_duration_seconds_count{}[5m]))' --since 1h -o graph
  187. ```
  188. ![Terminal graph output](./graph_example.png)
  189. ### Query data sources
  190. To query data sources directly:
  191. ```sh
  192. # PromQL queries
  193. gcx metrics query 'rate(http_requests_total[5m])' --since 1h
  194. gcx metrics labels
  195. gcx metrics metadata
  196. # LogQL queries
  197. gcx logs query '{app="nginx"} |= "error"' --since 1h
  198. # Use a LogQL metric query for complete counts
  199. gcx logs metrics 'count_over_time({app="nginx"}[1h])'
  200. gcx logs labels
  201. gcx logs series --match '{app="nginx"}'
  202. ```
  203. > `gcx` also supports Pyroscope (profiling) and Tempo (traces) data sources.
  204. ### Check what's firing
  205. To check alerts:
  206. ```sh
  207. $ gcx alert rules list --state firing
  208. ┌──────────────────────────────────────┬─────────────────────────────────────────────────────────────────────┬──────────┬──────────┬──────────┐
  209. │ UID │ NAME │ STATE │ HEALTH │ PAUSED │
  210. ├──────────────────────────────────────┼─────────────────────────────────────────────────────────────────────┼──────────┼──────────┼──────────┤
  211. │ e62566b8-da2d-45e0-853a-40abebc9f863 │ adaptive_traces_forecast_gme_distributor_alert │ firing │ ok │ no │
  212. │ cfhcfnhd8xam9a │ GraphiteProxy: Reads (dev) Native - Error Budget Burn Rate is High │ firing │ ok │ no │
  213. │ affq1sffre0apd │ Unified Storage: HIGH_SLOW Latency - Error Budget Burn Rate is High │ firing │ ok │ no │
  214. │ 16ddf4b0-7d8c-5dad-a71a-81f87a1e47a2 │ BillingSeriesAbsent │ firing │ ok │ no │
  215. │ 09d44d08-b4cc-5d0e-8544-514e380f6bb3 │ k6CloudSecretsUsageReportingNoData │ firing │ ok │ no │
  216. │ eb62d01f-5f73-543b-947b-2c849890d5f6 │ MissingBackups │ firing │ ok │ no │
  217. │ 5f9e01d4-0b2d-5b51-a787-26535ded4719 │ MissingBackups │ firing │ ok │ no │
  218. │ e4646576-9c07-5dfd-b22c-1e5b4da761ef │ MissingBackups │ firing │ ok │ no │
  219. │ b89d5170-d0bd-5869-ad22-7a0a944b3aae │ MissingBackups │ firing │ ok │ no │
  220. ```
  221. ### Review SLO status
  222. ```sh
  223. $ gcx slo definitions list
  224. ┌───────────────────────┬───────────────────────────────────────────────────────┬─────────────┬────────────┬────────────┐
  225. │ UUID │ NAME │ TARGET │ WINDOW │ STATUS │
  226. ├───────────────────────┼───────────────────────────────────────────────────────┼─────────────┼────────────┼────────────┤
  227. │ y5yc8cy86yqtmey930foh │ CB additional identifier │ 90.00% │ 28d │ created │
  228. │ sgz23sbv2c19v0r32s8y1 │ Checkout App - p95 Latency │ 99.50% │ 28d │ updated │
  229. │ nwd4dk7j38spanror727k │ GraphiteProxy: Reads (dev) Native │ 99.50% │ 28d │ created │
  230. │ e1cteeyl2ukmilw1tqugw │ KG fusion test grafana-slo-app │ 99.50% │ 28d │ created │
  231. │ bwyf5d8g1614ugri7u0w7 │ KG fusion test grafana-slo-stats-service │ 99.50% │ 28d │ created │
  232. │ tfkp5e0ronnl1ywpbv9b5 │ OTLPGateway: MetricWrites (dev) - Mimir │ 99.90% │ 28d │ created │
  233. │ wvgxovr2k60efxizv1y9f │ Unified Storage: HIGH_SLOW Latency │ 99.50% │ 28d │ updated │
  234. └───────────────────────┴───────────────────────────────────────────────────────┴─────────────┴────────────┴────────────┘
  235. ```
  236. ### Manage resources
  237. Manage both Grafana-native resources (dashboards, folders) and Grafana Cloud resources from a single CLI:
  238. ```bash
  239. # Pull dashboards and folders to local files
  240. gcx resources pull dashboards -p ./resources -o yaml
  241. gcx resources pull folders -p ./resources -o yaml
  242. # Push local changes back to Grafana
  243. gcx resources push -p ./resources
  244. # Include the resource identities returned by successful writes
  245. gcx resources push -p ./resources --include-successes -o json
  246. # An aborted push returns completed identities and a nonzero exit
  247. gcx resources push -p ./resources --include-successes -o json --on-error abort
  248. # Preview changes without applying
  249. gcx resources push -p ./resources --dry-run
  250. # Validate resources before pushing
  251. gcx resources validate -p ./resources
  252. # Edit a dashboard interactively (opens $EDITOR)
  253. gcx resources edit dashboards/my-dashboard
  254. # Delete a resource
  255. gcx resources delete dashboards/my-dashboard
  256. ```
  257. ### Synthetic management
  258. Synthetic Monitoring check manifests support optional `spec.folderUid` for folder assignment. Refer to the [Synthetics check management guide](claude-plugin/skills/synth-manage-checks/SKILL.md#step-3-build-yaml-definition) for create/update semantics and cross-stack push guidance.
  259. ### Observability as code
  260. `gcx` includes tools for managing Grafana resources as Go code using the [Grafana Foundation SDK](https://grafana.com/docs/grafana/latest/as-code/observability-as-code/foundation-sdk/):
  261. ```bash
  262. # Scaffold a new project
  263. gcx dev scaffold --project my-dashboards
  264. # Import existing dashboards from Grafana as Go builder code
  265. gcx dev import dashboards
  266. # Live-reload dev server (preview dashboards in browser)
  267. gcx dev serve ./resources
  268. # Lint resources with built-in and custom Rego rules
  269. gcx dev lint run ./resources
  270. gcx dev lint list-rules # list available rules
  271. gcx dev lint new dashboard my-rule # create custom rule
  272. # Build and push
  273. go run . && gcx resources push -p ./resources
  274. ```
  275. ### GitOps
  276. Pull resources to files, version in git, then push back:
  277. ```bash
  278. # Pull all resources
  279. gcx resources pull -p ./resources -o yaml
  280. # Commit to git
  281. git add ./resources && git commit -m "snapshot Grafana resources"
  282. # Push changes from git to Grafana
  283. gcx resources push -p ./resources
  284. ```
  285. `gcx push` is idempotent, so running it multiple times produces the same result. Folders are automatically pushed before dashboards to satisfy dependencies.
  286. Updates preserve the existing `kubectl` manager identity, including identities from `grafanactl` and older `gcx` releases. New resources use the stable identity `gcx`. Refer to [manager metadata](docs/architecture/resource-model.md#manager-metadata).
  287. > **gcx resources push/pull vs Git Sync:** [Git Sync](https://grafana.com/docs/grafana/latest/as-code/observability-as-code/git-sync/) provides bi-directional sync between your git repo and Grafana for dashboards. `gcx resources push/pull` enables users to create their own as-code resource synchronisation workflows. `gcx resources push/pull` also works with all resources available in `gcx resources get`, not just dashboards.
  288. ### CI/CD
  289. You can deploy your resources using `gcx`:
  290. ```yaml
  291. # .github/workflows/deploy-resources.yaml
  292. name: Deploy Grafana Resources
  293. on:
  294. push:
  295. branches: [main]
  296. paths: ['resources/**']
  297. jobs:
  298. deploy:
  299. runs-on: ubuntu-latest
  300. steps:
  301. - uses: actions/checkout@v4
  302. - name: Install gcx
  303. run: |
  304. curl -fL "$(curl -s https://api.github.com/repos/grafana/gcx/releases/latest | grep browser_download_url | grep linux_amd64.tar.gz | cut -d '"' -f 4)" | tar xz gcx
  305. chmod +x gcx && sudo mv gcx /usr/local/bin/
  306. - name: Deploy resources
  307. env:
  308. GRAFANA_SERVER: ${{ secrets.GRAFANA_PROD_URL }}
  309. GRAFANA_TOKEN: ${{ secrets.GRAFANA_PROD_TOKEN }}
  310. run: |
  311. gcx resources validate -p ./resources
  312. gcx resources push -p ./resources --on-error abort
  313. ```
  314. - `gcx resources` commands are designed for non-interactive use, apart from `edit`, which opens an external editor
  315. - `resources delete` has no confirmation prompt. Named selectors proceed without `--force`; a type-only selector such as `dashboards` requires `--force` (`--yes` also enables it) and can delete every matching resource in the selected context and namespace
  316. - `--dry-run` on `push` and `delete` to preview changes
  317. - `--on-error abort|fail|ignore` to control error behavior
  318. - `-o json` or `-o yaml` for machine-parseable output
  319. - `--jq '<expr>' -o agents` for [jq with compact output and spilling](docs/design/output.md#16-jq-transformation)
  320. ### Provisioning and UI updates
  321. Contact points, notification policies, templates, and mute timings that `gcx` creates or updates through Grafana's provisioning API remain editable in the Grafana UI by default.
  322. Pass `--allow-ui-updates=false` to contact-point or mute-timing create and update commands, `alert templates upsert`, or `alert notification-policies set` to use Grafana's default provisioning ownership. Grafana then prevents UI edits to the provisioned item.
  323. To update a provisioned contact point, keep `--allow-ui-updates=false`.
  324. Grafana can reject an attempt to make an existing provisioned contact point editable in the UI because its provenance cannot be changed by that update.
  325. ```bash
  326. gcx alert contact-points create -f contact-point.yaml --allow-ui-updates=false
  327. ```
  328. ### Mobile Frontend Observability apps
  329. Mobile Frontend Observability app manifests set `spec.appType: mobile` and a mobile
  330. `spec.runtime`. Refer to [`gcx frontend apps create`](docs/sources/cli-reference.md#gcx-frontend-apps-create-gcx-frontend-apps-create)
  331. for the runtimes and an example manifest, and
  332. [`gcx frontend apps update`](docs/sources/cli-reference.md#gcx-frontend-apps-update-gcx-frontend-apps-update) for what an update keeps.
  333. ### Manage Assistant Watchers (experimental)
  334. Read Watcher configuration with `gcx assistant watchers list` and `get WATCHER`, inspect runtime observations with `status WATCHER`, or export manifests with `gcx resources pull watchers`. Apply configuration with `create -f FILE`, `update WATCHER -f FILE` or `gcx resources push`; remove a Watcher with `delete WATCHER --force`. Creation stays inactive and uncalibrated. Requires Grafana Cloud. See [Assistant Watchers](docs/sources/guides/manage-assistant-watchers).
  335. Pulled Watcher manifests can be pushed back unchanged. Applying configuration preserves calibrated content and learned state; meaningful settings outside the manifest model cause an explicit refusal.
  336. ## Raw API access
  337. For anything not covered by built-in commands, use the API passthrough. For example, to work with dashboards:
  338. ```bash
  339. # Review who can access a dashboard
  340. gcx api /api/dashboards/uid/my-dashboard/permissions -o yaml
  341. # Star a dashboard for the current user
  342. gcx api /api/user/stars/dashboard/uid/my-dashboard -X POST
  343. # Version history: list versions
  344. gcx api /api/dashboards/uid/my-dashboard/versions -o yaml
  345. # Compare two dashboard JSONs before pushing
  346. gcx api /api/dashboards/calculate-diff -X POST -d @diff-request.json
  347. ```
  348. `gcx api` accepts paths on the configured Grafana stack. It rejects absolute URLs.
  349. ## Usage statistics
  350. `gcx` reports limited usage statistics about itself to Grafana Labs. This data is used to understand which commands and flags are used most, where commands fail, and which commands people try that don’t exist, so we can make the product better.
  351. To find out more about `gcx` usage statistics, or for information on how to disable it, refer to the [Usage and statistics documentation](https://grafana.com/docs/grafana/latest/ai-tools/grafana-cli/gcx/anonymous-usage-statistics/).
  352. ## Documentation
  353. | Topic | Description |
  354. |-------|-------------|
  355. | [Installation](docs/sources/installation.md) | Install gcx on macOS, Linux, and Windows |
  356. | [Authentication](docs/sources/authentication.md) | Authenticate `gcx` |
  357. | [Configuration](docs/sources/configuration.md) | Contexts, authentication, environment variables |
  358. | [Dashboards as Code](docs/sources/guides/dashboards-as-code.md) | Dashboard-as-code workflow with live dev server |
  359. | [Managing Resources](docs/sources/guides/manage-resources.md) | Get, push, pull, delete, edit, validate |
  360. | [Linting Resources](docs/sources/guides/lint-resources.md) | Lint dashboards and alert rules with Rego policies |
  361. | [CLI Reference](docs/sources/cli-reference.md) | Full command reference (auto-generated) |
  362. | [Engineering RFCs](docs/rfcs/README.md) | Proposals, technical designs, and review workflows |
  363. ## Contributing
  364. Read our [contributing guide](CONTRIBUTING.md).
  365. ## License
  366. Apache 2.0 [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.