grafana-util.1

NAME

grafana-util - unified CLI for Grafana dashboards, alerts, datasources, access, status, and sync workflows

SYNOPSIS

grafana-util [--help] [--version]

grafana-util COMMAND [SUBCOMMAND] [OPTIONS]

grafana-util dashboard [SUBCOMMAND] [OPTIONS]

grafana-util alert [SUBCOMMAND] [OPTIONS]

grafana-util datasource [SUBCOMMAND] [OPTIONS]

grafana-util access [SUBCOMMAND] [OPTIONS]

grafana-util profile [SUBCOMMAND] [OPTIONS]

grafana-util status [SUBCOMMAND] [OPTIONS]

grafana-util overview [SUBCOMMAND] [OPTIONS]

grafana-util change [SUBCOMMAND] [OPTIONS]

grafana-util snapshot [SUBCOMMAND] [OPTIONS]

DESCRIPTION

grafana-util is a unified command-line interface for operating Grafana estates with one executable and one namespaced command shape.

The checked-in English command reference pages under docs/commands/en/ are the higher-level maintainer source for the generated manpage family under docs/man/.

TOP-LEVEL COMMANDS

dashboard

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 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.

alert

Run the alerting command surface for exporting, importing, diffing, planning, applying, deleting, authoring, and listing Grafana alert resources. Use when: Export local alert bundles from Grafana.; Import or diff alert bundles against live Grafana state.; Build and apply a reviewed alert management plan.; Author staged rules, contact points, routes, and templates.; List live alert rules, contact points, mute timings, and templates.

datasource

grafana-util datasource is the namespace for catalog lookup, inventory reads, export/import, diff, and live create/modify/delete workflows. The same namespace is also available as grafana-util ds. Use when: You want to inspect supported datasource types, read inventory from live Grafana or a local bundle, export a datasource bundle, compare a local bundle with Grafana, or create and maintain live datasources.

access

Run the access-management command surface for users, orgs, teams, and service accounts. Use when: List live or local access inventory.; Create, modify, export, import, diff, or delete access resources.; Manage service-account tokens.

profile

list, inspect, validate, add, and initialize repo-local grafana-util profiles. Use when: Want to keep Grafana connection defaults in the current checkout and reuse them with --profile.

status

render shared project-wide staged or live status. Use when: Need the final gate view for exported artifacts or live Grafana state.

overview

summarize staged artifacts into one project-wide overview. Use when: Want a single readout across dashboard, datasource, access, alert, and change artifacts before checking status or promoting changes.

change

task-first staged change workflow with optional live Grafana preview and apply paths. Use when: Need to inspect a staged package, check whether it looks safe to continue, preview what would change, apply an approved preview, or drop into lower-level advanced review contracts.

snapshot

export and review Grafana snapshot inventory bundles. Use when: Want a local snapshot root that captures dashboard, datasource, and access inventory for later inspection.

SUBCOMMAND MANPAGES

.SS dashboard

grafana-util-dashboard-browse(1)

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.

grafana-util-dashboard-fetch-live(1)

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.

grafana-util-dashboard-clone-live(1)

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.

grafana-util-dashboard-list(1)

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.

grafana-util-dashboard-export(1)

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.

grafana-util-dashboard-import(1)

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.

grafana-util-dashboard-patch-file(1)

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.

grafana-util-dashboard-review(1)

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.

grafana-util-dashboard-publish(1)

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.

grafana-util-dashboard-delete(1)

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.

grafana-util-dashboard-diff(1)

Compare local dashboard files against live Grafana dashboards. Use when: You want to see what would change before importing or publishing a dashboard bundle.

grafana-util-dashboard-analyze-export(1)

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.

grafana-util-dashboard-analyze-live(1)

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.

grafana-util-dashboard-list-vars(1)

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.

grafana-util-dashboard-governance-gate(1)

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.

grafana-util-dashboard-topology(1)

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.

grafana-util-dashboard-screenshot(1)

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. .SS alert

grafana-util-alert-export(1)

Export alerting resources into raw/ JSON files. Use when: Capture alert rules, contact points, mute timings, templates, and policies from Grafana.; Build a local bundle before review or import.

grafana-util-alert-import(1)

Import alerting resource JSON files through the Grafana API. Use when: Recreate an exported alert bundle in Grafana.; Update existing alert resources with --replace-existing.; Preview import actions before making changes.

grafana-util-alert-diff(1)

Compare local alerting export files against live Grafana resources. Use when: Check a raw export directory against Grafana before import or plan work.; Render the diff as plain text or structured JSON.

grafana-util-alert-plan(1)

Build a staged alert management plan from desired alert resources. Use when: Review the changes needed to align Grafana with a desired-state alert tree.; Prune live-only alert resources from the plan when needed.; Repair linked rules with dashboard or panel remapping during planning.

grafana-util-alert-apply(1)

Apply a reviewed alert management plan. Use when: Execute a plan that was reviewed outside the live Grafana connection.; Require explicit acknowledgement before touching Grafana.

grafana-util-alert-delete(1)

Delete one explicit alert resource identity. Use when: Remove a single rule, contact point, mute timing, policy tree, or template by identity.; Reset the managed notification policy tree only when you intend to allow it.

grafana-util-alert-add-rule(1)

Author a staged alert rule from the higher-level authoring surface. Use when: Create a new rule under a desired-state alert tree.; Attach labels, annotations, severity, and threshold logic in one command.; Generate a route for the rule unless you explicitly skip it.

grafana-util-alert-clone-rule(1)

Clone an existing staged alert rule into a new authoring target. Use when: Reuse an existing rule as a starting point for a variant.; Override folder, rule group, receiver, or route behavior while cloning.

grafana-util-alert-add-contact-point(1)

Author a staged alert contact point from the higher-level authoring surface. Use when: Create a new contact point under a desired-state alert tree.; Preview the generated file before writing it.

grafana-util-alert-set-route(1)

Author or replace the tool-owned staged notification route. Use when: Replace the managed route with a new receiver and matcher set.; Re-run the command to fully replace the managed route instead of merging fields.

grafana-util-alert-preview-route(1)

Preview the managed route inputs without changing runtime behavior. Use when: Inspect the matcher set you intend to feed into set-route.; Validate route inputs before writing the managed route document.

grafana-util-alert-new-rule(1)

Create a low-level staged alert rule scaffold. Use when: Seed a new rule file in a desired-state tree.; Start from a simple scaffold before filling in rule details.

grafana-util-alert-new-contact-point(1)

Create a low-level staged alert contact point scaffold. Use when: Seed a new contact point file in a desired-state tree.; Start from a scaffold before filling in receiver details.

grafana-util-alert-new-template(1)

Create a low-level staged alert template scaffold. Use when: Seed a new notification template file in a desired-state tree.; Start from a scaffold before adding template content.

grafana-util-alert-list-rules(1)

List live Grafana alert rules. Use when: Inspect alert rule inventory from one org or from all visible orgs.; Render the list in text, table, CSV, JSON, or YAML form.

grafana-util-alert-list-contact-points(1)

List live Grafana alert contact points. Use when: Inspect notification endpoints configured in Grafana.; Switch output between text, table, CSV, JSON, and YAML.

grafana-util-alert-list-mute-timings(1)

List live Grafana mute timings. Use when: Inspect mute timing inventory from one org or from all visible orgs.; Render the list in text, table, CSV, JSON, or YAML form.

grafana-util-alert-list-templates(1)

List live Grafana notification templates. Use when: Inspect template inventory from one org or from all visible orgs.; Render the list in text, table, CSV, JSON, or YAML form. .SS datasource

grafana-util-datasource-types(1)

Show the built-in supported datasource type catalog. Use when: You need to see the canonical datasource type ids that the CLI normalizes and supports for create flows.

grafana-util-datasource-list(1)

List datasource inventory from live Grafana or a local export bundle. Use when: You need a non-interactive inventory of datasources, either from live Grafana for the current org, one explicit org, or across all visible orgs, or from a local export bundle on disk.

grafana-util-datasource-browse(1)

Open a live datasource browser against Grafana with in-place modify and delete actions. Use when: You want an interactive inventory view for inspecting, editing, or deleting live datasources.

grafana-util-datasource-export(1)

Export live Grafana datasource inventory as normalized JSON plus provisioning files. Use when: You need a local datasource bundle for later inspection, diff, or import.

grafana-util-datasource-import(1)

Import datasource inventory through the Grafana API. Use when: You have a local datasource bundle or provisioning tree and want to push it into Grafana, either live or as a dry run.

grafana-util-datasource-diff(1)

Compare datasource inventory from a local bundle against live Grafana and print an operator-summary diff report. Use when: You want a concise live-versus-local difference report before import.

grafana-util-datasource-add(1)

Create one live Grafana datasource through the Grafana API. Use when: You want to create a new datasource directly, or dry-run the create step before applying it.

grafana-util-datasource-modify(1)

Modify one live Grafana datasource through the Grafana API. Use when: A datasource already exists and you need to update its URL, auth, JSON payload, or other live settings.

grafana-util-datasource-delete(1)

Delete one live Grafana datasource through the Grafana API. Use when: A datasource should be removed by UID or by name, either as a dry run or as an acknowledged live delete. .SS access

grafana-util-access-user(1)

List or browse live and local Grafana users, create, modify, export, import, diff, or delete Grafana users. Use when: Inspect users in the current org or in global admin scope.; Inspect users from a live Grafana server or from a local export bundle.; Create or update users with login, email, role, and admin settings.; Export and import user inventory bundles.; Remove users from the org membership or from the global registry.

grafana-util-access-org(1)

List live or local Grafana organizations, create, modify, export, import, diff, or delete Grafana organizations. Use when: Inspect organization inventory and org users.; Inspect organizations from a live Grafana server or from a local export bundle.; Create a new organization or rename an existing one.; Export or import org bundles between environments.; Remove an organization by id or exact name.

grafana-util-access-team(1)

List or browse live and local Grafana teams, create, modify, export, import, diff, or delete Grafana teams. Use when: Inspect team inventory and team memberships.; Inspect teams from a live Grafana server or from a local export bundle.; Create or update team membership and admin assignments.; Export or import team bundles.; Remove a team by id or exact name.

grafana-util-access-service-account(1)

List live or local Grafana service accounts, create, export, import, diff, or delete Grafana service accounts, and manage their tokens. Use when: Inspect service-account inventory.; Inspect service accounts from a live Grafana server or from a local export bundle.; Create or update service-account bundles.; Generate or delete service-account tokens.

grafana-util-access-service-account-token(1)

Add or delete tokens for a Grafana service account. Use when: Create a new service-account token.; Delete an existing service-account token by service-account name or id. .SS profile

grafana-util-profile-list(1)

list profile names from the resolved grafana-util config file. Use when: Need to confirm which profiles are available in the current checkout.

grafana-util-profile-show(1)

show the selected profile as text, table, csv, json, or yaml. Use when: Want to inspect the resolved connection settings before running a live command.

grafana-util-profile-current(1)

show the currently selected profile, resolved config path, auth mode, and secret mode. Use when: Want to confirm which repo-local profile would be used before a live command runs.

grafana-util-profile-validate(1)

validate the selected profile and optionally check Grafana reachability. Use when: Want to confirm profile selection, auth shape, and secret resolution before running a live command.

grafana-util-profile-add(1)

create or replace one named profile without hand-editing grafana-util.yaml. Use when: Want a friendlier path than editing YAML directly, especially for storing reusable auth defaults.

grafana-util-profile-example(1)

print a comment-rich reference config that operators can copy and adapt. Use when: Want one canonical example that explains the supported profile fields and secret storage modes.

grafana-util-profile-init(1)

initialize grafana-util.yaml in the current working directory. Use when: A checkout does not yet have a repo-local profile file and you want the built-in starter template. .SS status

grafana-util-status-staged(1)

render project status from staged artifacts. Use when: Need the machine-readable readiness gate for exported files before apply.

grafana-util-status-live(1)

render project status from live Grafana read surfaces. Use when: Need current Grafana status, optionally deepened with staged context files. .SS overview

grafana-util-overview-live(1)

render the live overview by delegating to the shared status live path. Use when: Need the same live readout that status live uses, but want it under the overview namespace. .SS change

grafana-util-change-advanced(1)

expose lower-level staged contracts and specialized sync workflows. Use when: Need explicit summary, plan, review, preflight, audit, bundle, or promotion handoff documents instead of the task-first lane.

grafana-util-change-summary(1)

summarize local desired sync resources. Use when: Want a quick size check before planning or applying.

grafana-util-change-plan(1)

build a staged sync plan from desired and live state. Use when: Need a reviewable plan before marking work as reviewed or applying it.

grafana-util-change-review(1)

mark a staged sync plan as reviewed. Use when: A plan has been inspected and should carry an explicit review token before apply.

grafana-util-change-audit(1)

audit managed Grafana resources against a checksum lock and current live state. Use when: Need a drift check or want to refresh a lock snapshot.

grafana-util-change-preflight(1)

build a staged sync preflight document from desired resources and optional availability hints. Use when: Need a structural gate before planning or applying.

grafana-util-change-assess-alerts(1)

assess alert sync specs for candidate, plan-only, and blocked states. Use when: Want a focused readout of how alert resources will be classified before bundling or applying.

grafana-util-change-bundle(1)

package exported dashboards, alerting resources, datasource inventory, and metadata into one local source bundle. Use when: Want a single bundle artifact for later sync, review, or preflight steps.

grafana-util-change-bundle-preflight(1)

build a staged bundle-level sync preflight document from a source bundle and target inventory. Use when: Need to compare a source bundle against a target inventory before apply.

grafana-util-change-promotion-preflight(1)

build a staged promotion review handoff from a source bundle and target inventory. Use when: Are preparing a promotion review and want an explicit mapping and availability view. .SS snapshot

grafana-util-snapshot-export(1)

export dashboard, datasource, and access inventory into a local snapshot bundle. Use when: Need a local snapshot root that can be reviewed without Grafana access.

grafana-util-snapshot-review(1)

review a local snapshot inventory without touching Grafana. Use when: Want to inspect an exported snapshot root as table, csv, text, json, yaml, or interactive output. .SS change

grafana-util-change-apply(1)

Turn a reviewed preview into a staged apply intent, or execute it live when you explicitly opt in. Use when: Use this after preview and review are already complete.; Choose the default staged form when you need approval evidence or a machine-readable apply intent.; Add --execute-live only when you are ready to mutate Grafana for real.; --preview-file is the preferred input, while --plan-file still works as a compatibility alias for older staged workflows. .SS change

grafana-util-change-check(1)

Check whether the staged change package looks structurally safe to continue. Use when: Run this after change inspect when you need one readiness gate before preview.; Use this in CI when you want a fast staged readiness decision without building a full plan yet.; Prefer this over status staged when you want to stay in the task-first change lane. .SS change

grafana-util-change-inspect(1)

Inspect the staged change package from discovered or explicit inputs. Use when: Start here when you need the shortest path to understand what the staged package contains.; Use this before change check or change preview when you want to size the package first.; Prefer this over lower-level summary when the staged inputs may come from mixed workspace artifacts instead of only one desired.json. .SS change

grafana-util-change-preview(1)

Preview what would change from discovered or explicit staged inputs. Use when: You want the actionable review artifact for the current staged package.; This is the task-first replacement for the common plan step.; Choose this when the operator question is “what will change?” rather than “which lower-level builder should I run?” .SS dashboard

grafana-util-dashboard-edit-live(1)

Fetch one live dashboard into an external editor, then preview, save, or apply the edited result. Use when: Grafana already has the closest source dashboard and you want to edit that payload directly, while keeping a clear choice between preview-only, saved draft, and direct live apply flows. .SS dashboard

grafana-util-dashboard-history(1)

List, restore, diff, or export dashboard revision history for one dashboard UID, whether it comes from live Grafana or from local history artifacts. Use when: You need to inspect earlier dashboard versions, recover a known-good revision, or export dashboard history into a reusable artifact for review or CI. You can also read the same history back from a single exported artifact or an export tree with included history. .SS dashboard

grafana-util-dashboard-impact(1)

Estimate the blast radius of one datasource directly from live Grafana, a local export tree, or reusable dashboard governance artifacts. Use when: You are about to change, migrate, or troubleshoot one datasource and need to know which dashboards and alert resources depend on it before you touch the live system. Prefer direct live or local inputs for the common path; keep governance artifacts for reuse. .SS dashboard

grafana-util-dashboard-raw-to-prompt(1)

Convert ordinary dashboard JSON or raw/ lane files into Grafana UI prompt JSON with __inputs. Use when: Someone gives you a normal Grafana dashboard export, legacy raw JSON, or a raw/ lane file and you need a prompt-safe file for the Grafana UI Upload JSON flow. .SS dashboard

grafana-util-dashboard-serve(1)

Serve one or more dashboard drafts through a lightweight local preview server. Use when: You are iterating on one dashboard draft, one draft directory, or one generator command and want a local browser surface without publishing back to Grafana after every change. .SS resource

grafana-util-resource-describe(1)

Describe the supported live Grafana resource kinds and selector patterns. Use when: You want to know how the generic read-only resource surface is shaped before you pick resource list or resource get. .SS resource

grafana-util-resource-get(1)

Fetch one supported live Grafana resource by selector. Use when: You need the live payload for one supported resource item and want a simpler generic query than building a full export or inspect workflow. .SS resource

grafana-util-resource-kinds(1)

List the live resource kinds supported by the generic read-only resource query surface. Use when: You need to confirm whether the generic resource query surface already supports the live Grafana resource kind you want to inspect. If you need the selector pattern or endpoint shape, use resource describe instead. .SS resource

grafana-util-resource-list(1)

List one supported live Grafana resource kind. Use when: You need a read-only live inventory for one supported resource kind but do not yet need a higher-level domain workflow. .SS resource

grafana-util-resource(1)

Read a small set of live Grafana resources through a generic read-only query surface. Use when: You need a read-only live lookup before a richer workflow exists in dashboard, alert, datasource, access, or change.

change

Declarative sync planning and gated apply workflows. Sync is the workflow family; the public CLI surface and generated manpages live under grafana-util change and the grafana-util-change*(1) pages.

COMMON CONNECTION AND AUTH PATTERN

Many live Grafana commands accept a shared connection pattern. Prefer repo-local profiles for repeatable work, use direct Basic auth for bootstrap or admin-heavy flows, and use direct tokens for scoped automation where the permission envelope is already understood.

--url

Grafana base URL.

--token

Grafana API token.

--basic-user

HTTP basic-auth username.

--basic-password

HTTP basic-auth password.

--prompt-password

Prompt interactively for the basic-auth password.

--prompt-token

Prompt interactively for the API token.

--profile

Load defaults from the selected repo-local profile in grafana-util.yaml.

--timeout

Override request timeout where supported.

--verify-ssl

Enable or disable TLS certificate verification where supported.

For environment-backed secrets, the usual pattern is to store them in grafana-util.yaml via password_env or token_env, then run the live command with --profile rather than repeating secrets on every command line.

Cross-org inventory such as --all-orgs, plus org or user administration, is usually safest with an admin-backed profile or direct Basic auth. Narrow API tokens may only see a subset of orgs or may be rejected entirely for broader administration surfaces.

CONFIGURATION

grafana-util uses repo-local profile configuration by design.

grafana-util.yaml

Primary profile configuration file. By default it is resolved in the current working directory.

GRAFANA_UTIL_CONFIG

Overrides the default config file path.

.grafana-util.secrets.yaml

Optional encrypted secret store used by profile-backed secret resolution.

.grafana-util.secrets.key

Optional local key file used by the encrypted-file secret store mode.

DOCUMENTATION

To render a checked-in manpage from the repo, run man ./docs/man/<name>.1 on BSD or macOS systems, or man -l docs/man/<name>.1 on GNU/Linux systems whose man implementation supports -l.

This repository provides generated top-level, namespace-level, and per-subcommand manpages sourced from docs/commands/en/.

EXAMPLES

EXAMPLES

Open the unified CLI help and command namespace list.

grafana-util --help

Inspect the dashboard namespace help before choosing a live or file-based workflow.

grafana-util dashboard --help

Render staged or live estate status through a repo-local profile.

grafana-util status live --profile prod --output yaml

Render live estate status with direct Basic auth during bootstrap or break-glass work.

grafana-util status live --url http://localhost:3000 --basic-user admin --prompt-password --output yaml

Summarize live Grafana inventory as JSON under the overview namespace.

grafana-util overview live --url http://localhost:3000 --token $GRAFANA_API_TOKEN --output json

Export live dashboards into a local working tree for review or promotion.

grafana-util dashboard export --url http://localhost:3000 --export-dir ./dashboards

Build a reviewable alert plan from desired-state files before apply.

grafana-util alert plan --desired-dir ./alerts/desired --prune --output json

Export datasource inventory into a normalized local bundle.

grafana-util datasource export --url http://localhost:3000 --export-dir ./datasources --overwrite

SEE ALSO

grafana-util-dashboard(1), grafana-util-alert(1), grafana-util-datasource(1), grafana-util-access(1), grafana-util-profile(1), grafana-util-status(1), grafana-util-overview(1), grafana-util-change(1), grafana-util-snapshot(1), man(1)