This is documentation for the next version of Grafana documentation. For the latest stable release, go to the latest version.
Resource management workflows with gcx
gcx allows you to interact with Grafana resources directly from your terminal. You can browse, inspect, update, and delete resources without using the Grafana UI, and move them between environments as files.
Use this approach if you’re an advanced user and want to manage resources more efficiently, or to integrate Grafana operations into automated workflows.
Available commands
The gcx resources command group includes the following commands:
For every flag of each command, refer to the CLI reference.
Discover resource types
To list the resource types that your Grafana instance serves, including provider-backed types such as SLOs and Synthetic Monitoring checks, run:
gcx resources list-typesThis command requires a connection to Grafana. It also fetches each type’s schema, so add --no-schema for faster results. Pass a selector to filter the list, and use -o wide, -o json, or -o yaml for more detail:
gcx resources list-types incidents -o jsonTo write a manifest from scratch, start from an example. Without arguments, list-examples lists every resource type that has an example. Pass a selector to show the examples for that type:
gcx resources list-examples
gcx resources list-examples slo -o yamlSearch resources by relevance
Use the experimental gcx resources search command to find ranked matches from a phrase:
gcx resources search "kubernetes memory problems"Search returns top matches, without pagination or an exhaustive resource inventory. Scores rank matches in the response.
Prerequisites
You need to enable the Grafana global hybrid search endpoint to use gcx resources search.
- On supported Grafana Cloud stacks,
gcx resources searchcan combine text and semantic matching. - On self-managed deployments with the endpoint, only use text matching. Semantic matching isn’t available on-premises.
Your deployment must have default resource types, or you must select types with --resource.
Search for specific resources
Select resource types and exact folder UIDs for a narrower search:
gcx resources search "memory" \
--resource dashboards.dashboard.grafana.app \
--resource folders.folder.grafana.app \
--folder team-platform \
--limit 10
gcx resources search "memory" --folder generalRepeat --resource to search your selected types instead of the server defaults.
Repeat --folder to match any listed folder UID. Folders match exactly, without descendants; general or --folder '' selects the root folder. The default limit is 50, and the maximum is 200.
Use -o wide to see matching text, or -o json or -o yaml for the full response:
gcx resources search "memory" -o wide
gcx resources search "memory" -o jsonFind and delete dashboards using incorrect data sources
To identify and remove production dashboards relying on non-production data sources, use the command below to list dashboard UIDs along with the data source UIDs used in their panels:
gcx resources get dashboards --context prod | jq '.items | map({ uid: .metadata.name, datasources: .spec.panels | map(.datasource.uid) })'
[
{
"uid": "important-production-dashboard",
"datasources": [
"mimir-prod"
]
},
{
"uid": "test-dashboard-from-dev",
"datasources": [
"mimir-dev"
]
},
{
"uid": "test-dashboard-from-stg",
"datasources": [
"mimir-stg"
]
}
]Next, identify the dashboards that are using unexpected data sources, and delete them:
gcx resources delete dashboards/test-dashboard-from-stg,test-dashboard-from-dev
✔ 2 resources deleted, 0 errorsEdit remote resources
You can edit resources directly from the default editor, without having to pull them first. To do so, run:
gcx resources edit dashboard/edit-me-pleaseThis command opens the default editor set in the EDITOR environment variable, or falls back to ‘vi’ for Linux and ’notepad’ for Windows.
After the editor process terminates, the resource is updated in the Grafana instance targeted by the current context. Edition is cancelled if no changes are written to the file, or if the file after edition is empty.
Validate and preview changes
Before you push local files, check them against the target Grafana instance. gcx resources validate reads resources from disk and asks Grafana to validate each one, without creating or updating anything:
gcx resources validate --path ./resources
gcx resources validate dashboards folders -o jsonTo preview the outcome of a push, add --dry-run:
gcx resources push --path ./resources --dry-runBoth commands use server-side dry-run. Resources that aren’t known to support server-side dry-run aren’t sent, and the summary reports them as skipped instead of verified. If you know a resource honors server-side dry-run, add it with --assume-server-dry-run, for example --assume-server-dry-run alertrules.rules.alerting.grafana.app.
Migrate resources between environments
Grafana resources can be migrated from one environment to another, for example from a development to production environment.
You need to configure one context per environment. In this example scenario, use dev for the development environment and prod for production.
- Make changes to dashboards and other resources using the Grafana UI in your development instance.
- Pull those resources from the development environment to your local machine:
gcx resources pull --context dev # Add `-o yaml` export resources as YAML - Push the resources to production:
gcx resources push --context prod
Note
Resources are pulled and pushed from the
./resourcesdirectory by default. Configure this path with the--path/-pflags.
Name pulled files by title
By default, gcx resources pull names each file after the resource’s metadata.name, which is usually a generated UID such as adkg9x2. These names are hard to recognize when you browse a directory or review a Git diff.
To name files after the resource title instead, add --filename-by=title:
gcx resources pull dashboards --filename-by=title --path ./dashboard-backupFor example, a dashboard titled Ventas Overview is saved as ventas-overview.json instead of adkg9x2.json. Only the filename changes: the file still contains the original metadata.name, so push and validate treat it exactly like a file pulled by name.
How titles become filenames
gcx converts the title to lowercase letters, digits, and hyphens, and limits it to 100 characters. If a resource has no usable title, gcx uses its metadata.name instead.
If two resources produce the same filename, for example two dashboards titled Overview, gcx appends each resource’s metadata.name to keep them apart, such as overview-adkg9x2.json and overview-b71fq0m.json. gcx never overwrites a file that belongs to a different resource. For the complete rules, refer to the file naming rules.
Remove stale files before you push
gcx resources pull writes files but never deletes them. If a resource is renamed, or you switch between --filename-by=name and --filename-by=title, the directory can end up with two files for the same resource: the old one and the new one.
When you pull with --filename-by=title, gcx warns on stderr about files that hold the same resource under a different name. A pull in name mode does not check for this. Before you push, remove the outdated files, for example with git rm, or pull into an empty directory.
Back up and restore resources
Follow this workflow to back up all Grafana resources from one instance and later restore them. This can be useful to replicate a configuration or perform disaster recovery.
- Ensure the current context points to the Grafana instance to backup/restore:
gcx config use-context YOUR_CONTEXT # for example "prod" - Pull all resources from your target environment:
gcx resources pull --path ./backup-prod # Add `-o yaml` to export resources as YAML - Save the exported resources to version control or cloud storage.
- Push the resources to restore them:
gcx resources push --path ./backup-prod
Incident descriptions
Incident descriptions remain visible in gcx resources get and
gcx irm incidents list results.
gcx resources pull omits descriptions from saved manifests. These backups
cannot restore incident descriptions.
Old backup files can contain spec.description. Remove that field before you
push the file to create an incident or to change an incident with a different
description. You can update other fields when spec.description is absent or equal to the current value.


