### Install grafanactl from Source using Go

Source: https://github.com/grafana/grafanactl/blob/main/docs/installation.md

Use this command to install the grafanactl executable from source. Ensure you have Go v1.24 or greater installed.

```shell
go install github.com/grafana/grafanactl/cmd/grafanactl@latest
```

--------------------------------

### Install grafanactl to GOPATH/bin

Source: https://github.com/grafana/grafanactl/blob/main/AGENTS.md

Install the built binary to your Go binary path for easy command-line access.

```bash
make install
```

--------------------------------

### Get Everything

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_get.md

Retrieve all resources of all kinds. Use with caution as this can return a large amount of data.

```bash
grafanactl resources get dashboards/foo
```

--------------------------------

### Start the test environment

Source: https://github.com/grafana/grafanactl/blob/main/CONTRIBUTING.md

Use the Make target to bring up the Grafana and MySQL services for testing. This command waits for services to be healthy.

```bash
$ make test-env-up
```

--------------------------------

### Start the test environment manually

Source: https://github.com/grafana/grafanactl/blob/main/CONTRIBUTING.md

Manually start the Docker Compose services in detached mode.

```bash
$ docker-compose up -d
```

--------------------------------

### Add a package to devbox

Source: https://github.com/grafana/grafanactl/blob/main/CONTRIBUTING.md

Install a specific package, like Go version 1.24, into the devbox environment.

```bash
$ devbox add go@1.24
```

--------------------------------

### List Grafanactl Contexts

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_config_list-contexts.md

Use this command to view all configured contexts in your grafanactl setup. No arguments are required.

```bash
grafanactl config list-contexts
```

--------------------------------

### Get All Resources

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_get.md

Retrieve all resources of a specific kind. This is useful for a broad overview or when specific resource names are unknown.

```bash
grafanactl resources get dashboards
```

```bash
grafanactl resources get dashboards folders
```

--------------------------------

### Serve Grafana Resources Locally

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_serve.md

Serve Grafana resources from a specified directory. This command starts a local server to explore and review resources.

```bash
grafanactl resources serve ./resources
```

--------------------------------

### Serve Grafana resources locally for live preview

Source: https://context7.com/grafana/grafanactl/llms.txt

Starts a local HTTP server to expose local resource files to a Grafana instance for live preview. Supports watch mode for automatic reloads on file changes and script-driven generation. Useful for code-driven dashboard development.

```shell
# Serve resources from a directory with file-watching enabled (default)
grafanactl resources serve ./resources

```

```shell
# Serve without watching for changes
grafanactl resources serve ./resources --no-watch

```

```shell
# Serve on a custom port
grafanactl resources serve ./resources --port 9090

```

```shell
# Serve resources generated by a script; reload on source change
grafanactl resources serve \
  --script 'go run dashboard-generator/*.go' \
  --watch ./dashboard-generator \
  --script-format yaml

```

```shell
# Dashboards-as-code full development loop
grafanactl config use-context dev
grafanactl resources serve \
  --script 'go run scripts/generate-dashboard.go' \
  --watch ./scripts
# → Edit scripts/generate-dashboard.go, dashboard auto-reloads in Grafana UI

# When satisfied, generate manifest files and push
go run scripts/generate-dashboard.go --generate-resource-manifests --output ./resources
grafanactl resources push --context prod -p ./resources

```

--------------------------------

### Options Pattern for Command Structs

Source: https://github.com/grafana/grafanactl/blob/main/CLAUDE.md

Defines a struct for command options with setup and validation methods. Use this pattern to encapsulate command-line arguments and their validation logic.

```go
type pushOpts struct {
    Paths []string
    MaxConcurrent int
    // ...
}

func (opts *pushOpts) setup(flags *pflag.FlagSet) { ... }
func (opts *pushOpts) Validate() error { ... }
```

--------------------------------

### Grafana Configuration File Schema

Source: https://context7.com/grafana/grafanactl/llms.txt

Example of the grafanactl configuration file structure in YAML format. Shows how to define contexts, server details, and authentication methods.

```yaml
# $HOME/.config/grafanactl/config.yaml
contexts:
  default:
    grafana:
      server: http://localhost:3000    # Required
      org-id: 1                        # Required for on-prem; omit for Grafana Cloud
      token: glsa_xxxxxxxxxxxxxxxxxxxx # Preferred auth method (takes precedence over user/password)
      # user: admin                    # Basic auth alternative
      # password: secret
  prod:
    grafana:
      server: https://myorg.grafana.net
      stack-id: 123456                 # Required for Grafana Cloud; omit for on-prem
      token: glsa_yyyyyyyyyyyyyyyyyyyy
      tls:
        insecure-skip-verify: false
        ca-data: <base64-encoded-PEM>
current-context: default

```

--------------------------------

### Clean Build Artifacts and Dependencies

Source: https://github.com/grafana/grafanactl/blob/main/AGENTS.md

Remove generated build artifacts and downloaded dependencies to start with a clean slate.

```bash
make clean
```

--------------------------------

### Edit a Dashboard

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_edit.md

This example shows how to edit a specific dashboard identified by 'dashboard/foo'.

```bash
grafanactl resources dashboard/foo
```

--------------------------------

### Build and Test grafanactl

Source: https://github.com/grafana/grafanactl/blob/main/CLAUDE.md

Standard make targets for building the grafanactl binary, running all tests, or testing specific packages. Also includes commands for installing the binary and running linters.

```bash
make build
```

```bash
make tests
```

```bash
go test -v ./internal/config
```

```bash
make install
```

```bash
make lint
```

```bash
make all
```

--------------------------------

### Edit a Dashboard Using an Alternative Editor

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_edit.md

This example demonstrates how to use an alternative editor, 'nvim', to edit the dashboard by setting the EDITOR environment variable.

```bash
EDITOR=nvim grafanactl resources dashboard/foo
```

--------------------------------

### Get Multiple Resource Kinds with Specific Instances

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_get.md

Retrieve specific instances across multiple resource kinds. This allows for fetching related resources in a single command.

```bash
grafanactl resources get dashboards/foo folders/qux
```

```bash
grafanactl resources get dashboards/foo,bar folders/qux,quux
```

--------------------------------

### Get Specific Resources by Name

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_get.md

Retrieve one or more specific resources by their names for a given kind. This is useful for targeting exact resources.

```bash
grafanactl resources get dashboards/foo
```

```bash
grafanactl resources get dashboards/foo,bar
```

--------------------------------

### Get Multiple Resource Kinds with Long Kind Format and Version

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_get.md

Retrieve specific instances across multiple resource kinds using their long kind format and API version. This provides the most granular control for fetching resources.

```bash
grafanactl resources get dashboards.v1alpha1.dashboard.grafana.app/foo folders.v1alpha1.folder.grafana.app/qux
```

--------------------------------

### Run One-off Commands with Devbox

Source: https://github.com/grafana/grafanactl/blob/main/AGENTS.md

Execute single commands within the devbox environment to verify tool installations or run specific tasks.

```bash
devbox run go version
```

--------------------------------

### Pull all instances of specific resource kinds

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_pull.md

Retrieve all instances for one or more specified resource kinds. This is useful for backing up all dashboards or folders, for example.

```bash
grafanactl resources pull dashboards
```

```bash
grafanactl resources pull dashboards folders
```

--------------------------------

### Get Resources with Long Kind Format and Version

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_get.md

Retrieve resources using the long kind format including the API version. This is useful for targeting resources of a specific API version.

```bash
grafanactl resources get dashboards.v1alpha1.dashboard.grafana.app/foo
```

```bash
grafanactl resources get dashboards.v1alpha1.dashboard.grafana.app/foo,bar
```

--------------------------------

### Get Resources with Long Kind Format

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_get.md

Retrieve resources using the long kind format, which includes the group and kind. This provides more specificity.

```bash
grafanactl resources get dashboard.dashboards/foo
```

```bash
grafanactl resources get dashboard.dashboards/foo,bar
```

--------------------------------

### Get Multiple Resource Kinds with Long Kind Format

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_get.md

Retrieve specific instances across multiple resource kinds using their long kind format. This offers precise selection across different resource types.

```bash
grafanactl resources get dashboard.dashboards/foo folder.folders/qux
```

```bash
grafanactl resources get dashboard.dashboards/foo,bar folder.folders/qux,quux
```

--------------------------------

### Get Grafana Resources

Source: https://context7.com/grafana/grafanactl/llms.txt

Fetch and display specific resources from Grafana. Supports flexible selectors and multiple output formats. Resources are not saved to disk.

```shell
# Get a single dashboard by UID
grafanactl resources get dashboards/my-dashboard

# Get all dashboards as JSON and filter with jq
grafanactl resources get dashboards -o json | jq '.items[].metadata.name'

# Get multiple specific dashboards
grafanactl resources get dashboards/foo,bar

# Get dashboards and folders together
grafanactl resources get dashboards/foo folders/my-folder

# Get all dashboards from the production context and extract datasource info
grafanactl resources get dashboards --context prod -o json | \
  jq '.items | map({ uid: .metadata.name, datasources: [.spec.panels[].datasource.uid] })'
# Output:
# [
#   { "uid": "prod-overview", "datasources": ["mimir-prod"] },
#   { "uid": "test-leftover", "datasources": ["mimir-dev"] }
# ]

# Use fully-qualified API group format
grafanactl resources get dashboards.v1alpha1.dashboard.grafana.app/my-dashboard -o yaml

# Continue on errors instead of stopping
grafanactl resources get dashboards --on-error ignore
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/grafana/grafanactl/blob/main/AGENTS.md

Serve the project documentation locally with live reload capabilities for easy previewing.

```bash
make serve-docs
```

--------------------------------

### Generate Configuration File Reference

Source: https://github.com/grafana/grafanactl/blob/main/AGENTS.md

Create documentation that outlines the structure and options for configuration files.

```bash
make config-reference
```

--------------------------------

### Get a dashboard from Grafana

Source: https://github.com/grafana/grafanactl/blob/main/CONTRIBUTING.md

Retrieve a specific dashboard from Grafana using its identifier and the grafanactl resource get command.

```bash
$ devbox run go run ./cmd/grafanactl --config testdata/integration-test-config.yaml resources get dashboards/test-dashboard
```

--------------------------------

### Generate and Build Documentation

Source: https://github.com/grafana/grafanactl/blob/main/AGENTS.md

Create and build all project documentation, ensuring it is up-to-date.

```bash
make docs
```

--------------------------------

### Build grafanactl Binary

Source: https://github.com/grafana/grafanactl/blob/main/AGENTS.md

Build the grafanactl executable and place it in the bin/grafanactl location.

```bash
make build
```

--------------------------------

### Specify configuration file

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_push.md

Use the --config flag to specify the path to the configuration file.

```bash
grafanactl resources push --config /path/to/config.yaml
```

--------------------------------

### View all test environment logs

Source: https://github.com/grafana/grafanactl/blob/main/CONTRIBUTING.md

Display logs from all services in the test environment using the Make target.

```bash
$ make test-env-logs
```

--------------------------------

### Enter the devbox shell

Source: https://github.com/grafana/grafanactl/blob/main/CONTRIBUTING.md

Access a shell with all necessary development tools pre-installed. Exit with 'exit' or CTRL+D.

```bash
$ devbox shell
```

--------------------------------

### Validate Specific Resource Kind

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_validate.md

To validate only a particular type of resource, specify the resource kind after the command. For example, to validate only dashboards.

```bash
grafanactl resources validate dashboards
```

--------------------------------

### Specify resource paths

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_push.md

Use the -p or --path flag to specify directories from which to read resources for the push operation. Defaults to './resources'.

```bash
grafanactl resources push -p /path/to/resources
```

```bash
grafanactl resources push --path ./my-resources,./other-resources
```

--------------------------------

### Push Resources to Production Environment

Source: https://github.com/grafana/grafanactl/blob/main/docs/guides/manage-resources.md

Use this command to push resources to a specified production context. Resources are pulled and pushed from the `./resources` directory by default, but this path can be configured with `--path`/`-p` flags.

```shell
grafanactl resources push --context prod
```

--------------------------------

### List Grafana API Resources with Configuration File

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_list.md

Specify a custom configuration file to use for the `grafanactl` command.

```bash
grafanactl resources list --config "/path/to/config.yaml"
```

--------------------------------

### Serve and Watch Dashboard Generation Script

Source: https://github.com/grafana/grafanactl/blob/main/docs/guides/dashboards-as-code.md

Use `grafanactl resources serve` to preview dashboard output locally. It requires a context to be set and watches for changes in a specified directory.

```shell
grafanactl config use-context YOUR_CONTEXT  # for example "dev"
```

```shell
grafanactl resources serve --script 'go run scripts/generate-dashboard.go' --watch './scripts'
```

--------------------------------

### Run All Checks

Source: https://github.com/grafana/grafanactl/blob/main/AGENTS.md

Perform a comprehensive check of the project, including linting, tests, building, and documentation.

```bash
make all
```

--------------------------------

### Manage grafanactl Documentation

Source: https://github.com/grafana/grafanactl/blob/main/CLAUDE.md

Commands for generating, building, and serving documentation locally. Includes targets for CLI reference, environment variables, and configuration files, as well as checking for documentation drift.

```bash
make docs
```

```bash
make cli-reference
```

```bash
make env-var-reference
```

```bash
make config-reference
```

```bash
make serve-docs
```

```bash
make reference-drift
```

--------------------------------

### Serve dashboards with live reload

Source: https://github.com/grafana/grafanactl/blob/main/CONTRIBUTING.md

Develop dashboards locally with live reload enabled. Access the development server via the URL shown in the output.

```bash
$ devbox run go run ./cmd/grafanactl --config testdata/integration-test-config.yaml resources serve test-dashboard.yaml
```

--------------------------------

### Delete dashboards by jq filter

Source: https://context7.com/grafana/grafanactl/llms.txt

Deletes dashboards on a production environment that match a specific jq filter, typically used for removing dashboards referencing incorrect data sources. This command pipes the output of 'get dashboards' to 'jq' for filtering and then uses 'xargs' to pass the dashboard names to the 'delete' command.

```shell
grafanactl resources get dashboards --context prod -o json | 
  jq -r '.items[] | select(.spec.panels[].datasource.uid == "mimir-dev") | .metadata.name' | 
  xargs -I{} grafanactl resources delete dashboards/{}

```

--------------------------------

### Push resources by kind

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_push.md

Push all instances of specific resource kinds, such as dashboards or folders.

```bash
grafanactl resources push dashboards
```

```bash
grafanactl resources push dashboards folders
```

--------------------------------

### List available resources in grafanactl

Source: https://github.com/grafana/grafanactl/blob/main/CONTRIBUTING.md

Show all resources that grafanactl can manage, using the specified test configuration.

```bash
$ devbox run go run ./cmd/grafanactl --config testdata/integration-test-config.yaml resources list
```

--------------------------------

### Generate Environment Variable Reference

Source: https://github.com/grafana/grafanactl/blob/main/AGENTS.md

Generate documentation detailing the environment variables used by the tool.

```bash
make env-var-reference
```

--------------------------------

### Push multiple resource kinds with instances

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_push.md

Push specific instances across multiple resource kinds. Separate kinds and instances as shown.

```bash
grafanactl resources push dashboards/foo folders/qux
```

```bash
grafanactl resources push dashboards/foo,bar folders/qux,quux
```

--------------------------------

### List Grafana API Resources

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_list.md

Use this command to list all available resources in Grafana. This is the basic usage of the command.

```bash
grafanactl resources list
```

--------------------------------

### Generate CLI Reference Documentation

Source: https://github.com/grafana/grafanactl/blob/main/AGENTS.md

Specifically generate the reference documentation for the command-line interface.

```bash
make cli-reference
```

--------------------------------

### Grafana Configuration Check Help Option

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_config_check.md

Use the -h or --help flag with the check command to display help information about its usage and available options.

```bash
grafanactl config check -h
```

--------------------------------

### grafanactl config current-context Options

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_config_current-context.md

This command accepts a help flag to display usage information.

```bash
  -h, --help   help for current-context
```

--------------------------------

### View grafanactl configuration

Source: https://github.com/grafana/grafanactl/blob/main/CONTRIBUTING.md

Display the current configuration of grafanactl using the test configuration file.

```bash
$ devbox run go run ./cmd/grafanactl --config testdata/integration-test-config.yaml config view
```

--------------------------------

### Pull All Resources for Backup

Source: https://github.com/grafana/grafanactl/blob/main/docs/guides/manage-resources.md

Pull all resources from the target environment to a specified local path for backup. Add `-o yaml` to export resources as YAML.

```shell
grafanactl resources pull --path ./backup-prod # Add `-o yaml` to export resources as YAML
```

--------------------------------

### Vendor Dependencies

Source: https://github.com/grafana/grafanactl/blob/main/AGENTS.md

Download and vendor project dependencies to ensure reproducible builds.

```bash
make deps
```

--------------------------------

### grafanactl config current-context Synopsis

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_config_current-context.md

The synopsis shows the basic command structure for displaying the current context.

```bash
grafanactl config current-context [flags]
```

--------------------------------

### Add Packages with Devbox

Source: https://github.com/grafana/grafanactl/blob/main/AGENTS.md

Add new packages, such as a specific Go version, to your devbox environment.

```bash
devbox add go@1.24
```

--------------------------------

### Push single resource kind with instances

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_push.md

Push specific instances of a single resource kind. You can specify one or more instances by name.

```bash
grafanactl resources push dashboards/foo
```

```bash
grafanactl resources push dashboards/foo,bar
```

--------------------------------

### Specify context

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_push.md

Use the --context flag to specify the name of the context to use.

```bash
grafanactl resources push --context production
```

--------------------------------

### Push all resources

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_push.md

Use this command to push all available resources to Grafana.

```bash
grafanactl resources push
```

--------------------------------

### Pull multiple resource kinds with specific instances

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_pull.md

Retrieve specific instances across multiple resource kinds in a single command. Separate resource kinds and instances as needed.

```bash
grafanactl resources pull dashboards/foo folders/qux
```

```bash
grafanactl resources pull dashboards/foo,bar folders/qux,quux
```

--------------------------------

### Manage Project Dependencies

Source: https://github.com/grafana/grafanactl/blob/main/CLAUDE.md

Use these make targets to vendor project dependencies or clean build artifacts and dependencies.

```bash
make deps
```

```bash
make clean
```

--------------------------------

### View MySQL service logs

Source: https://github.com/grafana/grafanactl/blob/main/CONTRIBUTING.md

Follow the logs of the MySQL service in real-time.

```bash
$ docker-compose logs -f mysql
```

--------------------------------

### Enter Devbox Shell

Source: https://github.com/grafana/grafanactl/blob/main/AGENTS.md

Use this command to enter the devbox shell, which includes all necessary tools for development.

```bash
devbox shell
```

--------------------------------

### grafanactl config view options

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_config_view.md

Available options for the grafanactl config view command include help, minify, output format, and raw display.

```bash
-h, --help            help for view
      --minify          Remove all information not used by current-context from the output
  -o, --output string   Output format. One of: json, yaml (default "yaml")
      --raw             Display sensitive information
```

--------------------------------

### View Grafana logs for troubleshooting

Source: https://github.com/grafana/grafanactl/blob/main/CONTRIBUTING.md

Check the logs of the Grafana service to diagnose startup or health issues.

```bash
$ docker-compose logs grafana
```

--------------------------------

### Run All Tests

Source: https://github.com/grafana/grafanactl/blob/main/AGENTS.md

Execute all tests within the project to ensure code quality and functionality.

```bash
make tests
```

--------------------------------

### List Grafana Resource Types

Source: https://context7.com/grafana/grafanactl/llms.txt

Discover and list all available resource kinds in a Grafana instance. Use -o json for programmatic consumption.

```shell
# List all available resource types (default text output)
grafanactl resources list

# List as JSON for programmatic use
grafanactl resources list -o json

# List against a specific context
grafanactl resources list --context prod
```

--------------------------------

### Enter Devbox Shell

Source: https://github.com/grafana/grafanactl/blob/main/CLAUDE.md

Use this command to enter the devbox shell, which includes all necessary tools for development. Alternatively, run one-off commands within the devbox environment.

```bash
devbox shell
```

```bash
devbox run go version
```

```bash
devbox add go@1.24
```

--------------------------------

### Run Linter

Source: https://github.com/grafana/grafanactl/blob/main/AGENTS.md

Execute the linter to check for code style and potential issues.

```bash
make lint
```

--------------------------------

### List Grafana API Resources with Specific Context

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_list.md

Use a specific context from the configuration file for the `grafanactl` command.

```bash
grafanactl resources list --context "my-grafana-context"
```

--------------------------------

### Push multiple resource kinds with versioned long format

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_push.md

Push resources using the versioned long kind format for multiple resource kinds and their instances.

```bash
grafanactl resources push dashboards.v1alpha1.dashboard.grafana.app/foo folders.v1alpha1.folder.grafana.app/qux
```

--------------------------------

### Generate Dashboard Resource Manifests

Source: https://github.com/grafana/grafanactl/blob/main/docs/guides/dashboards-as-code.md

Generate dashboard manifest files using a Go script. Specify the output directory for the generated files.

```shell
go run scripts/generate-dashboard.go --generate-resource-manifests --output './resources'
```

--------------------------------

### Pull Resources from Development Environment

Source: https://github.com/grafana/grafanactl/blob/main/docs/guides/manage-resources.md

Use this command to pull resources from a specified development context. Add `-o yaml` to export resources as YAML.

```shell
grafanactl resources pull --context dev # Add `-o yaml` export resources as YAML
```

--------------------------------

### Pull single resource kind with one or more instances

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_pull.md

Fetch specific instances of a single resource kind. You can list multiple instances separated by commas.

```bash
grafanactl resources pull dashboards/foo
```

```bash
grafanactl resources pull dashboards/foo,bar
```

--------------------------------

### View Grafana service logs

Source: https://github.com/grafana/grafanactl/blob/main/CONTRIBUTING.md

Follow the logs of the Grafana service in real-time.

```bash
$ docker-compose logs -f grafana
```

--------------------------------

### Pull all resources

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_pull.md

Use this command to pull all available resources from Grafana. This is a general-purpose command for backing up or inspecting all Grafana configurations.

```bash
grafanactl resources pull
```

--------------------------------

### Stop the test environment

Source: https://github.com/grafana/grafanactl/blob/main/CONTRIBUTING.md

Use the Make target to shut down the Grafana and MySQL services.

```bash
$ make test-env-down
```

--------------------------------

### List Grafana API Resources with Output Formatting

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_list.md

Specify the output format for the list of Grafana API resources. Supported formats include json, text, wide, and yaml.

```bash
grafanactl resources list -o json
```

--------------------------------

### Configure Default Grafana Context

Source: https://context7.com/grafana/grafanactl/llms.txt

Sets up a default context for a local Grafana instance, including server URL, organization ID, and a service account token. This is useful for local development and testing.

```shell
grafanactl config set contexts.default.grafana.server http://localhost:3000
```

```shell
grafanactl config set contexts.default.grafana.org-id 1
```

```shell
grafanactl config set contexts.default.grafana.token glsa_xxxxxxxxxxxxxxxxxxxx
```

--------------------------------

### Check Grafana Configuration

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_config_check.md

Run this command to perform a check on your current Grafana configuration file for any potential issues or inconsistencies.

```bash
grafanactl config check
```

--------------------------------

### Push single resource kind with versioned long format

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_push.md

Specify a single resource kind using its versioned long format and push specific instances.

```bash
grafanactl resources push dashboards.v1alpha1.dashboard.grafana.app/foo
```

```bash
grafanactl resources push dashboards.v1alpha1.dashboard.grafana.app/foo,bar
```

--------------------------------

### List dashboard UIDs and their data sources

Source: https://github.com/grafana/grafanactl/blob/main/docs/guides/explore-modify-resources.md

Use this command to list dashboard UIDs and the data source UIDs used in their panels. This helps identify dashboards relying on incorrect data sources.

```shell
grafanactl resources get dashboards --context prod | jq '.items | map({ uid: .metadata.name, datasources: .spec.panels | map(.datasource.uid)  })'
```

```json
[
   {
      "uid": "important-production-dashboard",
      "datasources": [
         "mimir-prod"
      ]
   },
   {
      "uid": "test-dashboard-from-dev",
      "datasources": [
         "mimir-dev"
      ]
   },
   {
      "uid": "test-dashboard-from-stg",
      "datasources": [
         "mimir-stg"
      ]
   }
]
```

--------------------------------

### Run Tests for Specific Package

Source: https://github.com/grafana/grafanactl/blob/main/AGENTS.md

Focus testing efforts on a particular package by specifying its path.

```bash
go test -v ./internal/config
```

--------------------------------

### Simulate resource push with dry-run

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_push.md

Use the --dry-run flag to simulate the push operation without making any actual changes to Grafana resources.

```bash
grafanactl resources push --dry-run
```

--------------------------------

### List Grafana API Resources with Verbose Output

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_list.md

Enable verbose output for the list of Grafana API resources. Multiple `-v` flags increase verbosity up to a maximum of 3.

```bash
grafanactl resources list -v
```

--------------------------------

### Push single resource kind with long format

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_push.md

Use the long kind format for specifying a single resource kind and its instances.

```bash
grafanactl resources push dashboard.dashboards/foo
```

```bash
grafanactl resources push dashboard.dashboards/foo,bar
```

--------------------------------

### Pull single resource kind using long kind format with version

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_pull.md

Specify the resource kind using its long format and include the API version. This provides the most precise way to select resources.

```bash
grafanactl resources pull dashboards.v1alpha1.dashboard.grafana.app/foo
```

```bash
grafanactl resources pull dashboards.v1alpha1.dashboard.grafana.app/foo,bar
```

--------------------------------

### Serve Resources Generated by a Script

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_serve.md

Serve Grafana resources generated by an external script. The script's output is expected in YAML format, and changes in the specified paths will trigger re-execution of the script.

```bash
grafanactl resources serve --script 'go run dashboard-generator/*.go' --watch ./dashboard-generator --script-format yaml
```

--------------------------------

### Check for Documentation Drift

Source: https://github.com/grafana/grafanactl/blob/main/AGENTS.md

Verify that generated documentation has not drifted from its source or expected state.

```bash
make reference-drift
```

--------------------------------

### Enable Kubernetes Dashboards Feature Toggle

Source: https://github.com/grafana/grafanactl/blob/main/docs/guides/dashboards-as-code.md

To use `grafanactl resources serve`, enable the `kubernetesDashboards` feature toggle in your `config.ini` file.

```ini
[feature_toggles]
kubernetesDashboards = true
```

--------------------------------

### Push Resources for Restore

Source: https://github.com/grafana/grafanactl/blob/main/docs/guides/manage-resources.md

Push resources from a specified local path to restore them to the Grafana instance. This path should contain the previously backed-up resources.

```shell
grafanactl resources push --path ./backup-prod
```

--------------------------------

### Push multiple resource kinds with long format

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_push.md

Use the long kind format to specify multiple resource kinds and their instances for pushing.

```bash
grafanactl resources push dashboard.dashboards/foo folder.folders/qux
```

```bash
grafanactl resources push dashboard.dashboards/foo,bar folder.folders/qux,quux
```

--------------------------------

### Include managed resources in push

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_push.md

Use the --include-managed flag to include resources that are managed by other tools in the push operation.

```bash
grafanactl resources push --include-managed
```

--------------------------------

### Push a dashboard to Grafana

Source: https://github.com/grafana/grafanactl/blob/main/CONTRIBUTING.md

Create or update a dashboard in Grafana using a local YAML file and the grafanactl resource push command.

```bash
$ devbox run go run ./cmd/grafanactl --config testdata/integration-test-config.yaml resources push test-dashboard.yaml
```

--------------------------------

### Create a New Staging Context for Grafana CLI

Source: https://github.com/grafana/grafanactl/blob/main/docs/configuration.md

Create a new context named 'staging' for the Grafana CLI, specifying the server URL and organization ID. This allows for managing separate Grafana environments.

```shell
grafanactl config set contexts.staging.grafana.server https://staging.grafana.example
grafanactl config set contexts.staging.grafana.org-id 1
```

--------------------------------

### Processor Interface for Resource Transformations

Source: https://github.com/grafana/grafanactl/blob/main/CLAUDE.md

Defines a Processor interface for transforming resources. Implement this interface for operations like adding manager fields or stripping server fields, enabling a composable pipeline.

```go
type Processor interface {
    Process(*Resource) error
}

```

--------------------------------

### grafanactl Global Options

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl.md

These are the global options available for the grafanactl command. They control general behavior like help output, colorization, and verbosity.

```bash
  -h, --help            help for grafanactl
      --no-color        Disable color output
  -v, --verbose count   Verbose mode. Multiple -v options increase the verbosity (maximum: 3).
```

--------------------------------

### Set Grafana Environment Variables

Source: https://context7.com/grafana/grafanactl/llms.txt

Configure a Grafana context using environment variables. Useful for ephemeral environments like CI.

```shell
export GRAFANA_SERVER='https://myorg.grafana.net'
export GRAFANA_TOKEN='glsa_xxxxxxxxxxxxxxxxxxxx'
export GRAFANA_STACK_ID='123456'   # Grafana Cloud
# export GRAFANA_ORG_ID='1'        # On-prem alternative to STACK_ID
# export GRAFANA_USER='admin'       # Basic auth
# export GRAFANA_PASSWORD='secret'  # Basic auth

grafanactl resources list
```

--------------------------------

### Configure Production Grafana Cloud Context

Source: https://context7.com/grafana/grafanactl/llms.txt

Configures a production context for a Grafana Cloud stack, specifying the server URL, stack ID, and a service account token. This is for connecting to remote Grafana instances.

```shell
grafanactl config set contexts.prod.grafana.server https://myorg.grafana.net
```

```shell
grafanactl config set contexts.prod.grafana.stack-id 123456
```

```shell
grafanactl config set contexts.prod.grafana.token glsa_yyyyyyyyyyyyyyyyyyyy
```

--------------------------------

### Pull Grafana Resources to Disk

Source: https://context7.com/grafana/grafanactl/llms.txt

Download resources from Grafana to a local directory for backups, version control, or migrations. Defaults to ./resources.

```shell
# Pull all resources into ./resources (JSON format by default)
grafanactl resources pull

# Pull all resources as YAML
grafanactl resources pull -o yaml

# Pull to a custom directory
grafanactl resources pull --path ./backup-2024-01-15

# Pull only dashboards and folders
grafanactl resources pull dashboards folders

# Pull a specific dashboard
grafanactl resources pull dashboards/my-dashboard

# Pull from the dev context into a migration staging directory
grafanactl resources pull --context dev --path ./migration --output yaml

# Include resources managed by other tools (excluded by default)
grafanactl resources pull --include-managed
```

--------------------------------

### Pull multiple resource kinds using long kind format with version

Source: https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_pull.md

The most specific way to pull multiple resource kinds, using their long format and API versions. This ensures you are targeting the exact resources you intend to retrieve.

```bash
grafanactl resources pull dashboards.v1alpha1.dashboard.grafana.app/foo folders.v1alpha1.folder.grafana.app/qux
```

--------------------------------

### Run a command in the devbox shell

Source: https://github.com/grafana/grafanactl/blob/main/CONTRIBUTING.md

Execute a one-off command within the managed devbox environment.

```bash
$ devbox run go version
```

--------------------------------

### Grafanactl Push Flow

Source: https://github.com/grafana/grafanactl/blob/main/CLAUDE.md

Details the steps involved in the push flow, where local resources are applied to Grafana. Includes file reading, filtering, resource processing, and pushing to Grafana with support for dry-runs.

```plaintext
1. Read files from disk (FSReader)
   - Concurrent file reads with errgroup
   - Format detection (JSON/YAML)
   - Decode into unstructured.Unstructured

2. Apply filters (from selectors)
   - Skip resources not matching user criteria
   - Deduplicate by GVK+name

3. Process resources
   - ManagerFieldsAppender: Add grafanactl manager metadata
   - ServerFieldsStripper: Remove read-only fields (for dry-run)

4. Push to Grafana (Pusher)
   - Two-phase: folders first (dependency ordering)
   - Per-resource: Check if exists → Create or Update
   - Concurrent pushes (configurable concurrency)
   - Dry-run support via Kubernetes dry-run semantics
```

--------------------------------

### Check test environment status

Source: https://github.com/grafana/grafanactl/blob/main/CONTRIBUTING.md

Use the Make target to check the health status of the test environment services.

```bash
$ make test-env-status
```