grafana-util docs
Home / Manpages / grafana-util-dashboard.1

grafana-util-dashboard.1

Browser-readable rendering of a generated roff manpage.

This page renders the generated roff manpage into readable HTML for browser use. For richer per-subcommand detail, prefer the command-reference pages.

NAME

grafana-util-dashboard - dashboard browse, export, import, analysis, governance, and screenshot workflows

SYNOPSIS

grafana-util dashboard [SUBCOMMAND] [OPTIONS]

grafana-util db [SUBCOMMAND] [OPTIONS]

DESCRIPTION

grafana-util dashboard is the namespace for live dashboard workflows, local draft handling, export/import review, inspection, topology, and screenshots. The same namespace is also available as grafana-util db.

Use this namespace when you need to browse live dashboards, fetch or clone a live dashboard into a local JSON draft, compare local files with Grafana, inspect export or live metadata, convert raw dashboards into prompt JSON, or publish a prepared dashboard back to Grafana.

WORKFLOW LANES

- Browse and inventory: browse, list, and fetch-live.

- Analyze dashboards and build reports: analyze, list-vars, and topology checks.

- Move: export, import, clone-live, raw-to-prompt, diff, and publish paths.

- Author: fetch-live, clone-live, serve, patch-file, edit-live, review, and publish around one dashboard draft.

- Review Before Mutate: review, governance-gate, and impact analysis.

- History: list, restore, and export revision history before you recover or promote a dashboard.

- Capture: screenshot flows for reproducible visual proof.

For single-dashboard authoring, the local draft path is:

- fetch-live or clone-live to start from one live dashboard

- serve to keep one or more drafts open in a local preview browser while you edit, optionally opening the browser for you

- review to verify one draft

- patch-file to rewrite local metadata

- edit-live to fetch one live dashboard into an editor with a safe local-draft default and a review-aware apply gate

- publish to replay that draft back through the import pipeline

review, patch-file, and publish also accept --input - for one wrapped or bare dashboard JSON document from standard input. Use that when an external generator already writes the dashboard JSON to stdout. patch-file --input - requires --output, and publish --watch is the local-file variant for repeated save-and-preview loops and does not support --input -.

Choose this page when the task is dashboard work but you are still deciding whether the next step is to inspect, move, review, or capture.

BEFORE / AFTER

  • Before: dashboard work is often split across UI browsing, one-off exports, local JSON edits, and ad hoc screenshot or review steps.
  • After: the dashboard namespace keeps browse, inspect, move, review, and capture in one place, so you can pick the lane first and then jump to the matching subcommand.

SUBCOMMANDS

browse
Open the live dashboard tree or a local export tree in an interactive terminal UI. Use when: You want to explore folders, select a dashboard, inspect the live tree before fetching, diffing, importing, or deleting, review raw JSON edits inside the live TUI flow, or review a local export tree without calling Grafana.
fetch-live
Fetch one live dashboard into an API-safe local JSON draft. Use when: You need a local copy of one live dashboard for review, patching, cloning, or later publish work.
clone-live
Clone one live dashboard into a local draft with optional overrides. Use when: You want to start from an existing live dashboard but give the local draft a new title, UID, or folder target.
list
List dashboard summaries without writing export files. Use when: You want a non-interactive inventory view of live dashboards, optionally with resolved sources or structured output.
export
Export dashboards to raw/, prompt/, and provisioning/ files, with optional history/ artifacts. Use when: You need a local export tree for later import, review, diff, or file-provisioning workflows. Add --include-history when you also need dashboard revision-history artifacts under each exported org scope. The prompt/ lane is for Grafana UI import, not dashboard API import; use dashboard raw-to-prompt when you need to convert ordinary or raw dashboard JSON into prompt JSON.
import
Import dashboard JSON files through the Grafana API. Use when: You have a local export tree or provisioning tree and need to push dashboards back into Grafana, either live or as a dry run. This command consumes raw/ or provisioning/ inputs; it does not consume the Grafana UI prompt/ lane.
patch-file
Patch one local dashboard JSON file in place or write it to a new path. Use when: You need to rewrite dashboard metadata locally before review or publish, without contacting Grafana.
review
Review one local dashboard JSON file without touching Grafana. Use when: You want a local read-only check of a dashboard draft before publishing or importing it.
publish
Publish one local dashboard JSON file through the existing dashboard import pipeline. Use when: A local draft is ready to go live and you want the command to stage or push it through the same import path used by the CLI.
delete
Delete live dashboards by UID or folder path. Use when: You need to remove one dashboard, a folder subtree, or a subtree plus the matched folders themselves.
diff
Compare local dashboard files against live Grafana dashboards. Use when: You want to see what would change before importing or publishing a dashboard bundle.
analyze-export
Analyze dashboard export directories through the canonical dashboard analyze command. Use when: You want to read a local export tree, inspect its structure, or render governance and dependency views without contacting Grafana. Prefer dashboard analyze --input-dir ... in new docs and scripts.
analyze-live
Analyze live Grafana dashboards through the canonical dashboard analyze command. Use when: You need the same analysis views as the local export-tree flow, but sourced from live Grafana instead of a local export tree. Prefer dashboard analyze --url ... in new docs and scripts.
list-vars
List dashboard templating variables and datasource-like choices from live Grafana, a local dashboard file, or a local export tree. Use when: You need to list variable state, feed a screenshot workflow, debug variable-scoped dashboard URLs, or inspect a rendered local dashboard file.
governance-gate
Evaluate governance policy directly against live Grafana or a local export tree, with saved analysis artifacts as an advanced reuse path. Use when: You want a policy pass or fail result before promotion. Prefer direct live or local analysis inputs for the common path; keep governance-json and queries-json for advanced reuse and CI pipelines.
topology
Build a deterministic dashboard topology graph directly from live Grafana or a local export tree, with saved analysis artifacts available for advanced reuse. Use when: You need a graph view of dashboards, folders, variables, datasource links, and optional alert contract data. Prefer --url or --input-dir for the common path; keep artifact inputs for advanced reuse or CI. The command also accepts the graph alias.
screenshot
Open one dashboard in a headless browser and capture image or PDF output. Use when: You need a reproducible dashboard or panel screenshot, especially for docs, incident notes, or visual debugging.

COMMON OPTIONS

--url
Grafana base URL.
--token, --basic-user, --basic-password
shared live Grafana credentials.
--profile
load repo-local defaults from grafana-util.yaml.
--color
control JSON color output for the namespace.

SUCCESS CRITERIA

  • you can tell whether the task is inspect, move, review, or capture before opening a subcommand
  • inventory reads, export/import flows, and review surfaces share the same auth and bundle conventions
  • screenshot and topology paths stay available when you need proof instead of only a final JSON blob

FAILURE CHECKS

  • if browse output looks incomplete, verify the profile, auth flags, and target org before retrying
  • if live inspect or topology output looks stale, confirm you are pointing at the current Grafana and not at an older local export
  • if a result is going into automation, set --output-format explicitly so the downstream step knows the contract

WORKFLOW NOTES

Dashboard export intentionally separates output lanes for different workflows. Treat the raw export tree as the canonical replay or import source unless a command explicitly asks for another lane.

analyze-export and analyze-live are read-only analysis commands, not mutation paths.

browse and screenshot operate against live Grafana state.

EXAMPLES

grafana-util dashboard is the namespace for live dashboard workflows, local draft handling, export/import review, inspection, topology, and screenshots. The same namespace is also available as grafana-util db.

grafana-util dashboard --help

browse: Open the live dashboard tree or a local export tree in an interactive terminal UI.

grafana-util dashboard browse --url http://localhost:3000 --basic-user admin --basic-password admin

fetch-live: Fetch one live dashboard into an API-safe local JSON draft.

grafana-util dashboard fetch-live --profile prod --dashboard-uid cpu-main --output ./cpu-main.json

clone-live: Clone one live dashboard into a local draft with optional overrides.

grafana-util dashboard clone-live --url http://localhost:3000 --basic-user admin --basic-password admin --source-uid cpu-main --output ./cpu-main-clone.json

list: List dashboard summaries without writing export files.

grafana-util dashboard list --profile prod

export: Export dashboards to raw/, prompt/, and provisioning/ files, with optional history/ artifacts.

grafana-util dashboard export --profile prod --output-dir ./dashboards --overwrite

SEE ALSO

grafana-util(1), grafana-util-datasource(1), grafana-util-status(1), grafana-util-overview(1), grafana-util-snapshot(1)