# import-dashboards

Converts live Grafana dashboards into Go builder code using the gcx CLI, for teams moving dashboards into code.

Skill by Grafana Labs. Category: Shipping and ops.

## Install

Project (for this project only):

```sh
npx skills add grafana/gcx --skill import-dashboards
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add grafana/gcx --skill import-dashboards -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 24. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/site/grafana.gcx/import-dashboards)

## Source

[Open the source](https://github.com/grafana/gcx/tree/HEAD/claude-plugin/skills/import-dashboards). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: import-dashboards
description: >
  Imports existing Grafana dashboards as Go builder code via gcx. Use when
  the user wants to convert live dashboards to builder code, migrate
  dashboards to code, or reverse-engineer a dashboard from a Grafana
  instance. Triggers on
  "import dashboard", "convert to code", "dashboard as code", "export dashboard".
  For pulling dashboards as YAML/JSON resource files rather than Go code,
  use manage-dashboards instead.
---

# Import Dashboards as Code

Import existing dashboards from a Grafana instance and convert them to Go
builder code using `gcx dev import`.

## Prerequisites

1. gcx installed and configured with a Grafana connection
   (`gcx config check` should show a valid context)
2. The target Grafana instance must be reachable

## Import Commands

### Import All Dashboards

```bash
gcx dev import dashboards
```

Writes Go files to `imported/` (default). Each dashboard becomes a function
returning `*resource.ManifestBuilder`.

### Import a Specific Dashboard

```bash
gcx dev import dashboards/my-dashboard-uid
```

### Import to a Custom Directory

```bash
gcx dev import dashboards --path src/grafana
```

### Import Multiple Resource Types

```bash
gcx dev import dashboards folders
```

## How It Works

```
Grafana Instance
    │
    ▼
gcx dev import dashboards/foo
    │
    ├── 1. Fetches resource via K8s API (/apis endpoint)
    ├── 2. Detects the resource API version
    ├── 3. Runs version-specific converter (JSON → SDK builder code)
    ├── 4. Wraps in resource.NewManifestBuilder()
    └── 5. Writes to imported/<snake_case_name>.go
```

The converter produces Go code using the grafana-foundation-sdk builder
pattern — the same pattern used by `dev generate` and `dev scaffold`.

## Output Format

Each imported file looks like:

```go
package dashboards

import (
    "github.com/grafana/grafana-foundation-sdk/go/dashboardv2beta1"
    "github.com/grafana/grafana-foundation-sdk/go/resource"
)

func MyDashboard() *resource.ManifestBuilder {
    // ... builder code generated from the live dashboard
}
```

## Workflow: Import → Edit → Push

```bash
# 1. Import from Grafana
gcx dev import dashboards --path internal/dashboards

# 2. Review and edit the generated code
#    (fix up builder calls, add variables, etc.)

# 3. Render manifests from the builders. In a gcx-scaffolded project,
#    `go run .` writes JSON manifests to ./resources
go run .

# 4. Push back to Grafana
gcx resources push
```

## Common Issues

| Issue | Fix |
|-------|-----|
| "no converter found" | The resource's API version has no converter; the error message names the unsupported version |
| Auth error (401/403) | Run `gcx config check` to verify credentials |
| Empty import | The selector matched no resources; check UID with `gcx resources get dashboards` |
| Build fails with `undefined: cog` (or another lowercase SDK identifier) | Older gcx versions omit SDK imports from generated files. Add the missing import `github.com/grafana/grafana-foundation-sdk/go/<pkg>` for each undefined identifier — `variants` is nested at `go/cog/variants`. Newer gcx emits complete imports |
| Imported code doesn't compile for other reasons | Complex dashboards can produce converter output that needs manual fixup: build, read the first error, fix, repeat |
````

- Previous: [gcx-observability](https://syn4pse.dev/terminal/gcx-observability.md)
- Next: [diagnose-entity-graph](https://syn4pse.dev/terminal/diagnose-entity-graph.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
