grafana-util-datasource.1

NAME

grafana-util-datasource - datasource catalog, export, import, diff, browse, and mutation workflows

SYNOPSIS

grafana-util datasource [SUBCOMMAND] [OPTIONS]

grafana-util ds [SUBCOMMAND] [OPTIONS]

DESCRIPTION

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

WORKFLOW LANES

- Inspect: types, browse, and list paths for live or local inventory.

- Move: export, import, and diff paths when you are carrying datasource state between environments.

- Review Before Mutate: add, modify, and delete flows before a live datasource changes.

Choose this page when the work might turn into inventory, migration, or a reviewed datasource change and you want to decide the lane first.

BEFORE / AFTER

• Before: data source work is split across Grafana UI edits, API calls, and one-off shell snippets that are hard to review later.
• After: the same lifecycle is grouped into one namespace, so browse, export, diff, and mutation flows can share the same auth and review habits.

SUBCOMMANDS

types

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.

list

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.

browse

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.

export

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.

import

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.

diff

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.

add

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.

modify

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.

delete

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.

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 next step is inventory, export/import, diff, or live mutation before touching a production data source
• repeatable auth and profile settings keep the same commands usable across daily operations and CI
• export and diff flows give you a safer path than editing a live data source first and asking questions later

FAILURE CHECKS

• if browse or list output looks incomplete, confirm whether the token or profile can actually see the target org
• if export or diff results look stale, verify that you are pointing at the correct Grafana and not at an older local bundle
• if a live mutation fails, compare the intended input with the current live data source before retrying the same command

WORKFLOW NOTES

Datasource export follows a masked recovery contract. Treat the canonical export JSON as the replay source. Treat provisioning output as a derived projection for Grafana provisioning workflows.

EXAMPLES

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.

grafana-util datasource --help

types: Show the built-in supported datasource type catalog.

grafana-util datasource types

list: List datasource inventory from live Grafana or a local export bundle.

grafana-util datasource list --url http://localhost:3000 --basic-user admin --basic-password admin --output-format text

browse: Open a live datasource browser against Grafana with in-place modify and delete actions.

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

export: Export live Grafana datasource inventory as normalized JSON plus provisioning files.

grafana-util datasource export --url http://localhost:3000 --basic-user admin --basic-password admin --output-dir ./datasources --overwrite

import: Import datasource inventory through the Grafana API.

grafana-util datasource import --url http://localhost:3000 --basic-user admin --basic-password admin --input-dir ./datasources --dry-run --table

SEE ALSO

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