id       = "gcx"
name     = "gcx"
homepage = "https://grafana.com/docs/grafana-cloud/ai-tools/gcx/"
description = "CLI for managing Grafana Cloud resources."
executables   = ["gcx"]

[dotfiles]

# https://grafana.com/docs/grafana-cloud/ai-tools/gcx/configuration/ — gcx's
# documented user source is $HOME/.config/gcx/config.yaml, with the platform
# user config directory as a fallback. The repository .gcx.yaml is deliberately
# omitted because it is project-local, not a home-directory preference.
paths = ["~/.config/gcx/config.yaml"]

# gcx can put these authentication values in its YAML configuration; the same
# page documents both service-account tokens and basic-auth passwords.
secret = []
[[dotfiles.secret_paths]]
file  = "~/.config/gcx/config.yaml"
match = { key_path = ["stacks.*.grafana.token", "stacks.*.grafana.password"] }

[commands]
format = 1
label = "Query Grafana Cloud"
description = "Run PromQL or LogQL queries against Grafana Cloud. Login, resource pull/push, alerts and other gcx areas are not covered."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = false, short_bundles = false }

[[commands.subcommand]]
path = ["metrics", "query"]
label = "Query metrics (PromQL)"

[[commands.subcommand.source]]
id = "readme"
kind = "help"
url = "https://raw.githubusercontent.com/grafana/gcx/HEAD/README.md"
revision = "2026-10-27"
evidence = """
$ gcx metrics query  'sum by (handler)(rate(grafana_http_request_duration_seconds_count{}[5m]))' --since 1h -o graph
gcx metrics query 'rate(http_requests_total[5m])' --since 1h
gcx logs query '{app="nginx"} |= "error"' --since 1h
"""

[[commands.subcommand.field]]
id = "query"
label = "Query"
description = "PromQL expression, for example rate(http_requests_total[5m])."
type = "string"
position = 0
min = 1
sources = ["readme"]

[[commands.subcommand.field]]
id = "since"
label = "Time range"
description = "Look back this far, for example 1h."
type = "string"
option = ["--since"]
suggestions = [{ value = "1h", label = "1 hour" }]
sources = ["readme"]

[[commands.subcommand.field]]
id = "output"
label = "Output format"
type = "string"
option = ["-o"]
suggestions = [{ value = "graph", label = "Graph" }]
sources = ["readme"]

[[commands.subcommand.task]]
id = "query"
label = "Run query"
fields = ["query", "since", "output"]
required = ["query"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["query", "since", "output"]

[[commands.subcommand]]
path = ["logs", "query"]
label = "Query logs (LogQL)"

[[commands.subcommand.source]]
id = "readme"
kind = "help"
url = "https://raw.githubusercontent.com/grafana/gcx/HEAD/README.md"
revision = "2026-10-27"
evidence = """
$ gcx metrics query  'sum by (handler)(rate(grafana_http_request_duration_seconds_count{}[5m]))' --since 1h -o graph
gcx metrics query 'rate(http_requests_total[5m])' --since 1h
gcx logs query '{app="nginx"} |= "error"' --since 1h
"""

[[commands.subcommand.field]]
id = "query"
label = "Query"
description = "LogQL expression, for example a stream selector plus a line filter."
type = "string"
position = 0
min = 1
sources = ["readme"]

[[commands.subcommand.field]]
id = "since"
label = "Time range"
description = "Look back this far, for example 1h."
type = "string"
option = ["--since"]
suggestions = [{ value = "1h", label = "1 hour" }]
sources = ["readme"]

[[commands.subcommand.field]]
id = "output"
label = "Output format"
type = "string"
option = ["-o"]
suggestions = [{ value = "graph", label = "Graph" }]
sources = ["readme"]

[[commands.subcommand.task]]
id = "query"
label = "Run query"
fields = ["query", "since", "output"]
required = ["query"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["query", "since", "output"]