grafana-util-alert.1

NAME

grafana-util-alert - alert export, import, planning, apply, routing, and authoring workflows

SYNOPSIS

grafana-util alert [SUBCOMMAND] [OPTIONS]

DESCRIPTION

Run the alerting command surface for exporting, importing, diffing, planning, applying, deleting, authoring, and listing Grafana alert resources.

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

WORKFLOW LANES

- Inspect: list-rules, list-contact-points, list-mute-timings, and list-templates.

- Move: export, import, add-rule, clone-rule, add-contact-point, set-route, new-rule, new-contact-point, and new-template.

- Review Before Mutate: diff, plan, apply, and preview-route.

Choose this page when alert work spans rules, routes, contact points, or templates and you want the workflow before the flags.

BEFORE / AFTER

• Before: alert work is often scattered across rule editors, export scripts, and route tweaks without one grouped path from inventory to reviewed apply.
• After: the alert namespace keeps inventory, authoring, diff, planning, and apply in one place so you can read first, then change.

SUBCOMMANDS

export

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.

import

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.

diff

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.

plan

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.

apply

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.

delete

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.

add-rule

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.

clone-rule

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.

add-contact-point

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.

set-route

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.

preview-route

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.

new-rule

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.

new-contact-point

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.

new-template

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.

list-rules

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.

list-contact-points

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

list-mute-timings

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.

list-templates

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.

COMMON OPTIONS

• --profile, --url, --token, --basic-user, --basic-password
• --prompt-password, --prompt-token, --timeout, --verify-ssl
• Use the nested subcommands for export, import, diff, plan, apply, delete, add-rule, clone-rule, add-contact-point, set-route, preview-route, new-rule, new-contact-point, new-template, list-rules, list-contact-points, list-mute-timings, and list-templates.

SUCCESS CRITERIA

• you can tell whether the task belongs to inspect, move, or review-before-mutate before you open a subcommand
• a plan or export can move through review without losing routing context
• the same alert flow can be repeated in CI or during incident follow-up

FAILURE CHECKS

• if an inventory command returns less than expected, confirm whether the auth scope is wide enough for the org or folder you need
• if a review or apply step behaves strangely, inspect the alert plan JSON before assuming the CLI is wrong
• if the result is going to automation, set --output-format explicitly so the downstream step knows the contract

WORKFLOW NOTES

The safest alert workflow is: author or update desired files, inspect the delta with alert plan, then execute only reviewed changes with alert apply.

EXAMPLES

list-rules: List live Grafana alert rules.

grafana-util alert list-rules --profile prod --json

export: Export alerting resources into raw/ JSON files.

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

import: Import alerting resource JSON files through the Grafana API.

grafana-util alert import --url http://localhost:3000 --input-dir ./alerts/raw --replace-existing

diff: Compare local alerting export files against live Grafana resources.

grafana-util alert diff --url http://localhost:3000 --diff-dir ./alerts/raw

plan: Build a staged alert management plan from desired alert resources.

grafana-util alert plan --desired-dir ./alerts/desired

apply: Apply a reviewed alert management plan.

grafana-util alert apply --plan-file ./alert-plan-reviewed.json --approve

SEE ALSO

grafana-util(1), grafana-util-change(1), grafana-util-status(1), grafana-util-overview(1)