id = "grafanactl"
name = "grafanactl"
homepage = "https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/grafanactl/"
description = "A command-line tool to authenticate, manage environments, and perform administrative tasks through the Grafana REST API."
executables = ["grafanactl"]

[dotfiles]

# Grafana's official documentation says the YAML config is
# $XDG_CONFIG_HOME/grafanactl/config.yaml, falling back to ~/.config there.
# https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/grafanactl/#configure-grafanactl-with-configuration-files
paths = ["[configHome]/grafanactl/config.yaml"]
secret = []

# Contexts may persist a service-account token or basic-auth credentials.
# https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/grafanactl/#use-configuration-contexts
[[dotfiles.secret_paths]]
file = "[configHome]/grafanactl/config.yaml"
format = "yaml"
match = { key_path = [
  "contexts.*.grafana.token",
  "contexts.*.grafana.user",
  "contexts.*.grafana.password",
] }

[commands]
format = 1
label = "grafanactl"
description = "Grafana CLI. Only 'resources pull' is offered here; other sub-commands are left out. The project is being deprecated in favour of gcx."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.subcommand]]
path = ["resources", "pull"]
label = "Pull resources from Grafana"
description = "Download dashboards, folders and other resources from the selected Grafana context to files on disk."

[[commands.subcommand.source]]
id = "docs"
kind = "manual"
url = "https://github.com/grafana/grafanactl/blob/main/docs/reference/cli/grafanactl_resources_pull.md"
revision = "main 2026-10-27"
evidence = '''
grafanactl resources pull [RESOURCE_SELECTOR]... [flags]
grafanactl resources pull dashboards folders
grafanactl resources pull dashboards/foo,bar
      --include-managed   Include resources managed by tools other than grafanactl
      --on-error string   How to handle errors during resource operations:
                            ignore — continue processing all resources and exit 0
                            fail   — continue processing all resources and exit 1 if any failed (default)
                            abort  — stop on the first error and exit 1 (default "fail")
  -o, --output string     Output format. One of: json, yaml (default "json")
  -p, --path string       Path on disk in which the resources will be written (default "./resources")
      --config string    Path to the configuration file to use
      --context string   Name of the context to use
      --no-color         Disable color output
'''

[[commands.subcommand.field]]
id = "selectors"
label = "Resource selectors"
description = "For example dashboards, dashboards/foo,bar or folders. Leave empty to pull everything."
type = "string"
position = 0
multiple = true
sources = ["docs"]

[[commands.subcommand.field]]
id = "context"
label = "Context"
description = "Name of the configured Grafana context to use."
type = "string"
option = ["--context"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "path"
label = "Output directory"
type = "path"
option = ["--path", "-p"]
path = { kind = "directory", role = "output", must_exist = false }
effect = "overwrite"
sources = ["docs"]

[[commands.subcommand.field]]
id = "output"
label = "File format"
type = "enum"
option = ["--output", "-o"]
choices = [{ value = "json", label = "JSON" }, { value = "yaml", label = "YAML" }]
sources = ["docs"]

[[commands.subcommand.field]]
id = "on_error"
label = "On error"
type = "enum"
option = ["--on-error"]
choices = [{ value = "ignore", label = "Ignore and exit 0" }, { value = "fail", label = "Continue, exit 1 if any failed" }, { value = "abort", label = "Stop at first error" }]
sources = ["docs"]

[[commands.subcommand.field]]
id = "include_managed"
label = "Include resources managed by other tools"
type = "boolean"
option = ["--include-managed"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "config"
label = "Config file"
type = "path"
option = ["--config"]
path = { kind = "file", role = "input", must_exist = true }
sources = ["docs"]

[[commands.subcommand.field]]
id = "no_color"
label = "Disable colour"
type = "boolean"
option = ["--no-color"]
sources = ["docs"]

[[commands.subcommand.task]]
id = "dashboards"
label = "Pull all dashboards"
set = { selectors = ["dashboards"] }
fields = ["selectors", "context", "path", "output"]
required = []

[[commands.subcommand.task]]
id = "everything"
label = "Pull everything"
fields = ["context", "path", "output", "on_error"]
required = []

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["selectors", "context", "path", "output"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["on_error", "include_managed", "config", "no_color"]