--- title: "CLI reference | Grafana Cloud documentation" description: "Complete gcx command, flag, and environment variable reference." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # CLI reference This reference describes gcx **v1.6.0**. Run `gcx version` to check your installed version. Flag defaults below are for human mode. Agent mode changes defaults such as output format; explicit flags override those defaults. - [Commands](#commands) - [Environment variables](#environment-variables) - [Configuration reference](/docs/grafana-cloud/ai-tools/gcx/configuration/#configuration-reference) ## Commands ### `gcx` gcx is a unified CLI for managing Grafana resources, dashboards, datasources, alerting, and Cloud product APIs (SLO, IRM, Synthetic Monitoring, Fleet, k6, and more). Run ‘gcx agent skills list’ to see bundled Agent Skills with task-specific guidance. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for gcx ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --agent Enable agent mode (JSON output, no color). Auto-detected from known agent identity variables. Set GCX_AGENT_NAME to identify a supported harness, or GCX_AGENT_MODE to control the mode. --context string Name of the context to use (overrides current-context in config) --insecure-log-http-payload Log full HTTP request/response bodies including raw credentials, authorization tokens, cookies, and OAuth refresh tokens. Requires -vvv. Do not ship these logs. --no-color Disable color output --no-truncate Disable table column truncation (auto-enabled when stdout is piped) -v, --verbose count Verbose mode. Multiple -v options increase the verbosity (maximum: 3). ``` ### `gcx agent` Utilities for gcx agent mode: manage spill files, install and update Agent Skills, and other agent session housekeeping. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for agent ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agent prune` Remove gcx agent spill files (gcx-results-*.json and gcx-results-*.jsonl) from the system temp directory that are older than 30 minutes. These files are created when a command response exceeds the spill threshold (default 100 KiB). Run prune periodically to keep the temp directory clean, or call it at the end of an agent session. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agent prune [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for prune --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agent skills` Install the canonical portable gcx Agent Skills bundle for .agents-compatible agent harnesses. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for skills ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agent skills get` Print the content of a bundled gcx Agent Skill straight from the embedded bundle, without writing anything to ~/.agents. By default the skill’s SKILL.md body is printed. Pass a reference path (e.g. references/query-patterns.md) to print a single bundled reference file instead. Deprecated skills emit a warning; retired skills report their replacement, when one is recorded, instead of content. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agent skills get SKILL [REFERENCE] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agent skills get create-dashboard gcx agent skills get create-dashboard -o json gcx agent skills get debug-with-grafana references/query-patterns.md ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agent skills install` Install one or more bundled gcx Agent Skills into a user-level .agents directory for tools that follow the .agents skill convention. Use –all to install the entire bundle. Deprecated skills are installed with a warning; retired skills cannot be installed. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agent skills install [SKILL]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agent skills install setup-gcx gcx agent skills install setup-gcx debug-with-grafana manage-dashboards gcx agent skills install --all gcx agent skills install --all --dry-run gcx agent skills install setup-gcx --force ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all Install all bundled skills --dir string Root directory for the .agents installation (default "~/.agents") --dry-run Preview the installation without writing files --force Overwrite existing differing files managed by the gcx skills bundle -h, --help help for install --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agent skills list` List bundled skills and locally present retired gcx skills, including descriptions, lifecycle status, replacements, and installation state. Skills not in the gcx catalog are unmanaged and omitted. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agent skills list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agent skills list gcx agent skills list -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dir string Root directory for the .agents installation (used to check installed status) (default "~/.agents") -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agent skills uninstall` Remove one or more current or retired gcx skills from a user-level .agents skills directory. Only names recorded in the gcx catalog can be uninstalled; unmanaged skills are never touched. Catalog names identify skills but do not prove ownership of local files. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agent skills uninstall [SKILL]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agent skills uninstall setup-gcx gcx agent skills uninstall setup-gcx debug-with-grafana gcx agent skills uninstall --all --yes gcx agent skills uninstall --all --yes --dry-run ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all Uninstall all gcx-managed skills --dir string Root directory for the .agents installation (default "~/.agents") --dry-run Preview the uninstall without removing files -h, --help help for uninstall --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") -y, --yes Auto-approve uninstalling all skills ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agent skills update` Update installed gcx skills in a user-level .agents skills directory. With no skill names, update all installed bundled skills and report retired installations. Retired skills are left untouched; replacements are never installed automatically. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agent skills update [SKILL]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agent skills update gcx agent skills update --dry-run gcx agent skills update setup-gcx debug-with-grafana ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dir string Root directory for the .agents installation (default "~/.agents") --dry-run Preview the update without writing files -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y` Manage Grafana Agent Observability resources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for agento11y ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y agents` Query Agent Observability agent catalog. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for agents ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y agents get` Get the full agent definition. Use –version for a specific version. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y agents get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") --version string Specific effective version to look up ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y agents list` List agents. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y agents list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of agents to return (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y agents list-versions` List version history for an agent. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y agents list-versions [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-versions --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y collections` Manage named groups of saved conversations. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for collections ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y collections add-conversations` Add one or more saved conversations to a collection. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y collections add-conversations ... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for add-conversations --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y collections create` Create a new collection. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y collections create [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Create with inline flags. gcx agento11y collections create --name "Regression suite" --description "Nightly regression" # Create from a YAML file (either raw {name,description} or a typed resource envelope). gcx agento11y collections create -f collection.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --description string Collection description -f, --filename string File containing the collection create payload (use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Collection name (required if --filename is not given) -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y collections delete` Delete collections. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y collections delete COLLECTION-ID... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y collections get` Get a single collection. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y collections get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y collections list` List collections. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y collections list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of collections to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y collections list-conversations` List saved conversations belonging to a collection. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y collections list-conversations [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-conversations --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of saved conversations to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y collections remove-conversation` Remove a single saved conversation from a collection. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y collections remove-conversation [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for remove-conversation --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y collections update` Patch a collection’s name and/or description. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y collections update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --description string New collection description -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string New collection name -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y conversations` Query Agent Observability conversations. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for conversations ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y conversations annotate` Annotate a conversation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y conversations annotate [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y conversations annotate conv-123 --body "Needs review" gcx agento11y conversations annotate conv-123 --type TRIAGE_STATUS --body "Escalated" --tag status=needs_review ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --annotation-id string Annotation ID; generated when omitted --body string Annotation body --generation-id string Generation ID to attach the annotation to -h, --help help for annotate --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --metadata-json string Metadata object as JSON -o, --output string Output format. One of: agents, json, yaml (default "json") --tag stringArray Tag in key=value form (repeatable) --type string Annotation type: NOTE, LABEL, TRIAGE_STATUS, ROOT_CAUSE, or FOLLOW_UP (default "NOTE") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y conversations get` Get a single conversation with all generations. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y conversations get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y conversations list` List conversations. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y conversations list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of conversations to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y conversations list-annotations` List annotations for a conversation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y conversations list-annotations [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --cursor string Pagination cursor from a previous response -h, --help help for list-annotations --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Number of annotations to request (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y conversations search` Search conversations using filter expressions and time ranges. Defaults to the last 24 hours. Use –from and –to for custom ranges (both required). Filter syntax: key operator “value” (multiple filters separated by spaces). Filter keys (trace): model, provider, agent, agent.version, status, error.type, error.category, duration, tool.name, operation, namespace, cluster, service Filter keys (metadata): generation\_count, eval.passed, eval.evaluator\_id, eval.score\_key, eval.score Operators: =, !=, >, <, >=, <=, =~ (regex) Returns a single page of results (controlled by –page-size). A warning is shown when more results are available. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y conversations search [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y conversations search --filters 'agent = "claude-code"' gcx agento11y conversations search --filters 'agent = "claude-code" model = "claude-opus-4-6"' gcx agento11y conversations search --filters 'status = "error"' --from 2026-04-01T00:00:00Z --to 2026-04-02T00:00:00Z ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --filters string Filter expression for conversation search --from string Start of time range (RFC3339, e.g. 2026-01-01T00:00:00Z) -h, --help help for search --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --page-size int Number of results per page (default 50) --to string End of time range (RFC3339, e.g. 2026-12-31T23:59:59Z) ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y evaluators` Manage evaluator definitions (LLM judge, regex, heuristic). **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for evaluators ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y evaluators delete` Delete evaluators. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y evaluators delete ID... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y evaluators get` Get a single evaluator definition. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y evaluators get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y evaluators list` List evaluator definitions. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y evaluators list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of evaluators to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y evaluators test` Run an evaluator against a generation without persisting results. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y evaluators test [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Test an existing evaluator against a generation. gcx agento11y evaluators test -e my-evaluator -g gen-abc123 # Test from a full request file (kind, config, output_keys, generation_id). gcx agento11y evaluators test -f test-request.yaml # Test with JSON output. gcx agento11y evaluators test -e my-evaluator -g gen-abc123 -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --conversation-id string Conversation ID hint for generation lookup -e, --evaluator string Evaluator ID to test (fetches config from server) -f, --filename string File with full eval:test request body (use - for stdin) -g, --generation string Generation ID to evaluate -h, --help help for test --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y evaluators upsert` Create or update an evaluator from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y evaluators upsert [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Create an evaluator from a YAML file. gcx agento11y evaluators upsert -f evaluator.yaml # Create from stdin. gcx agento11y evaluators upsert -f - # Export a template, customize it, then create an evaluator. gcx agento11y templates get -o yaml > evaluator.yaml gcx agento11y evaluators upsert -f evaluator.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the evaluator definition (use - for stdin) -h, --help help for upsert --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments` Manage eval experiment runs. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for experiments ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments cancel` Cancel a running experiment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments cancel [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for cancel --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments create` Create a new experiment from a JSON or YAML file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments create [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Create from a YAML file. gcx agento11y experiments create -f experiment.yaml # Create from stdin. cat experiment.json | gcx agento11y experiments create -f - ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the experiment create payload (use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments get` Get a single experiment by run ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments get-report` Get the aggregate report for an experiment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments get-report [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get-report --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments list` List experiments. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of experiments to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments list-scores` List scores produced by an experiment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments list-scores [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-scores --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of scores to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments list-trials` List test case trials for an experiment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments list-trials [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-trials --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of trials to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments pull` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Pull the experiment record, aggregate report, and paginated trial responses to a new directory. The report includes the evaluator scores and artifact metadata returned for each trial. The trial index contains referenced conversation IDs. Conversation and artifact payloads are not downloaded unless their respective –include-conversations or –include-artifacts flag is set. API response bodies are stored without field selection or model-specific transformation so source fields remain available for offline analysis. The destination must not already exist. Before downloading, gcx verifies that the destination filesystem supports atomic no-replace directory publication. When conversations or artifacts are included, payload requests run concurrently and individual failures are recorded in the manifest and artifact receipt. Pulled data may contain sensitive prompts, tool inputs, tool outputs, and artifact bytes. Each bundle includes an AGENTS.md with safe-handling instructions and a .gitignore that excludes the entire bundle from Git by default. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments pull [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Pull experiment metadata, aggregate report, trials, and conversation IDs. gcx agento11y experiments pull -d ./exports/run-1 # Also download every referenced conversation and artifact with reduced request pressure. gcx agento11y experiments pull -d ./exports/run-1 --include-conversations --include-artifacts --concurrency 4 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --concurrency int Maximum concurrent payload requests (default 10) -h, --help help for pull --include-artifacts Download every artifact payload referenced by the experiment report --include-conversations Download the full payload for every conversation referenced by a trial -d, --output-dir string Directory to create for the pulled bundle (required; must not already exist) ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments test-suites` Manage experiment test suites. **Aliases:** `suites` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for test-suites ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments test-suites cases` Manage test cases in a suite version. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for cases ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments test-suites cases delete` Delete a test case from a mutable suite version. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments test-suites cases delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments test-suites cases get` Get a single test case. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments test-suites cases get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments test-suites cases list` List test cases in a suite version. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments test-suites cases list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of test cases to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments test-suites cases update` Update a test case from a JSON or YAML file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments test-suites cases update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the test case patch payload (use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments test-suites cases upsert` Create or replace a test case from a JSON or YAML file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments test-suites cases upsert [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the test case payload (use - for stdin) -h, --help help for upsert --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments test-suites create` Create a test suite. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments test-suites create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --description string Test suite description -f, --filename string File containing the test suite create payload (use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Test suite name -o, --output string Output format. One of: agents, json, yaml (default "json") --suite-id string Stable test suite id --tag strings Test suite tag (repeatable or comma-separated) ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments test-suites get` Get a single test suite. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments test-suites get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments test-suites list` List test suites. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments test-suites list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of test suites to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments test-suites update` Update a test suite. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments test-suites update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --description string New test suite description; pass an empty string to clear -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string New test suite name -o, --output string Output format. One of: agents, json, yaml (default "json") --tag strings Test suite tag (repeatable or comma-separated; replaces all tags) ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments test-suites versions` Manage test suite versions. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for versions ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments test-suites versions create` Create a draft test suite version. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments test-suites versions create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --changelog string Version changelog --empty-draft Create an empty draft instead of cloning the latest published version -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments test-suites versions publish` Publish a draft test suite version. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments test-suites versions publish [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for publish --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments trials` Manage experiment test case trials. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for trials ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments trials create` Create or upsert a test case trial from a JSON or YAML file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments trials create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the trial payload (use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments trials get` Get a single test case trial. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments trials get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments trials list-artifacts` List artifacts for a test case trial. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments trials list-artifacts [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-artifacts --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of artifacts to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments trials list-scores` List scores for a test case trial. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments trials list-scores [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-scores --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of scores to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments trials update` Update a test case trial from a JSON or YAML file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments trials update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the trial patch payload (use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y experiments update` Update an experiment’s mutable fields. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y experiments update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --description string New experiment description; pass an empty string to clear -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string New experiment name -o, --output string Output format. One of: agents, json, yaml (default "json") --tag strings Experiment tag (repeatable or comma-separated; replaces all tags) ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y generations` Inspect individual LLM generations. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for generations ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y generations get` Get a generation’s full detail: input, output, model, tokens, and tool calls. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y generations get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y generations list-scores` List evaluation scores produced by online rules for a generation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y generations list-scores [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-scores --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of scores to return (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y guards` Guards (hook rules) are synchronous policies evaluated before or after each generation. They can deny, warn, or transform a generation based on evaluators, regex patterns, or blocked tool names. Unlike eval rules (gcx agento11y rules), guards run inline on the request path and short-circuit by default. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for guards ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y guards create` Create a hook rule (guard) from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y guards create [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Create a guard from a YAML file. gcx agento11y guards create -f guard.yaml # Create from stdin. gcx agento11y guards create -f - # Create and output as YAML. gcx agento11y guards create -f guard.json -o yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the hook rule definition (use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y guards delete` Delete hook rules (guards). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y guards delete ID... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y guards get` Get a single hook rule (guard). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y guards get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y guards list` List hook rules (guards). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y guards list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of hook rules to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y guards update` Update a hook rule (guard) from a file. Full replace; omitted fields reset to defaults. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y guards update [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Update a guard from a YAML file. gcx agento11y guards update my-guard -f guard.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the full hook rule definition (use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y judge` List LLM providers and models available for LLM-judge evaluators. Use these values in the ‘provider’ and ‘model’ fields of an llm\_judge evaluator config. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for judge ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y judge list-models` List available judge models. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y judge list-models --provider [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-models --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --provider string Provider ID (required, see 'judge list-providers') ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y judge list-providers` List available judge providers. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y judge list-providers [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-providers --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y model-rates` Configure your own negotiated model prices. Cost figures are otherwise computed from a public catalog, so a negotiated rate, a committed-use discount or a reseller agreement shows a price that is not yours — and a model the catalog does not carry shows no price at all. Rates are given in USD per million tokens, the same way providers publish them, so what you type is what you can check against your contract. Setting a rate applies it from that moment on. Generations already recorded keep the price they were given, and a later change records a new rate rather than replacing the old one, so history stays readable. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for model-rates ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y model-rates create` Record your price for one model, in force from now. The rate replaces the public catalog price for this provider and model completely: nothing is filled in from the catalog card, so state every rate your contract covers. A bucket you leave unset is not charged, and passing 0 charges the same. The difference is what it records: 0 says your contract prices that bucket at nothing, while leaving the flag off says nothing about it at all. At least one rate has to be set, and an explicit 0 counts. The long-context flags do not work that way. They are changes on top of the rates above, so a bucket you leave unset there keeps charging its base rate above the threshold, and only an explicit 0 makes it free. Omitting –long-context-price-input is not the same as setting it to 0. Generations already recorded keep the price they were given. A later call records a new rate rather than overwriting this one. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y model-rates create [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # A flat negotiated rate. gcx agento11y model-rates create --provider openai --model gpt-5.5 \ --price-input 2.00 --price-output 8.00 # A model the catalog does not carry. gcx agento11y model-rates create --provider acme --model in-house-7b \ --price-input 1.00 --price-output 4.00 # A contract that keeps the provider's long-context tier. gcx agento11y model-rates create --provider openai --model gpt-5.5 \ --price-input 2.00 --price-output 8.00 \ --long-context-threshold 272000 \ --long-context-price-input 4.00 --long-context-price-output 12.00 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --long-context-price-cache-read float USD per million cache-read tokens above the threshold. Omit to keep --price-cache-read above it; pass 0 to charge nothing --long-context-price-cache-write float USD per million cache-write tokens above the threshold. Omit to keep --price-cache-write above it; pass 0 to charge nothing --long-context-price-input float USD per million input tokens above the threshold. Omit to keep --price-input above it; pass 0 to charge nothing --long-context-price-output float USD per million output tokens above the threshold. Omit to keep --price-output above it; pass 0 to charge nothing --long-context-threshold int Input tokens above which the long-context rates apply --model string Model the rate applies to, as your telemetry reports it (required) -o, --output string Output format. One of: agents, json, yaml (default "yaml") --price-cache-read float USD per million tokens read from the prompt cache --price-cache-write float USD per million tokens written to the prompt cache --price-input float USD per million input tokens --price-output float USD per million output tokens --price-request float USD charged per call, for models that have a flat fee --provider string Provider the model belongs to, as your telemetry reports it (required) ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y model-rates delete` Delete one configured rate. A model can carry several rates, one per change, so a delete names which by its effective-from. Take that value from ’list’. Deleting does not restore the catalog price for generations this rate already priced: their cost was computed when they arrived and is not recalculated. What changes is the price applied from now on. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y model-rates delete [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Take effective-from from list, then delete that rate. gcx agento11y model-rates list gcx agento11y model-rates delete --provider openai --model gpt-5.5 \ --effective-from 2026-09-23T09:14:22.481739Z ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --effective-from string effective-from of the rate to delete, as 'list' reports it (required) --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --model string Model of the rate to delete (required) -o, --output string Output format. One of: agents, json, text, yaml (default "text") --provider string Provider of the rate to delete (required) ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y model-rates list` List the rates you have configured. Superseded rates are listed too. A change records a new rate rather than replacing the old one, so a model can appear more than once — the newest effective-from is the one in force, and the others are what priced the generations that arrived while they applied. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y model-rates list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # The rates you have configured, up to --limit (default 50), newest first per model. gcx agento11y model-rates list # With every rate column. gcx agento11y model-rates list -o wide ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of rates to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y rules` Manage rules that route generations to evaluators. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for rules ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y rules create` Create an evaluation rule from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y rules create [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Create a rule from a YAML file. gcx agento11y rules create -f rule.yaml # Create from stdin. gcx agento11y rules create -f - # Create and output as YAML. gcx agento11y rules create -f rule.json -o yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the rule definition (use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y rules delete` Delete evaluation rules. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y rules delete ID... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y rules get` Get a single evaluation rule. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y rules get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y rules list` List evaluation rules. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y rules list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of rules to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y rules list-scores` List online evaluation score rows for a rule. Each row may include an LLM-judge explanation in the payload. The default table shows score key, value, pass/fail, evaluator, and timestamp only; use -o wide (truncated explanation column) or -o json for full explanation text. Use –passed=false to focus on failing scores for failure theme analysis. Filter by evaluator, time range, agent, model, or provider as needed. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y rules list-scores [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Recent scores (summary table; no explanations). gcx agento11y rules list-scores # Failing scores with explanations. gcx agento11y rules list-scores --passed=false -o json # Wide table with truncated explanation column. gcx agento11y rules list-scores --passed=false -o wide # Scoped to one evaluator and time window. gcx agento11y rules list-scores --evaluator-id --from 2026-04-01T00:00:00Z --to 2026-04-02T00:00:00Z -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --agent-name stringArray Filter by exact agent name, case-sensitive (repeat to OR; not comma-split) --evaluator-id string Filter by evaluator ID --from string Inclusive lower bound on created_at (RFC3339) -h, --help help for list-scores --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of scores to return. 0, or a value above 1000, returns up to the 1000-row safety cap; narrow with filters to see beyond it (default 100) --max-value float Inclusive upper bound on numeric score value (omit for no upper bound) --min-value float Inclusive lower bound on numeric score value (omit for no lower bound) --model stringArray Filter by exact generation model, case-sensitive (repeat to OR; not comma-split) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --passed Filter by pass/fail (omit for all scores) --provider stringArray Filter by exact generation provider, case-sensitive (repeat to OR; not comma-split) --score-value stringArray Filter by exact score value, case-sensitive (repeat to OR; not comma-split, max 20) --sort-by string Sort field: created_at or value (default "created_at") --sort-dir string Sort direction: asc or desc (default "desc") --to string Exclusive upper bound on created_at (RFC3339) ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y rules update` Update an evaluation rule from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y rules update [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Update a rule from a YAML file. gcx agento11y rules update my-rule -f rule.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the full rule definition (use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y saved-conversations` Bookmark live conversations as fixed inputs for evaluation runs. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for saved-conversations ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y saved-conversations collections` List collections that contain a saved conversation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y saved-conversations collections [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for collections --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y saved-conversations delete` Delete saved conversations. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y saved-conversations delete SAVED-ID... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y saved-conversations get` Get a single saved conversation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y saved-conversations get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y saved-conversations list` List saved conversations. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y saved-conversations list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of saved conversations to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --source string Filter by source (telemetry or manual) ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y saved-conversations save` Bookmark a live conversation surfaced by gcx agento11y conversations. By default the bookmark ID is derived as saved-, matching the plugin UI; pass –saved-id to override. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y saved-conversations save [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Bookmark with the default saved ID. gcx agento11y saved-conversations save conv-123 --name "Regression seed" # Bookmark with tags. gcx agento11y saved-conversations save conv-123 --name "Regression seed" --tag suite=checkout --tag priority=high ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for save --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Human-readable name for the bookmark (required) -o, --output string Output format. One of: agents, json, yaml (default "json") --saved-id string Bookmark ID; defaults to saved- --tag stringArray Tag in key=value form (repeatable) ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y templates` Browse reusable evaluator blueprints (global and tenant-scoped). **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for templates ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y templates get` Get the full template definition including config and output keys. Templates are reusable evaluator blueprints. Export a template as YAML, customize it, and create an evaluator with ’evaluators upsert -f’. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y templates get [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Get a template's config and output keys. gcx agento11y templates get my-template -o yaml > evaluator.yaml gcx agento11y evaluators upsert -f evaluator.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y templates list` List eval templates. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y templates list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all templates. gcx agento11y templates list # Filter by scope. gcx agento11y templates list --scope global ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of templates to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --scope string Filter by scope: "global" or "tenant" ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx agento11y templates list-versions` List version history for an eval template. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx agento11y templates list-versions [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-versions --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx agento11y`](#gcx-agento11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert` Manage Grafana alert rules and alert groups **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for alert ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert contact-points` Manage Grafana alerting contact points. **Aliases:** `contact-point` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for contact-points ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert contact-points create` Create a new contact point. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert contact-points create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the contact point definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert contact-points delete` Delete a contact point by UID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert contact-points delete UID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert contact-points export` Export all contact points in provisioning format. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert contact-points export [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --format string Export format: yaml, json, or hcl (default "yaml") -h, --help help for export ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert contact-points get` Get a single contact point by UID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert contact-points get UID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert contact-points list` List alerting contact points. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert contact-points list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for unlimited) (default 50) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert contact-points update` Update an existing contact point by UID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert contact-points update UID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the contact point definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert groups` Inspect Grafana-managed alert rule groups. These commands are read-only. To modify the rules in a group, use the resources commands: gcx resources pull/push alertrules. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for groups ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert groups get` Get a single alert rule group. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert groups get NAME [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert groups list` List alert rule groups. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert groups list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for unlimited) (default 50) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert groups status` Show alert rule group status. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert groups status [NAME] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for status --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert instances` Manage alert instances. **Aliases:** `alerts` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for instances ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert instances list` List alert instances. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert instances list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --datasource string Datasource UID to query (default: Grafana-managed rules) --folder string Filter by folder UID --group string Filter by group name -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Filter by rule name (regex, e.g. 'Tempo.*') -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --rule string Filter by rule UID --state string Filter by alert instance state (firing, pending, inactive) ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert mute-timings` Manage Grafana alerting mute timings. **Aliases:** `mute-timing` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for mute-timings ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert mute-timings create` Create a new mute timing. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert mute-timings create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the mute timing definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert mute-timings delete` Delete a mute timing by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert mute-timings delete NAME [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert mute-timings export` Export mute timings in provisioning format. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert mute-timings export [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --format string Export format: yaml, json, or hcl (default "yaml") -h, --help help for export --name string Export a single mute timing by name (default: all) ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert mute-timings get` Get a mute timing by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert mute-timings get NAME [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert mute-timings list` List mute timings. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert mute-timings list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for unlimited) (default 50) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert mute-timings update` Update an existing mute timing by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert mute-timings update NAME [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the mute timing definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert notification-history` Inspect the history of alert notifications delivered by Grafana Alerting. These commands are read-only. Each entry is a grouped notification that Grafana attempted to send to a contact point, recorded by the alerting historian. Use ’list’ to browse notifications and ’list-alerts’ to see the alerts in a specific one. Notification history must be enabled on the stack (the \[unified\_alerting.notification\_history] config with Loki, plus the kubernetesAlertingHistorian feature). **Aliases:** `nh` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for notification-history ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert notification-history list` List notification delivery history. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert notification-history list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start of time range (RFC3339). Overrides --since. -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of notifications to return. (default 100) --outcome string Filter by delivery outcome (success, error). -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --receiver string Filter by contact point (receiver) name. --rule-uid string Filter by alert rule UID. --since duration Look back this far from now when --from is not set. (default 1h0m0s) --status string Filter by notification status (firing, resolved). --to string End of time range (RFC3339, default now). ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert notification-history list-alerts` List the individual alerts that were part of one grouped notification. The notification’s own entry does not carry its alerts, so they are fetched separately by UUID. The time range must bracket the notification’s timestamp; widen –since (or set –from/–to) if the notification is older. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert notification-history list-alerts [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start of time range (RFC3339). Overrides --since. -h, --help help for list-alerts --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of alerts to return. (default 100) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since duration Look back this far from now when --from is not set. (default 1h0m0s) --to string End of time range (RFC3339, default now). --uuid string UUID of the notification (from 'notification-history list'). ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert notification-policies` Manage the Grafana alerting notification policy tree. **Aliases:** `notification-policy`, `policies` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for notification-policies ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert notification-policies export` Export the notification policy tree in provisioning format. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert notification-policies export [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --format string Export format: yaml, json, or hcl (default "yaml") -h, --help help for export ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert notification-policies get` Get the notification policy tree. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert notification-policies get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert notification-policies reset` Reset the notification policy tree to its default. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert notification-policies reset [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for reset --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert notification-policies set` Replace the entire notification policy tree. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert notification-policies set [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the policy tree (JSON/YAML, use - for stdin) --force Skip confirmation prompt -h, --help help for set --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert routing-trees` Manage notification routing trees through Grafana’s native `notifications.alerting.grafana.app` API. The default tree is named “user-defined”. Named trees require Grafana 13.1+, or 12.4-13.0 with the alertingMultiplePolicies feature toggle. Server errors are reported unchanged. **Aliases:** `routing-tree` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for routing-trees ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert routing-trees create` Create a routing tree from a native RoutingTree manifest. Create never updates an existing tree; an existing or reserved name (“user-defined”, “default”) fails with the server’s conflict error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert routing-trees create -f [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert routing-trees create -f team-a.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --api-version string Must match the manifest's apiVersion when set; the manifest decides the version -f, --filename string Path to a JSON/YAML RoutingTree manifest ('-' reads from stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert routing-trees delete` Delete a named routing tree. Deleting the default tree (“user-defined”) resets it to Grafana’s built-in configuration instead of removing it. **Aliases:** `rm` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert routing-trees delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --api-version string API version to use (e.g. notifications.alerting.grafana.app/v1beta1); defaults to the server's preferred version --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert routing-trees get` Get a routing tree’s native manifest by name. The default tree is “user-defined”. The name is sent to the server as given. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert routing-trees get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --api-version string API version to use (e.g. notifications.alerting.grafana.app/v1beta1); defaults to the server's preferred version -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert routing-trees list` List routing trees, including the default tree. **Aliases:** `ls` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert routing-trees list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --api-version string API version to use (e.g. notifications.alerting.grafana.app/v1beta1); defaults to the server's preferred version -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert routing-trees update` Replace one routing tree from a native RoutingTree manifest. Other trees are unchanged. The manifest must carry the metadata.resourceVersion from a recent get. If the tree changed on the server since then, the update fails with a conflict. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert routing-trees update -f [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert routing-trees get team-a -o yaml > team-a.yaml # edit team-a.yaml gcx alert routing-trees update team-a -f team-a.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --api-version string Must match the manifest's apiVersion when set; the manifest decides the version -f, --filename string Path to a JSON/YAML RoutingTree manifest ('-' reads from stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert ruler` Manage alerting and recording rules stored in a Mimir or Loki ruler, via Grafana’s per-datasource ruler proxy. These commands work only against Mimir (or another Prometheus-flavored ruler) and Loki datasources: every command requires –datasource with the UID of such a datasource. These are datasource-managed rules, distinct from Grafana-managed alert rules — inspect those with ‘gcx alert rules’ and modify them with ‘gcx resources pull/push alertrules’. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for ruler ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert ruler groups` Manage datasource-managed (Mimir/Loki ruler) rule groups. **Aliases:** `group` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for groups ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert ruler groups delete` Delete a ruler rule group. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert ruler groups delete NAMESPACE GROUP [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string UID of the Mimir or Loki datasource used as ruler (required) --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert ruler groups get` Get a ruler rule group (YAML by default, round-trips into upsert). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert ruler groups get NAMESPACE GROUP [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string UID of the Mimir or Loki datasource used as ruler (required) -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert ruler groups list` List ruler rule groups. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert ruler groups list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string UID of the Mimir or Loki datasource used as ruler (required) -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -n, --namespace string Only list groups in this namespace -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert ruler groups upsert` Create or update rule groups in a ruler namespace. The input may be a standard Prometheus rules file (with a top-level “groups:” list) or a single bare rule group. Upserting a group replaces the group with the same name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert ruler groups upsert NAMESPACE [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string UID of the Mimir or Loki datasource used as ruler (required) --dry-run Parse and validate only; send nothing to the ruler -f, --filename string File containing rule groups (Prometheus rules file or a single group; YAML/JSON, use - for stdin) -h, --help help for upsert --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert ruler namespaces` Manage datasource-managed (Mimir/Loki ruler) namespaces. **Aliases:** `namespace` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for namespaces ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert ruler namespaces delete` Delete a ruler namespace and all rule groups in it. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert ruler namespaces delete NAMESPACE [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string UID of the Mimir or Loki datasource used as ruler (required) --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert ruler namespaces list` List ruler namespaces with group and rule counts. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert ruler namespaces list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string UID of the Mimir or Loki datasource used as ruler (required) -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert rules` Inspect Grafana-managed alert rules. These commands are read-only: they show evaluation state, health, and timing. To create, modify, or delete alert rules, use the resources commands: shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources pull alertrules -p ./rules # export rules to disk gcx resources push -p ./rules # apply edited rules gcx resources delete alertrules/ # delete a rule ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for rules ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert rules get` Get a single alert rule. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert rules get UID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert rules list` List alert rules. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert rules list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --folder string Filter by folder UID --group string Filter by group name -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for unlimited) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --state string Filter by rule state (firing, pending, inactive) ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert state-history` Query the recorded history of alert rule state transitions. State history is served by Grafana’s alerting history backend. The default Loki backend answers both rule-scoped and global queries; the annotations backend requires –rule. Records are returned newest-first. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert state-history list --rule --from now-24h gcx alert state-history list --label severity=critical --limit 200 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for state-history ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert state-history list` List recorded alert state transitions. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert state-history list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start of the time range (RFC3339, Unix seconds, or relative e.g. now-6h) (default "now-6h") -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --label stringArray Filter by instance label equality (key=value); repeatable --limit int Maximum number of records to return (0 for the backend default) (default 100) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --rule string Filter by rule UID (required by the annotations history backend) --to string End of the time range (RFC3339, Unix seconds, or relative e.g. now) (default "now") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert templates` Manage Grafana alerting notification templates. **Aliases:** `template` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for templates ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert templates delete` Delete a notification template by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert templates delete NAME [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert templates get` Get a notification template by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert templates get NAME [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert templates list` List notification templates. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert templates list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for unlimited) (default 50) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx alert templates upsert` Create or update a notification template. The provisioning API uses a single PUT endpoint keyed by template name, so the same command handles both create and update. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx alert templates upsert [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the template definition (JSON/YAML, use - for stdin) -h, --help help for upsert --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx alert`](#gcx-alert-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx api` Send arbitrary HTTP requests to any Grafana API endpoint using the configured authentication. Supports GET, POST, PUT, PATCH, DELETE with custom headers and request bodies. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx api PATH [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all datasources gcx api /api/datasources # Get a specific datasource by UID gcx api /api/datasources/uid/my-prometheus # Get Grafana health status gcx api /api/health # Create a folder (POST implied by -d) gcx api /api/folders -d '{"title":"My Folder"}' # Create a dashboard from a file gcx api /api/dashboards/db -d @dashboard.json # Delete a dashboard gcx api /api/dashboards/uid/my-dashboard -X DELETE # Output as YAML gcx api /api/datasources -o yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --data string Request body (use @file for file, @- for stdin). Implies POST. -H, --header stringArray Custom headers (repeatable) -h, --help help for api --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -X, --method string HTTP method (default: GET, or POST if -d is set) -o, --output string Output format for JSON responses. One of: agents, json, yaml (default "json") ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx appo11y` Manage Grafana App Observability settings **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for appo11y ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx appo11y operations` Rank and inspect operations (span names) across App Observability services **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for operations ``` Inherits `--config` from [`gcx appo11y`](#gcx-appo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx appo11y operations get` Show the rate/errors/duration snapshot for one operation (span\_name) inside one service. The operation name is the positional argument; the parent service is always given via –service (bare name or “/”), never as part of the positional — span names routinely contain “/” (e.g. “GET /api/v1/carts”), which would make a slash-composite positional ambiguous. TimeSharePercent here means this operation’s share of ITS SERVICE’s wall-clock time — the same number “gcx appo11y services list-operations” reports for the same operation — not the fleet’s (see “gcx appo11y operations list” for the fleet-wide ranking). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx appo11y operations get --service [--namespace ns] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # One operation within the "checkoutservice" service gcx appo11y operations get "GET /cart" --service checkoutservice # Explicit namespace, last hour, JSON for scripting gcx appo11y operations get "GET /cart" --service payments/checkoutservice --since 1h -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Prometheus datasource UID (defaults to datasources.prometheus in config or auto-discovery) --filter stringArray Scope the lookup to series matching a label matcher, e.g. --filter k8s_cluster_name=prod-us (repeatable); the label must exist on the span metrics -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --kg string Knowledge Graph catalog consumption: auto (annotate rows with what the graph knows, when it's active) or off (never contact the Knowledge Graph). The annotation appears in JSON/YAML/agents output only — table and wide render nothing extra (default "auto") --kind string Span kinds to include. One of: inbound (server+consumer), server, consumer, all, or a comma-separated list of SPAN_KIND_* literals (default "inbound") --metrics-mode string Span-metrics family. One of: auto (probes the stack), v3 (traces_span_metrics_*), tempo (traces_spanmetrics_*), or otel (bare calls_total + duration_seconds_bucket) (default "auto") -n, --namespace string Service namespace (only needed when --service is a bare name and multiple namespaces are in play) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --service string Service the operation belongs to: bare name or the canonical "/" form (required) --since string Rate/quantile window applied to span metrics (e.g. 1m, 5m, 1h, 1d) — PromQL duration syntax (default "5m") ``` Inherits `--config` from [`gcx appo11y`](#gcx-appo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx appo11y operations list` Rank the top operations across every service by busy-seconds-per-second (time share), the fleet-wide counterpart to “gcx appo11y services list-operations” (which is scoped to one service). Each row is qualified by the service (job) it belongs to. Time-share is normalized against the WHOLE FLEET’s busy-time, not per-service — so a –limit N view never claims the top N operations are 100% of anything; it reports what share of the fleet’s total wall-clock time they actually consume. –limit always bounds the returned row count to N, ranked by busy-seconds-per-second desc. Without –group-by that’s N operations; with –group-by a single operation can occupy more than one of those N rows (one per distinct group-label value it appears under), so N rows may cover fewer than N distinct operations. The source span-metrics series (Tempo’s traces\_spanmetrics\_*, the v3 traces\_span\_metrics\_*, or bare OTel calls\_total) is auto-detected by default. Use –metrics-mode to pin it. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx appo11y operations list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Top 20 operations fleet-wide in the default 5m window gcx appo11y operations list # Top 50, last hour, JSON for scripting gcx appo11y operations list --since 1h --limit 50 -o json # Restrict to one namespace after ranking gcx appo11y operations list --namespace payments # Break each operation out per cluster to spot per-cluster hotspots gcx appo11y operations list --group-by k8s_cluster_name ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Prometheus datasource UID (defaults to datasources.prometheus in config or auto-discovery) --env string Restrict to a single deployment_environment (post-query convenience filter, applied after ranking; only useful if the span metrics carry the label) --filter stringArray Scope the ranking to series matching a label matcher, e.g. --filter k8s_cluster_name=prod-us (repeatable); the label must exist on the span metrics --group-by strings Break each operation out per distinct value of a label, e.g. --group-by k8s_cluster_name (comma-separated or repeatable); the label must exist on the span metrics -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --kg string Knowledge Graph catalog consumption: auto (annotate rows with what the graph knows, when it's active) or off (never contact the Knowledge Graph). The annotation appears in JSON/YAML/agents output only — table and wide render nothing extra (default "auto") --kind string Span kinds to include. One of: inbound (server+consumer), server, consumer, all, or a comma-separated list of SPAN_KIND_* literals (default "inbound") --limit int Return at most N rows fleet-wide, ranked by busy-seconds-per-second desc (must be 1-500; unlike other list commands, 0 is rejected — the unbounded fleet shape is #services x #operations). With --group-by a single operation may occupy more than one row, so N rows can cover fewer than N distinct operations (default 20) --metrics-mode string Span-metrics family. One of: auto (probes the stack), v3 (traces_span_metrics_*), tempo (traces_spanmetrics_*), or otel (bare calls_total + duration_seconds_bucket) (default "auto") -n, --namespace string Restrict to services in a single namespace (post-query convenience filter, applied after ranking) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --since string Rate/quantile window applied to span metrics (e.g. 1m, 5m, 1h, 1d) — PromQL duration syntax (default "5m") ``` Inherits `--config` from [`gcx appo11y`](#gcx-appo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx appo11y overrides` Manage App Observability metrics generator overrides. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for overrides ``` Inherits `--config` from [`gcx appo11y`](#gcx-appo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx appo11y overrides get` Get the App Observability metrics generator overrides. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx appo11y overrides get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx appo11y`](#gcx-appo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx appo11y overrides update` Update App Observability metrics generator overrides from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx appo11y overrides update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --file string Path to the overrides file (JSON or YAML) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx appo11y`](#gcx-appo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx appo11y services` Inspect Application Observability services discovered from telemetry **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for services ``` Inherits `--config` from [`gcx appo11y`](#gcx-appo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx appo11y services get` Show metadata and a rate/errors/duration snapshot for one service. The argument is either the bare service name (matching the OTel service.name resource attribute) or the canonical “/” form. When a bare name is given, the namespace is resolved automatically from target\_info; ambiguity (the same name in multiple namespaces) errors out so the snapshot can’t accidentally target the wrong service. Pass –namespace or use the “/” form to disambiguate. Metadata comes from the same target\_info/traces\_target\_info union used by “gcx appo11y services list”. RED numbers are computed from span metrics over –since (default 5m), restricted to inbound spans (SERVER + CONSUMER). The span-metric family is selected by –metrics-mode: auto probe each family for this service and pick the one with data (prefers v3 > tempo > otel when a stack double-emits) v3 traces\_span\_metrics\_calls\_total / \_duration\_seconds\_bucket (OTel Collector >= 0.109, Grafana Alloy >= 1.5.0) tempo traces\_spanmetrics\_calls\_total / \_latency\_bucket (Tempo metrics-generator — Grafana Cloud default — and Beyla) otel calls\_total / duration\_seconds\_bucket (OTel Collector 0.94–0.108, Alloy 1.0–1.4.3, Grafana Agent >= 0.40) The resolved mode is reported in the snapshot output so you can confirm which family produced the numbers. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx appo11y services get [--namespace ns] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Bare name — namespace is resolved from target_info gcx appo11y services get checkoutservice # Same service, explicit namespace (skips the lookup) gcx appo11y services get payments/checkoutservice --since 1h # JSON for scripting gcx appo11y services get checkoutservice -o json # Restrict to server-side traffic only gcx appo11y services get checkoutservice --kind server # Stack double-emits both families; force the Tempo metrics-generator numbers gcx appo11y services get checkoutservice --metrics-mode tempo # Break a multi-cluster service down to a single cluster gcx appo11y services get faro-collector --filter k8s_cluster_name=prod-us-central-0 # Compare a service's RED across all clusters to spot the outlier gcx appo11y services get faro-collector --group-by k8s_cluster_name ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Prometheus datasource UID (defaults to datasources.prometheus in config or auto-discovery) --filter stringArray Scope the RED snapshot to series matching a label matcher, e.g. --filter k8s_cluster_name=prod-us (repeatable). Use to break a multi-cluster/multi-region service down one cluster at a time; the label must exist on the span metrics --group-by strings Pivot the RED snapshot into one row per distinct value of a label, e.g. --group-by k8s_cluster_name (comma-separated or repeatable). Surfaces outliers across clusters/regions without naming each one; the label must exist on the span metrics -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --kg string Knowledge Graph catalog consumption: auto (annotate rows with what the graph knows, when it's active) or off (never contact the Knowledge Graph). The annotation appears in JSON/YAML/agents output only — table and wide render nothing extra (default "auto") --kind string Span kinds to include. One of: inbound (server+consumer), server, consumer, all, or a comma-separated list of SPAN_KIND_* literals (default "inbound") --metrics-mode string Span-metrics family. One of: auto (probes the stack), v3 (traces_span_metrics_*), tempo (traces_spanmetrics_*), or otel (bare calls_total + duration_seconds_bucket) (default "auto") -n, --namespace string Service namespace (only needed when the argument is the bare service name and multiple namespaces are in play) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --since string Rate/quantile window applied to span metrics (e.g. 1m, 5m, 1h, 1d) — PromQL duration syntax (default "5m") ``` Inherits `--config` from [`gcx appo11y`](#gcx-appo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx appo11y services list` List the services Grafana Cloud Application Observability has discovered from telemetry. Discovery uses the same approach as the App Observability plugin: a group-by query against the OTel target\_info metric, projected onto (job, telemetry\_sdk\_language). Each result row is one service. Related: “gcx kg entities –type Service” surfaces services as Knowledge Graph entities with relationships and insights (requires the Knowledge Graph plugin); “gcx instrumentation services” lists Kubernetes workloads discovered for setting up instrumentation. The “version” field (–output wide/json/yaml) is populated only when every matched series agrees on a single service\_version; a service mid-rollout across two versions reports an empty version rather than picking one. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx appo11y services list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all services in the current stack gcx appo11y services list # Filter to Go services running in production gcx appo11y services list --language go --env production # Show the top 20 services with extra target_info labels gcx appo11y services list --limit 20 --columns service_version,k8s_pod_name # Per-language summary instead of the full list gcx appo11y services list --count # Pin a datasource and output JSON gcx appo11y services list -d grafanacloud-prom -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --columns strings Extra target_info labels to surface as table columns (comma-separated) --count Print a per-language summary instead of the full list -d, --datasource string Prometheus datasource UID (defaults to datasources.prometheus in config or auto-discovery) --env string Restrict to a single deployment_environment (e.g. production) --filter stringArray Restrict to services matching a label matcher, e.g. --filter k8s_namespace_name=prod (repeatable; applies to target_info only) -h, --help help for list --instrumentation string Which services to list: all, instrumented (target_info only), or uninstrumented (service-graph minus target_info) (default "all") --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --kg string Knowledge Graph catalog consumption: auto (annotate rows with what the graph knows, when it's active) or off (never contact the Knowledge Graph). The annotation appears in JSON/YAML/agents output only — table and wide render nothing extra (default "auto") --language string Restrict to a single telemetry_sdk_language (e.g. go, java, nodejs) --limit int Limit the number of services returned (0 = unlimited; applied after sorting) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --service-graph-metric string Override the service-graph metric used to find uninstrumented services (advanced) (default "traces_service_graph_request_total") ``` Inherits `--config` from [`gcx appo11y`](#gcx-appo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx appo11y services list-labels` List the labels present on a service’s span-metric series — the exact set that “gcx appo11y services get/list-operations –filter/–group-by” can operate on — with each label’s distinct-value count. This answers “what can I break this service down by?” without guessing. Pass –label to list the distinct values of a single label so you know what to feed –filter (e.g. –filter k8s\_cluster\_name=). Labels come from the span-metric calls series (auto-detected metrics-mode), which is what the RED commands filter and group on. Note: - “services map” groups on the Tempo service-graph metric family, whose labels may differ (and often omit cluster labels). - “services get -o json” additionally surfaces the target\_info resource attributes under .service.labels. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx appo11y services list-labels [--namespace ns] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # What can I filter/group checkoutservice by? gcx appo11y services list-labels checkoutservice # Which clusters does it run in? (values to feed --filter/--group-by) gcx appo11y services list-labels checkoutservice --label k8s_cluster_name # JSON for scripting gcx appo11y services list-labels checkoutservice -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Prometheus datasource UID (defaults to datasources.prometheus in config or auto-discovery) --filter stringArray Restrict discovery to series matching a label matcher, e.g. --filter k8s_cluster_name=prod-us (repeatable) -h, --help help for list-labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --label string Show the distinct values of a single label instead of the label summary (e.g. --label k8s_cluster_name) --metrics-mode string Span-metrics family whose labels to inspect. One of: auto (probes the stack), v3, tempo, or otel (default "auto") -n, --namespace string Service namespace (only needed when the argument is the bare service name and multiple namespaces are in play) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --since string Lookback window for series discovery (e.g. 15m, 1h, 1d) — PromQL duration syntax (default "1h") ``` Inherits `--config` from [`gcx appo11y`](#gcx-appo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx appo11y services list-operations` List the per-operation RED breakdown for one service. The argument is either the bare service name or the canonical “/” form; bare names are auto-resolved against target\_info the same way as “gcx appo11y services get”. Rows are sorted by time-share desc — the share of the service’s total wall-clock time each operation consumes, computed as (avg\_latency × rate) / sum(all). This surfaces operations that dominate latency regardless of whether they’re high-rate-fast or low-rate-slow. The source span-metrics series (Tempo’s traces\_spanmetrics\_*, the v3 traces\_span\_metrics\_*, or bare OTel calls\_total) is auto-detected by default. Use –metrics-mode to pin it; see “gcx appo11y services get –help” for the full reference. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx appo11y services list-operations [--namespace ns] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Top operations for the "checkoutservice" service in the default 5m window gcx appo11y services list-operations checkoutservice # Wider view with p50/p99 and absolute error rate gcx appo11y services list-operations checkoutservice -o wide # Last hour, unlimited rows, JSON for scripting gcx appo11y services list-operations payments/checkoutservice --since 1h --limit 0 -o json # Break a multi-cluster service down to a single cluster gcx appo11y services list-operations faro-collector --filter k8s_cluster_name=prod-us-central-0 # Break each operation out per cluster to spot per-cluster hotspots gcx appo11y services list-operations faro-collector --group-by k8s_cluster_name ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Prometheus datasource UID (defaults to datasources.prometheus in config or auto-discovery) --filter stringArray Scope the operations breakdown to series matching a label matcher, e.g. --filter k8s_cluster_name=prod-us (repeatable). Use to break a multi-cluster/multi-region service down one cluster at a time; the label must exist on the span metrics --group-by strings Break each operation out per distinct value of a label, e.g. --group-by k8s_cluster_name (comma-separated or repeatable). Time-share is normalized within each group so per-cluster hotspots are comparable; the label must exist on the span metrics -h, --help help for list-operations --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --kg string Knowledge Graph catalog consumption: auto (annotate rows with what the graph knows, when it's active) or off (never contact the Knowledge Graph). The annotation appears in JSON/YAML/agents output only — table and wide render nothing extra (default "auto") --kind string Span kinds to include. One of: inbound (server+consumer), server, consumer, all, or a comma-separated list of SPAN_KIND_* literals (default "inbound") --limit int Limit the number of operations returned (0 = unlimited; applied after sorting by time-share desc) (default 15) --metrics-mode string Span-metrics family. One of: auto (probes the stack), v3 (traces_span_metrics_*), tempo (traces_spanmetrics_*), or otel (bare calls_total + duration_seconds_bucket) (default "auto") -n, --namespace string Service namespace (only needed when the argument is the bare service name and multiple namespaces are in play) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --since string Rate/quantile window applied to span metrics (e.g. 1m, 5m, 1h, 1d) — PromQL duration syntax (default "5m") ``` Inherits `--config` from [`gcx appo11y`](#gcx-appo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx appo11y services map` Render the service-graph slice for one service: a callers list (services calling into this one) and a callees list (services this one calls). Data comes from Tempo’s service-graph metric family (traces\_service\_graph\_request\_\*), which is consistent across every metrics-mode — so there’s no –metrics-mode flag here. The argument is either the bare service name or the canonical “/” form; bare names are auto-resolved against target\_info the same way “gcx appo11y services get” does. Latency is direction-aware: callers see the server-side p95 (how long this service took to respond), callees see the client-side p95 (how long this service waited on the peer). JSON and YAML outputs include instrumentation status from `target_info` for each returned service name. This status uses the `target_info` inventory without edge filters, as the service list does. Status is name-level: metadata with the same service name marks a peer as instrumented across namespaces and connection types. A metadata query failure stops the map command. Connection type is empty for HTTP/gRPC peers; “database”, “messaging”, or “virtual\_node” for typed edges. Virtual-node peers are callers Tempo synthesises from orphan spans. Connection type does not change the name-level inventory status. Beyond –output table/wide/json/yaml, –output mermaid and –output dot render the map as a Mermaid or Graphviz graph, suitable for inlining in markdown / piping to “dot -Tpng”. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx appo11y services map [--namespace ns] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Default two-section table gcx appo11y services map checkoutservice # Mermaid graph — paste into a markdown doc or a PR comment gcx appo11y services map checkoutservice -o mermaid # Graphviz DOT — pipe to dot for an image gcx appo11y services map checkoutservice -o dot | dot -Tpng -o map.png # Wide table with p95 / connection-type, last hour gcx appo11y services map payments/checkoutservice --since 1h -o wide # JSON for scripting gcx appo11y services map checkoutservice -o json # Break a multi-cluster service's map down to a single cluster gcx appo11y services map faro-collector --filter k8s_cluster_name=prod-us-central-0 # Split each edge per cluster (service-graph metrics must carry the label) gcx appo11y services map faro-collector --group-by k8s_cluster_name ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Prometheus datasource UID (defaults to datasources.prometheus in config or auto-discovery) --filter stringArray Scope the map to service-graph edges matching a label matcher, e.g. --filter k8s_cluster_name=prod-us (repeatable). Use to break a multi-cluster/multi-region service down one cluster at a time; the label must exist on the service-graph metrics. JSON/YAML instrumentation status uses the target_info inventory without the edge filters --group-by strings Split each edge per distinct value of a label, e.g. --group-by k8s_cluster_name (comma-separated or repeatable). The label must exist on the service-graph metrics — note the Tempo service-graph family often omits cluster labels, in which case no edges match -h, --help help for map --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --kg string Knowledge Graph catalog consumption: auto (annotate rows with what the graph knows, when it's active) or off (never contact the Knowledge Graph). The annotation appears in JSON/YAML/agents output only — table and wide render nothing extra (default "auto") -n, --namespace string Service namespace (only needed when the argument is the bare service name and multiple namespaces are in play) -o, --output string Output format. One of: agents, dot, json, mermaid, table, wide, yaml (default "table") --since string Rate/quantile window applied to service-graph metrics (e.g. 1m, 5m, 1h, 1d) — PromQL duration syntax (default "5m") ``` Inherits `--config` from [`gcx appo11y`](#gcx-appo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx appo11y settings` Manage App Observability plugin settings. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for settings ``` Inherits `--config` from [`gcx appo11y`](#gcx-appo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx appo11y settings get` Get App Observability plugin settings. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx appo11y settings get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx appo11y`](#gcx-appo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx appo11y settings update` Update App Observability plugin settings. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx appo11y settings update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --file string Path to the settings file (JSON or YAML) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx appo11y`](#gcx-appo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant` Send prompts to Grafana Assistant and receive streaming responses via the A2A protocol. Requires Grafana Cloud with OAuth authentication (gcx login with browser flow). Service account tokens are not supported. Note: Grafana Assistant is billed based on tokens consumed, including requests made through gcx. See [https://grafana.com/docs/grafana-cloud/machine-learning/assistant/pricing.md](/docs/grafana-cloud/machine-learning/assistant/pricing.md). **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for assistant ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant conversation` Fetch conversation metadata and message history without sending a new prompt. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for conversation ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant conversation get` Fetch conversation metadata and message history by conversation ID or shared URL. AI SDK conversations include the server-visible main thread. Shared conversations are read-only snapshots in this workflow; transcript retrieval does not establish that a conversation can be continued with ‘gcx assistant prompt –context-id’. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant conversation get [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant conversation get 295a674f-3a3d-44e8-9166-3f8054409f65 gcx assistant conversation get 295a674f-3a3d-44e8-9166-3f8054409f65 -o json gcx assistant conversation get 'https://example.grafana.net/a/grafana-assistant-app/chats/shared/295a674f-3a3d-44e8-9166-3f8054409f65' ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --timeout int HTTP timeout in seconds (default 60) ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant conversation list` List the conversations you can access, most recently updated first. Use this to discover conversation IDs, then pull a transcript with ‘gcx assistant conversation get’ or continue one with ‘gcx assistant prompt –context-id’. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant conversation list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant conversation list gcx assistant conversation list --source assistant --limit 25 gcx assistant conversation list -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --archived-only Show only archived conversations -h, --help help for list --include-archived Include archived conversations --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of conversations to return (default 15) --offset int Number of conversations to skip (for pagination) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --source string Filter by conversation source. Use "all" for every source, or a comma-separated list (e.g. "assistant,cli"). (default "assistant,slack,cli") --timeout int HTTP timeout in seconds (default 60) ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant investigations` Manage Grafana Assistant investigations. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for investigations ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant investigations cancel` Cancel a running investigation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant investigations cancel [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for cancel --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant investigations create` Create a new investigation. On v2-enabled stacks, uses the v2 API with –instruction; falls back to legacy create otherwise. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant investigations create [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant investigations create --instruction="Debug API latency spike" --team=sre ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --description string Investigation description (legacy alias of --instruction) -h, --help help for create --instruction string Investigation instruction (required on v2-enabled stacks) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") --profile-id string Runner profile ID (v2 only) --team strings Team name to scope the investigation to (repeatable, v2 only) --title string Investigation title ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant investigations get` Get investigation detail. On v2-enabled stacks, returns the full session state when the ID is a v2 investigation, and falls back to legacy detail otherwise. v2 output includes both identifiers: investigationId, and the backing chatId that the chat, narrative, and tools subcommands key on. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant investigations get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the investigation in the default browser -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant investigations get-narrative` Show just the assistant-authored prose from a v2 investigation’s chat thread — the text a human would read in the workspace, with tool plumbing stripped. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant investigations get-narrative [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get-narrative --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant investigations list` List investigations. Auto-detects whether the stack supports the v2 investigations API and uses the richer endpoint when available. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant investigations list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Lower bound on creation time, RFC3339 (v2 only) -h, --help help for list --include-legacy Include legacy (pre-v2) investigations (v2 only) (default true) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --label string Filter by label, key:value format (v2 only) --limit int Maximum number of investigations to return (default 50) --offset int Number of investigations to skip (for pagination) --order string Sort order: asc|desc (v2 only) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --q string Search text across title, description, chat name (v2 only) --scope string Visibility scope: all|mine|teams|system (v2 only) --sort string Sort field: createdAt|updatedAt|title|state (v2 only) --state string Filter by investigation state (comma-separated, or "all") --team string Filter to a specific team (v2 only) --to string Upper bound on creation time, RFC3339 (v2 only) --view string Result detail level: full|lite (v2 only) ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant investigations list-evidence` List panel evidence for a v2 investigation — the canonical mapping from report citation keys (panel IDs like p3) to the tool and query that produced each panel. For raw chat-derived tool calls, use `gcx assistant investigations list-tool-calls` instead. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant investigations list-evidence [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-evidence --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant investigations list-messages` List the chat thread that backs a v2 investigation: assistant prose, tool calls (search\_skills, prometheus\_query\_handler, loki\_query\_handler\_investigator, tempo\_query\_handler, …), and tool results. This is the substantive view of what the agent did; use `get-narrative` for the prose-only rendering. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant investigations list-messages [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-messages --include-hidden Include hidden system messages --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --role string Filter messages by role (user|assistant|tool) ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant investigations list-tool-calls` List every tool call the agent made during a v2 investigation, paired with its result. Use –name to filter (e.g. search\_skills, prometheus\_query\_handler). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant investigations list-tool-calls [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-tool-calls --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Filter to tool calls with this name (e.g. search_skills, prometheus_query_handler) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant investigations mode` Change the autonomy mode of a running v2 investigation. Valid modes: low, medium, high. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant investigations mode [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for mode --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant investigations pause` Pause a v2 investigation. Unlike cancel, paused investigations can be resumed. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant investigations pause [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for pause --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant investigations resume` Resume a paused v2 investigation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant investigations resume [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for resume --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant investigations share` Widen the visibility of a v2 investigation. Sharing is additive — teams cannot be removed. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant investigations share [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for share --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") --team strings Team name to share with (repeatable) ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant mcp-servers` Manage remote MCP server integrations in the current Grafana stack’s Assistant settings. MCP servers can be scoped to the current user (“user”, shown as “Just me” in Grafana) or to the stack tenant (“tenant”, shown as “Everybody” in Grafana). Tenant-scoped servers are shared and must be configured with a non-empty authentication header such as Authorization, X-API-Key, or X-Grafana-API-Key. OAuth-based MCP servers, such as GitHub Copilot, are user-scoped. When Grafana reports that OAuth is required after create or update, gcx initiates the Assistant OAuth flow and opens the authorization URL in a browser. **Aliases:** `mcp-server` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List configured MCP servers as text table output gcx assistant mcp-servers list # Add a user-scoped OAuth MCP server and open the authorization URL gcx assistant mcp-servers create --name GitHub --url https://api.githubcopilot.com/mcp # Add a tenant-scoped header-auth MCP server gcx assistant mcp-servers create --name SharedTools --url https://mcp.example.com/mcp \ --scope tenant --header "Authorization=Bearer " ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for mcp-servers ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant mcp-servers create` Create an Assistant MCP server integration. By default, servers are user-scoped. Use –scope tenant for a shared server. Tenant-scoped servers require at least one non-empty authentication header, such as Authorization, X-API-Key, or X-Grafana-API-Key. OAuth-based servers should be created with user scope; gcx opens the OAuth authorization URL when Grafana reports that OAuth is required. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant mcp-servers create [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant mcp-servers create --name GitHub --url https://api.githubcopilot.com/mcp gcx assistant mcp-servers create --name SharedTools --url https://mcp.example.com/mcp \ --scope tenant --header "Authorization=Bearer " gcx assistant mcp-servers create --file server.yaml --if-not-exists ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --application stringArray Assistant application allowed to use this server (repeatable) --description string MCP server description --disabled Disable the MCP server --enabled Enable the MCP server -f, --file string Read MCP server input from a YAML or JSON file --header stringArray Custom header as NAME=VALUE (repeatable; tenant scope requires an auth header) -h, --help help for create --if-not-exists Return an existing server with the same name, URL, and scope instead of failing --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string MCP server display name -o, --output string Output format. One of: agents, json, yaml (default "yaml") --scope string MCP server scope: user or tenant --url string Remote MCP server URL ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant mcp-servers delete` Delete an Assistant MCP server integration. The command prompts for confirmation by default. Use –force to bypass the prompt. GCX\_AUTO\_APPROVE also bypasses the prompt for non-interactive workflows, while agent mode still requires explicit –force for destructive operations. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant mcp-servers delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Delete without confirmation -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant mcp-servers get` Get an Assistant MCP server. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant mcp-servers get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant mcp-servers list` List Assistant MCP server integrations. The default output format is text table output. Use –output wide to include scope and applications, –output table for the legacy table alias, or –output json, yaml, or agents for machine-readable output. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant mcp-servers list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant mcp-servers list gcx assistant mcp-servers list --output text gcx assistant mcp-servers list --output wide gcx assistant mcp-servers list --output json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of integrations to request (default 50) --offset int Number of integrations to skip -o, --output string Output format. One of: agents, json, table, text, wide, yaml (default "text") ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant mcp-servers update` Update an Assistant MCP server integration. Partial updates are merged with the current server before saving. Scope, name, and url are the server’s immutable identity: they cannot be changed via update — delete and recreate the server to change them. Headers follow an explicit write-intent model: a –header with a value overwrites (or creates) that header; if you pass no –header flags at all, every existing header is preserved unchanged; but once you pass any –header flags, they become the full desired header list, so any existing header you don’t list is removed. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant mcp-servers update [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant mcp-servers update GitHub --disabled gcx assistant mcp-servers update SharedTools --description "Shared internal MCP tools" gcx assistant mcp-servers update SharedTools --header "X-API-Key=" ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --application stringArray Assistant application allowed to use this server (repeatable) --description string MCP server description --disabled Disable the MCP server --enabled Enable the MCP server -f, --file string Read MCP server input from a YAML or JSON file --header stringArray Custom header as NAME=VALUE (repeatable; tenant scope requires an auth header) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string MCP server display name -o, --output string Output format. One of: agents, json, yaml (default "yaml") --scope string MCP server scope: user or tenant --url string Remote MCP server URL ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx assistant prompt` Send a single message to Grafana Assistant and receive the response. This is useful for scripting and automation. The response streams via the A2A (Agent-to-Agent) protocol over Server-Sent Events. Note: each prompt consumes billable Grafana Assistant tokens, including requests made through gcx. See [https://grafana.com/docs/grafana-cloud/machine-learning/assistant/pricing.md](/docs/grafana-cloud/machine-learning/assistant/pricing.md). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant prompt [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx assistant prompt "What alerts are firing?" gcx assistant prompt "Show CPU usage" --json gcx assistant prompt "Follow up" --continue ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --agent-id string Agent ID to target (default "grafana_assistant_cli") --context-id string Context ID for conversation threading --continue Continue the previous chat session -h, --help help for prompt --json Output as JSON (streams NDJSON events by default) --no-stream With --json, emit a single JSON object instead of streaming events --timeout int Timeout in seconds when waiting for a response (default 300) ``` Inherits `--config` from [`gcx assistant`](#gcx-assistant-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx cloud` Manage your Grafana Cloud resources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for cloud ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx cloud login` Authenticate with the Grafana Cloud API and store the token in the gcx config. This is different from “gcx login”, which authenticates to a specific Grafana stack instance. “gcx cloud login” authenticates against the Grafana Cloud platform API (grafana.com), enabling commands that manage Cloud resources like stacks and access policies. By default, opens a browser for interactive OAuth2 authentication. EXPERIMENTAL: interactive OAuth login is an experimental flow that stores an OAuth-issued token in the cloud entry’s oauth-token field. Some commands that talk to grafana.com do not yet work with an OAuth token, and the token cannot be refreshed - when it expires, run this command again. Use a Cloud Access Policy token via –cloud-token for operations that do not support OAuth. For non-interactive use (CI/CD, scripts), pass a Cloud Access Policy token directly via –cloud-token. The OAuth and API endpoints default to [https://grafana.com](/). Supplying only one of –oauth-url or –api-url selects that URL for both operations. Supplying both preserves the explicit OAuth-origin/API-destination pair. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx cloud login [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx cloud login gcx cloud login --cloud-token glc_abc123 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --api-url string Base URL for Grafana Cloud API resource calls (stacks etc.) (default "https://grafana.com") --cloud-token string Cloud Access Policy token (skips interactive OAuth flow) --config string Path to the configuration file to use --context string Name of the context to use -h, --help help for login --oauth-manual Complete browser OAuth without a local callback server: gcx prints the URL, then reads the redirect URL that you copy from the browser address bar. Use this when gcx runs on a remote host and the browser runs on your own computer --oauth-url string Base URL for the OAuth login flow (used only by this command) (default "https://grafana.com") --scope strings OAuth2 scopes to request (default [profile,stacks:read,stacks:write,stacks:delete,metrics:write,logs:write,traces:write]) ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx cloud orgs` Discover your Grafana Cloud organisations **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for orgs ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx cloud orgs list` List all organisation memberships returned by the Grafana Cloud. Returns organisation slugs and membership roles. To list stacks within an organisation, use gcx cloud stacks list –org . shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx cloud orgs list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx cloud orgs list gcx cloud orgs list -o json gcx cloud orgs list --json slug,role ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx cloud orgs`](#gcx-cloud-orgs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx cloud stacks` Manage Grafana Cloud stacks (list, create, update, delete) **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for stacks ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx cloud stacks create` Create a new Grafana Cloud stack. This provisions new infrastructure and may incur costs. The stack name, slug, and region cannot be changed after creation - double-check before running. Use –dry-run to preview the request first. Successful creation returns name, orgSlug, slug, status and url. Use gcx cloud stacks get for full details. Specify which organisation to create the stack in with –org. Find out which orgs you are in with gcx cloud orgs list. With an access-policy token, supply your organisation slug directly. Stack slugs may only contain lowercase letters and digits: the slug becomes the stack’s .grafana.net subdomain. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx cloud stacks create [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx cloud stacks create --org example-org --name my-stack --slug mystack --region us --dry-run ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --delete-protection Enable delete protection --description string Short description --dry-run Preview the request without executing it -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --labels strings Labels in key=value format (may be repeated) --name string Stack name (required) --org string Organisation slug (required) -o, --output string Output format. One of: agents, json, table, yaml (default "yaml") --region string Region slug (e.g. us, eu). Use 'gcx cloud stacks list-regions' to list. --slug string Stack slug / subdomain (lowercase letters and digits only; required) --url string Custom domain URL ``` Inherits `--config` from [`gcx cloud stacks`](#gcx-cloud-stacks-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx cloud stacks delete` Delete a Grafana Cloud stack. This permanently deletes a stack and all its data (dashboards, alerts, datasources, metrics, logs, traces). This cannot be undone. Use –dry-run to preview the operation first. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx cloud stacks delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dry-run Preview the operation without executing it --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx cloud stacks`](#gcx-cloud-stacks-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx cloud stacks get` Get details of a single stack. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx cloud stacks get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "yaml") ``` Inherits `--config` from [`gcx cloud stacks`](#gcx-cloud-stacks-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx cloud stacks list` List stacks in an organisation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx cloud stacks list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --org string Organisation slug (required) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx cloud stacks`](#gcx-cloud-stacks-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx cloud stacks list-regions` List available regions for stack creation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx cloud stacks list-regions [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-regions --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx cloud stacks`](#gcx-cloud-stacks-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx cloud stacks update` Update a Grafana Cloud stack. This modifies a live stack. Note that the slug and region cannot be changed. Use –dry-run to preview the request first. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx cloud stacks update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --delete-protection Enable delete protection --description string New description --dry-run Preview the request without executing it -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --labels strings Labels in key=value format (replaces all labels) --name string New stack name --no-delete-protection Disable delete protection -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx cloud stacks`](#gcx-cloud-stacks-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx commands` Output a hierarchical catalog of all CLI commands with metadata including flags, arguments, token cost estimates, and agent hints. Also includes a resource\_types section listing all known Grafana resource types. Use –validate with a configured Grafana context to compare the catalog against live resource discovery and report uncovered or stale types. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx commands [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use --flat Flatten the command tree into a single list -h, --help help for commands --include-hidden Include hidden commands in the output --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "json") --validate Validate catalog against a live Grafana instance (requires configured context) ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx completion` Generate the autocompletion script for gcx for the specified shell. See each sub-command’s help for details on how to use the generated script. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for completion ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx completion bash` Generate the autocompletion script for the bash shell. This script depends on the ‘bash-completion’ package. If it is not installed already, you can install it via your OS’s package manager. To load completions in your current shell session: ``` source <(gcx completion bash) ``` To load completions for every new session, execute once: #### Linux: ``` gcx completion bash > /etc/bash_completion.d/gcx ``` #### macOS: ``` gcx completion bash > $(brew --prefix)/etc/bash_completion.d/gcx ``` You will need to start a new shell for this setup to take effect. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx completion bash ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for bash --no-descriptions disable completion descriptions ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx completion fish` Generate the autocompletion script for the fish shell. To load completions in your current shell session: ``` gcx completion fish | source ``` To load completions for every new session, execute once: ``` gcx completion fish > ~/.config/fish/completions/gcx.fish ``` You will need to start a new shell for this setup to take effect. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx completion fish [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for fish --no-descriptions disable completion descriptions ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx completion powershell` Generate the autocompletion script for powershell. To load completions in your current shell session: ``` gcx completion powershell | Out-String | Invoke-Expression ``` To load completions for every new session, add the output of the above command to your powershell profile. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx completion powershell [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for powershell --no-descriptions disable completion descriptions ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx completion zsh` Generate the autocompletion script for the zsh shell. If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once: ``` echo "autoload -U compinit; compinit" >> ~/.zshrc ``` To load completions in your current shell session: ``` source <(gcx completion zsh) ``` To load completions for every new session, execute once: #### Linux: ``` gcx completion zsh > "${fpath[1]}/_gcx" ``` #### macOS: ``` gcx completion zsh > $(brew --prefix)/share/zsh/site-functions/_gcx ``` You will need to start a new shell for this setup to take effect. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx completion zsh [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for zsh --no-descriptions disable completion descriptions ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx config` View or manipulate configuration settings. –config or $GCX\_CONFIG selects one explicit file and bypasses layering. Otherwise gcx merges every existing source from lowest to highest priority: 1. System configuration: $XDG\_CONFIG\_DIRS/gcx/config.yaml (for example, /etc/xdg/gcx/config.yaml). 2. User configuration: $HOME/.config/gcx/config.yaml, then the platform $XDG\_CONFIG\_HOME fallback. 3. Repository configuration: .gcx.yaml in the current directory. Credential-bearing stack and Cloud entries are atomic across layers; contexts merge only their references and datasource defaults. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for config ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx config check` Check configured contexts for issues. Without –context, checks every configured context. With –context, checks only the selected context. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx config check [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx config check gcx config check --context production ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for check ``` Inherits `--config`, `--context` from [`gcx config`](#gcx-config-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx config current-context` Display the current context name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx config current-context [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx config current-context ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for current-context --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config`, `--context` from [`gcx config`](#gcx-config-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx config edit` Open a config file in your editor. If multiple config files are loaded, specify which one to edit: system, user, or local. If only one config file exists, it is opened directly. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx config edit [type] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --create Create the config file if it doesn't exist -h, --help help for edit ``` Inherits `--config`, `--context` from [`gcx config`](#gcx-config-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx config list-contexts` List the contexts defined in the configuration. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx config list-contexts [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx config list-contexts ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-contexts --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config`, `--context` from [`gcx config`](#gcx-config-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx config path` Display all config files that contribute to the merged configuration, ordered by priority. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx config path [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for path --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config`, `--context` from [`gcx config`](#gcx-config-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx config set` Set a single value in a configuration file. PROPERTY\_NAME is a dot-delimited reference to the value to set. It can either represent a field or a map entry. Paths are literal: they name the exact location in the configuration file, starting from a top-level section (“stacks..”, “cloud..”, “contexts..”, “resources.”, “current-context”). Nothing is resolved against the current context - the path you type is the path you see in “gcx config view”. PROPERTY\_VALUE is the new value to set. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx config set PROPERTY_NAME PROPERTY_VALUE [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Set the "server" field on the "dev-instance" stack gcx config set stacks.dev-instance.grafana.server https://grafana-dev.example # Disable the validation of the server's SSL certificate on a stack gcx config set stacks.dev-instance.grafana.tls.insecure-skip-verify true # Set the default prometheus datasource for a context gcx config set contexts.dev.datasources.prometheus my-prom-uid # Set a cloud entry's token in the local config layer gcx config set --file local cloud.grafana-com.token my-token ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --file string Config layer to write to (system, user, local) -h, --help help for set --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config`, `--context` from [`gcx config`](#gcx-config-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx config unset` Unset a single value in a configuration file. PROPERTY\_NAME is a dot-delimited reference to the value to unset. It can either represent a field or a map entry. Paths are literal: they name the exact location in the configuration file, starting from a top-level section (“stacks..”, “cloud..”, “contexts..”, “resources.”, “current-context”). Nothing is resolved against the current context - the path you type is the path you see in “gcx config view”. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx config unset PROPERTY_NAME [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Unset the "foo" context gcx config unset contexts.foo # Unset the "insecure-skip-verify" TLS setting on the "dev-instance" stack gcx config unset stacks.dev-instance.grafana.tls.insecure-skip-verify # Unset a cloud entry's token in the local config layer gcx config unset --file local cloud.grafana-com.token ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --file string Config layer to write to (system, user, local) -h, --help help for unset --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config`, `--context` from [`gcx config`](#gcx-config-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx config use-context` Set the current context and update the configuration file. Run without arguments to pick a context interactively, or pass “-” to switch back to the previously active context. In agent mode or when stdout is not a TTY, a context name is required. When multiple config files are loaded (e.g. a local .gcx.yaml alongside the user config), use –file to choose which layer to update. **Aliases:** `use` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx config use-context [CONTEXT_NAME] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx config use-context dev-instance gcx config use # interactive picker gcx config use - # previous context # Update the local .gcx.yaml when both user and local configs exist gcx config use-context --file local dev-instance ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --file string Config layer to write to (system, user, local) -h, --help help for use-context --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config`, `--context` from [`gcx config`](#gcx-config-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx config view` Display the current configuration shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx config view [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx config view ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for view --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --minify Remove all information not used by current-context from the output -o, --output string Output format. One of: agents, json, yaml (default "yaml") --raw Display sensitive information ``` Inherits `--config`, `--context` from [`gcx config`](#gcx-config-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dashboards` Create, read, update, delete, and search Grafana dashboards via the Kubernetes-compatible Grafana API. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for dashboards ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dashboards create` Create a dashboard from a manifest shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dashboards create -f [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --api-version string API version to use (e.g. dashboard.grafana.app/v1); defaults to server preferred version -f, --filename string Path to JSON/YAML manifest file ('-' reads from stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx dashboards`](#gcx-dashboards-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dashboards delete` Delete a dashboard **Aliases:** `rm` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dashboards delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --api-version string API version to use (e.g. dashboard.grafana.app/v1); defaults to server preferred version --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx dashboards`](#gcx-dashboards-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dashboards get` Get a Grafana dashboard by its Kubernetes resource name. The `name` argument equals the legacy Dashboard UID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dashboards get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --api-version string API version to use (e.g. dashboard.grafana.app/v1); defaults to server preferred version -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx dashboards`](#gcx-dashboards-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dashboards list` List dashboards **Aliases:** `ls` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dashboards list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --api-version string API version to use (e.g. dashboard.grafana.app/v1); defaults to server preferred version --continue string Continue token for the next page (requires --limit > 0; use the token shown by a previous limited response) -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of dashboards to return in one page (0 fetches all pages) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx dashboards`](#gcx-dashboards-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dashboards list-versions` List dashboard version history shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dashboards list-versions [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --api-version string API version to use (e.g. dashboard.grafana.app/v1); defaults to server preferred version -h, --help help for list-versions --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of revisions to return (0 = all) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx dashboards`](#gcx-dashboards-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dashboards search` Search dashboards using the Grafana full-text search API. The search endpoint is pinned to the v0alpha1 API version and does not support –api-version overrides. Use ‘gcx dashboards list’ to list dashboards with the server-preferred API version. An empty positional query is accepted when at least one –folder or –tag filter is supplied. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dashboards search [query] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Search by title. gcx dashboards search "my dashboard" # Search within a folder. gcx dashboards search --folder my-folder-name # Search by tag with multiple folders. gcx dashboards search --tag prod --folder folder-a --folder folder-b # Output as YAML. gcx dashboards search "metrics" -o yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --deleted Include recently deleted dashboards --folder stringArray Filter by folder name (repeatable) -h, --help help for search --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of results (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --sort string Sort key (e.g. name_sort) --tag stringArray Filter by tag (repeatable) ``` Inherits `--config` from [`gcx dashboards`](#gcx-dashboards-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dashboards snapshot` Render one or more Grafana dashboards or individual panels as PNG images using the Grafana Image Renderer. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dashboards snapshot [name...] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Snapshot a full dashboard gcx dashboards snapshot my-dashboard-name # Snapshot a specific panel gcx dashboards snapshot my-dashboard-name --panel 42 # Snapshot with custom dimensions and time range gcx dashboards snapshot my-dashboard-name --width 1000 --height 500 --theme light --from now-1h --to now # Snapshot using a duration shorthand gcx dashboards snapshot my-dashboard-name --since 6h # Allow up to three minutes for each render gcx dashboards snapshot my-dashboard-name --timeout 3m # Snapshot multiple dashboards to a specific directory gcx dashboards snapshot name1 name2 name3 --output-dir ./snapshots # Snapshot with dashboard template variable overrides gcx dashboards snapshot my-dashboard-name --var cluster=prod --var datasource=prometheus ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --concurrency int Maximum number of concurrent render requests (default 10) --from string Start time (relative like 'now-1h', RFC3339, Unix seconds, or Unix milliseconds) --height int Height of the rendered image in pixels (default: -1/full-page for dashboard, 600 for panel) -h, --help help for snapshot --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --org-id int Grafana organization number (default 1) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --output-dir string Directory to write PNG files to (created if it does not exist) (default ".") --panel int Panel number to render a single panel instead of the full dashboard --since string Duration before now (e.g. '1h', '7d'); expands to --from now-{since} --to now; mutually exclusive with --from/--to --theme string Grafana theme (light or dark) (default "dark") --timeout duration Maximum time for each render as a positive whole-second duration (e.g. 30s, 3m) --to string End time (relative like 'now', RFC3339, Unix seconds, or Unix milliseconds) --tz string Timezone (e.g. 'UTC', 'America/New_York') --var stringToString Dashboard template variable overrides (e.g. --var cluster=prod --var datasource=prometheus) (default []) --width int Width of the rendered image in pixels (default: 1920 for dashboard, 800 for panel) ``` Inherits `--config` from [`gcx dashboards`](#gcx-dashboards-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dashboards update` Update a Grafana dashboard from a JSON or YAML manifest. The manifest must include metadata.resourceVersion captured by a recent ‘gcx dashboards get’. The server uses it for optimistic concurrency: if the dashboard has been modified by another writer since the manifest was fetched, the update fails with a conflict error and the hint to re-fetch. Recommended workflow: shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dashboards get -o yaml > dashboard.yaml # edit dashboard.yaml gcx dashboards update -f dashboard.yaml ``` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dashboards update -f [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --api-version string API version to use (e.g. dashboard.grafana.app/v1); defaults to server preferred version -f, --filename string Path to JSON/YAML manifest file ('-' reads from stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx dashboards`](#gcx-dashboards-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dashboards versions` Manage dashboard version history **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for versions ``` Inherits `--config` from [`gcx dashboards`](#gcx-dashboards-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dashboards versions restore` Restore a dashboard to a previous version shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dashboards versions restore [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --api-version string API version to use (e.g. dashboard.grafana.app/v1); defaults to server preferred version --force Skip confirmation prompt -h, --help help for restore --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --message string Commit message for the restored revision (default: "Restored from version N") -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx dashboards`](#gcx-dashboards-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources` List, inspect, and query Grafana datasources. Use top-level signal commands (metrics, logs, traces, profiles) for datasource-specific queries. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for datasources ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources athena` Query Amazon Athena datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for athena ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources athena describe-table` List the column names of the specified table. Only names are returned, not types or other schema details. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources athena describe-table TABLE [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List columns for a table gcx datasources athena describe-table my_table -d UID --database mydb # With catalog and region gcx datasources athena describe-table my_table -d UID --catalog AwsDataCatalog --database mydb --region us-east-1 # Output as JSON gcx datasources athena describe-table my_table -d UID --database mydb -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --catalog string Data catalog --database string Database name -d, --datasource string Datasource UID (required unless datasources.athena is configured) -h, --help help for describe-table --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --region string AWS region override ``` Inherits `--config` from [`gcx datasources athena`](#gcx-datasources-athena-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources athena list-catalogs` List available Athena data catalogs shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources athena list-catalogs [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all catalogs gcx datasources athena list-catalogs # With explicit datasource and region gcx datasources athena list-catalogs -d UID --region us-east-1 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.athena is configured) -h, --help help for list-catalogs --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --region string AWS region override ``` Inherits `--config` from [`gcx datasources athena`](#gcx-datasources-athena-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources athena list-databases` List databases in an Athena data catalog shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources athena list-databases [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List databases in the default catalog gcx datasources athena list-databases -d UID --catalog AwsDataCatalog # With region override gcx datasources athena list-databases -d UID --catalog AwsDataCatalog --region us-east-1 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --catalog string Data catalog to query -d, --datasource string Datasource UID (required unless datasources.athena is configured) -h, --help help for list-databases --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --region string AWS region override ``` Inherits `--config` from [`gcx datasources athena`](#gcx-datasources-athena-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources athena list-tables` List tables in an Athena database shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources athena list-tables [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List tables in a database gcx datasources athena list-tables -d UID --database mydb # With catalog and region gcx datasources athena list-tables -d UID --catalog AwsDataCatalog --database mydb --region us-east-1 # Output as JSON gcx datasources athena list-tables -d UID --database mydb -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --catalog string Data catalog to query --database string Database to query -d, --datasource string Datasource UID (required unless datasources.athena is configured) -h, --help help for list-tables --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --region string AWS region override ``` Inherits `--config` from [`gcx datasources athena`](#gcx-datasources-athena-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources athena query` Execute a SQL query against an Amazon Athena datasource. EXPR is the SQL query to execute, passed as a positional argument or via –expr. Datasource is resolved from -d flag or datasources.athena in your context. Server-side macros ($\_\_timeFilter, $\_\_dateFilter, etc.) are supported. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources athena query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Simple query gcx datasources athena query 'SELECT count(*) FROM events' # With time macro and explicit datasource gcx datasources athena query -d UID 'SELECT * FROM logs WHERE $__timeFilter(event_time)' --since 1h # With connection overrides gcx datasources athena query -d UID 'SELECT 1' --region us-west-2 --database analytics # Enable result reuse (Athena engine v3) gcx datasources athena query -d UID 'SELECT count(*) FROM events' --result-reuse --ttl-minutes 60 # Disable limit enforcement gcx datasources athena query 'SELECT * FROM big_table' --limit 0 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --catalog string Data catalog override --database string Database override -d, --datasource string Datasource UID (required unless datasources.athena is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Max rows to return (0 disables enforcement) (default 100) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --region string AWS region override --result-reuse Enable Athena query result reuse (engine v3) --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') --ttl-minutes int Cache TTL in minutes for result reuse; 0 disables (default 60) ``` Inherits `--config` from [`gcx datasources athena`](#gcx-datasources-athena-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor` Query Azure Monitor datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for azuremonitor ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor list-metrics` List the Azure Monitor metric definitions available for a resource, including each metric’s primary aggregation, unit, and dimensions. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor list-metrics [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor list-metrics -d UID --subscription SUB_ID \ --resource-group my-rg --namespace Microsoft.Storage/storageAccounts --resource mystorage gcx datasources azuremonitor list-metrics -d UID --subscription SUB_ID \ --resource-group my-rg --namespace Microsoft.Compute/virtualMachines --resource my-vm -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.azuremonitor is configured) -h, --help help for list-metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --namespace string Metric namespace, e.g. Microsoft.Storage/storageAccounts (required; matches the resource type from list-resources) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --resource string Azure resource name; use the slash form for sub-resources, e.g. mystorage/blobServices/default (required) --resource-group string Azure resource group name (required) --subscription string Azure subscription ID (defaults to the datasource's default subscription) ``` Inherits `--config` from [`gcx datasources azuremonitor`](#gcx-datasources-azuremonitor-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor list-resource-groups` List the resource groups in an Azure subscription via an Azure Monitor datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor list-resource-groups [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor list-resource-groups -d UID --subscription SUB_ID gcx datasources azuremonitor list-resource-groups -d UID --subscription SUB_ID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.azuremonitor is configured) -h, --help help for list-resource-groups --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --subscription string Azure subscription ID (defaults to the datasource's default subscription) ``` Inherits `--config` from [`gcx datasources azuremonitor`](#gcx-datasources-azuremonitor-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor list-resources` List the Azure resources in a subscription, optionally scoped to a resource group, via an Azure Monitor datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor list-resources [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor list-resources -d UID --subscription SUB_ID --resource-group my-rg gcx datasources azuremonitor list-resources -d UID --subscription SUB_ID -o json # Uses the datasource's default subscription when --subscription is omitted gcx datasources azuremonitor list-resources -d UID ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.azuremonitor is configured) -h, --help help for list-resources --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --resource-group string Azure resource group name (optional; lists the whole subscription when omitted) --subscription string Azure subscription ID (defaults to the datasource's default subscription) ``` Inherits `--config` from [`gcx datasources azuremonitor`](#gcx-datasources-azuremonitor-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor list-subscriptions` List the Azure subscriptions the Azure Monitor datasource’s credentials can access. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor list-subscriptions [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor list-subscriptions -d UID gcx datasources azuremonitor list-subscriptions -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.azuremonitor is configured) -h, --help help for list-subscriptions --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources azuremonitor`](#gcx-datasources-azuremonitor-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor logs` Query Log Analytics workspaces with KQL **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for logs ``` Inherits `--config` from [`gcx datasources azuremonitor`](#gcx-datasources-azuremonitor-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor logs query` Execute a KQL (Kusto Query Language) query against an Azure Log Analytics workspace. KQL is the query expression, e.g. ‘AppRequests | take 10’. The workspace is identified by –subscription, –resource-group, and –workspace; use list-resources to discover workspaces (type Microsoft.OperationalInsights/workspaces). Datasource is resolved from -d flag or datasources.azuremonitor in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor logs query KQL [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Query a workspace gcx datasources azuremonitor logs query 'AppRequests | take 10' -d UID \ --subscription SUB_ID --resource-group my-rg --workspace my-workspace # With a time range gcx datasources azuremonitor logs query 'AppRequests | summarize count() by bin(TimeGenerated, 5m)' \ -d UID --subscription SUB_ID --resource-group my-rg --workspace my-workspace --since 1h # Output as JSON gcx datasources azuremonitor logs query 'AppTraces | take 5' -d UID \ --subscription SUB_ID --resource-group my-rg --workspace my-workspace -o json # Print a Grafana Explore share link for the executed query gcx datasources azuremonitor logs query 'AppRequests | take 10' -d UID \ --subscription SUB_ID --resource-group my-rg --workspace my-workspace --share-link # Open the executed query in Grafana Explore gcx datasources azuremonitor logs query 'AppRequests | take 10' -d UID \ --subscription SUB_ID --resource-group my-rg --workspace my-workspace --open ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.azuremonitor is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --resource-group string Azure resource group of the workspace (required) --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --subscription string Azure subscription ID (required) --to string End time (RFC3339, Unix timestamp, or relative like 'now') --workspace string Log Analytics workspace name (required) ``` Inherits `--config` from [`gcx datasources azuremonitor`](#gcx-datasources-azuremonitor-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor query` Execute an Azure Monitor metrics query. Queries are structured (subscription, resource group, resource, metric namespace, metric, aggregation) — there is no expression language for Azure Monitor metrics. Use –dimensions (repeatable) to filter or split by dimension values: a specific value filters the series, “\*” splits the result into one series per value. Use the list-subscriptions, list-resource-groups, list-resources, and list-metrics subcommands to discover valid flag values. Datasource is resolved from -d flag or datasources.azuremonitor in your context. Note: datasources configured with “Current User” (Azure AD passthrough) authentication cannot be queried with API tokens or service accounts. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor query [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Query a storage account metric gcx datasources azuremonitor query -d UID --subscription SUB_ID \ --resource-group my-rg --namespace Microsoft.Storage/storageAccounts \ --resource mystorage --metric Transactions --aggregation Total --since 1h # Split the series by a dimension gcx datasources azuremonitor query -d UID --subscription SUB_ID \ --resource-group my-rg --namespace Microsoft.Storage/storageAccounts \ --resource mystorage --metric Transactions --aggregation Total \ --dimensions ApiName='*' --since 1h # Output as JSON gcx datasources azuremonitor query -d UID --subscription SUB_ID \ --resource-group my-rg --namespace Microsoft.Compute/virtualMachines \ --resource my-vm --metric 'Percentage CPU' -o json # Print a Grafana Explore share link for the executed query gcx datasources azuremonitor query -d UID --subscription SUB_ID \ --resource-group my-rg --namespace Microsoft.Compute/virtualMachines \ --resource my-vm --metric 'Percentage CPU' --since 1h --share-link # Open the executed query in Grafana Explore gcx datasources azuremonitor query -d UID --subscription SUB_ID \ --resource-group my-rg --namespace Microsoft.Compute/virtualMachines \ --resource my-vm --metric 'Percentage CPU' --since 1h --open ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --aggregation string Aggregation: Average, Total, Maximum, Minimum, or Count (must be supported by the metric; see list-metrics) (default "Average") -d, --datasource string Datasource UID (required unless datasources.azuremonitor is configured) --dimensions stringToString Dimension key=value filters (repeatable, e.g. --dimensions ApiName=GetBlob); use "*" as the value to split the result by that dimension (default []) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --metric string Metric name, e.g. Transactions (required) --namespace string Metric namespace, e.g. Microsoft.Storage/storageAccounts (required) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --region string Azure region, e.g. uksouth (optional; used for multi-resource queries) --resource string Azure resource name; use the slash form for sub-resources, e.g. mystorage/blobServices/default (required) --resource-group string Azure resource group name (required) --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --subscription string Azure subscription ID (defaults to the datasource's default subscription) --time-grain string Time grain as an ISO 8601 duration (e.g. PT1M, PT1H) or "auto" to fit the time range (default "auto") --to string End time (RFC3339, Unix timestamp, or relative like 'now') --top string Maximum number of dimension value series to return (only with --dimensions) ``` Inherits `--config` from [`gcx datasources azuremonitor`](#gcx-datasources-azuremonitor-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor resource-graph` Query Azure Resource Graph with KQL **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for resource-graph ``` Inherits `--config` from [`gcx datasources azuremonitor`](#gcx-datasources-azuremonitor-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor resource-graph query` Execute a KQL (Kusto Query Language) query against Azure Resource Graph, Azure’s inventory of resources across subscriptions. KQL is the query expression, e.g. ‘Resources | project name, type | limit 10’. Pass –subscription (repeatable) to scope the query. Datasource is resolved from -d flag or datasources.azuremonitor in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor resource-graph query KQL [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List resources by type gcx datasources azuremonitor resource-graph query \ 'Resources | summarize count() by type | order by count_ desc' \ -d UID --subscription SUB_ID # Query across multiple subscriptions, output as JSON gcx datasources azuremonitor resource-graph query 'Resources | project name, type, location' \ -d UID --subscription SUB_A --subscription SUB_B -o json # Print a Grafana Explore share link for the executed query gcx datasources azuremonitor resource-graph query 'Resources | project name, type' \ -d UID --subscription SUB_ID --share-link # Open the executed query in Grafana Explore gcx datasources azuremonitor resource-graph query 'Resources | project name, type' \ -d UID --subscription SUB_ID --open ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.azuremonitor is configured) -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --subscription stringArray Azure subscription ID to query (repeatable; at least one required) ``` Inherits `--config` from [`gcx datasources azuremonitor`](#gcx-datasources-azuremonitor-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources bigquery` Query BigQuery datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for bigquery ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources bigquery describe-table` Show column name, data type, and nullability for each column in a table via INFORMATION\_SCHEMA.COLUMNS. The dataset is required, supplied either in the table name (DATASET.TABLE or PROJECT.DATASET.TABLE) or via –dataset. When the project is omitted, the datasource’s default project is used. At most 1000 columns are returned; if a table is wider, a warning is printed on stderr rather than silently truncating. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources bigquery describe-table TABLE [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Describe a table in a dataset (default project; equivalent forms) gcx datasources bigquery describe-table my_dataset.events gcx datasources bigquery describe-table events --dataset my_dataset # Describe a table in a specific project (equivalent forms) gcx datasources bigquery describe-table my-project.my_dataset.events gcx datasources bigquery describe-table events --project my-project --dataset my_dataset # Output as JSON gcx datasources bigquery describe-table my_dataset.events -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dataset string Dataset containing the table (required) -d, --datasource string Datasource UID (required unless datasources.bigquery is configured) -h, --help help for describe-table --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --project string GCP project ID (default: the datasource's default project) ``` Inherits `--config` from [`gcx datasources bigquery`](#gcx-datasources-bigquery-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources bigquery list-datasets` List datasets (schemas) in a BigQuery project via INFORMATION\_SCHEMA.SCHEMATA. When –project is omitted, the datasource’s default project is queried. At most 1000 datasets are returned; if more match, a warning is printed on stderr rather than silently truncating. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources bigquery list-datasets [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List datasets in the default project gcx datasources bigquery list-datasets # List datasets in a specific project gcx datasources bigquery list-datasets --project my-project # Output as JSON gcx datasources bigquery list-datasets -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.bigquery is configured) -h, --help help for list-datasets --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --project string GCP project ID (default: the datasource's default project) ``` Inherits `--config` from [`gcx datasources bigquery`](#gcx-datasources-bigquery-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources bigquery list-tables` List tables in a BigQuery dataset via INFORMATION\_SCHEMA.TABLES. –dataset is required. When –project is omitted, the datasource’s default project is used. Run ’list-datasets’ to discover available datasets. At most 1000 tables are returned; if more match, a warning is printed on stderr rather than silently truncating. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources bigquery list-tables [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List tables in a dataset (default project) gcx datasources bigquery list-tables --dataset my_dataset # List tables in a dataset in a specific project gcx datasources bigquery list-tables --project my-project --dataset my_dataset # Output as JSON gcx datasources bigquery list-tables --dataset my_dataset -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dataset string Dataset to list tables from (required) -d, --datasource string Datasource UID (required unless datasources.bigquery is configured) -h, --help help for list-tables --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --project string GCP project ID (default: the datasource's default project) ``` Inherits `--config` from [`gcx datasources bigquery`](#gcx-datasources-bigquery-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources bigquery query` Execute a GoogleSQL query against a BigQuery datasource. EXPR is the SQL query to execute, passed as a positional argument or via –expr. Datasource is resolved from -d flag or datasources.bigquery in your context. Reference tables as `project.dataset.table`; when the project is omitted the datasource’s default project is used. Server-side macros ($\_\_timeFilter, etc.) are supported against TIMESTAMP columns; a DATETIME column needs an explicit CAST(col AS TIMESTAMP) first, since $\_\_timeFilter substitutes a TIMESTAMP literal BigQuery won’t compare against DATETIME directly. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources bigquery query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Simple query gcx datasources bigquery query 'SELECT count(*) FROM `my-project.my_dataset.events`' # Explicit datasource gcx datasources bigquery query -d UID 'SELECT * FROM `my_dataset.logs`' --since 1h # $__timeFilter against a TIMESTAMP column gcx datasources bigquery query -d UID 'SELECT * FROM `my_dataset.events` WHERE $__timeFilter(event_ts)' --since 1h # Output as JSON gcx datasources bigquery query -d UID 'SELECT 1' -o json # Print a Grafana Explore share link for the executed query gcx datasources bigquery query 'SELECT 1' --share-link # Disable limit enforcement gcx datasources bigquery query 'SELECT * FROM `my_dataset.big_table`' --limit 0 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.bigquery is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Max rows to return; requests above 1000 are capped, with a warning (0 disables enforcement) (default 100) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources bigquery`](#gcx-datasources-bigquery-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources clickhouse` Query ClickHouse datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for clickhouse ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources clickhouse describe-table` Show column details including name, type, default, and comment for each column in the specified table. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources clickhouse describe-table TABLE [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Describe a table in the default database gcx datasources clickhouse describe-table otel_logs # Describe a table in a specific database gcx datasources clickhouse describe-table otel_logs --database otel # Output as JSON gcx datasources clickhouse describe-table otel_logs -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --database string Database name (default: "default") -d, --datasource string Datasource UID (required unless datasources.clickhouse is configured) -h, --help help for describe-table --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx datasources clickhouse`](#gcx-datasources-clickhouse-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources clickhouse list-tables` List tables from all non-system databases, or filter to a specific database. Shows database, name, engine, total\_rows, and total\_bytes for each table. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources clickhouse list-tables [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all tables gcx datasources clickhouse list-tables # Filter to a specific database gcx datasources clickhouse list-tables --database otel # Output as JSON gcx datasources clickhouse list-tables -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --database string Filter tables to this database -d, --datasource string Datasource UID (required unless datasources.clickhouse is configured) -h, --help help for list-tables --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx datasources clickhouse`](#gcx-datasources-clickhouse-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources clickhouse query` Execute a SQL query against a ClickHouse datasource. EXPR is the SQL query to execute, passed as a positional argument or via –expr. Datasource is resolved from -d flag or datasources.clickhouse in your context. Server-side macros ($\_\_timeFilter, $\_\_timeInterval, etc.) are supported. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources clickhouse query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Simple query gcx datasources clickhouse query 'SELECT count() FROM events' # With time macro and explicit datasource gcx datasources clickhouse query -d UID 'SELECT * FROM logs WHERE $__timeFilter(timestamp)' --since 1h # Output as JSON gcx datasources clickhouse query -d UID 'SELECT 1' -o json # Print a Grafana Explore share link for the executed query gcx datasources clickhouse query 'SELECT 1' --share-link # Disable limit enforcement gcx datasources clickhouse query 'SELECT * FROM big_table' --limit 0 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.clickhouse is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Max rows to return (0 disables enforcement) (default 100) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources clickhouse`](#gcx-datasources-clickhouse-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudmonitoring` Query Google Cloud Monitoring datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for cloudmonitoring ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudmonitoring list-metrics` List the Cloud Monitoring metric descriptors available in a project, with kind, value type, and unit. Use –service to narrow the listing (recommended; unfiltered listings page through every metric in the project and can be slow). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudmonitoring list-metrics [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudmonitoring list-metrics -d UID --project my-project --service compute.googleapis.com gcx datasources cloudmonitoring list-metrics -d UID --project my-project --service monitoring.googleapis.com -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.cloudmonitoring is configured) -h, --help help for list-metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --project string GCP project ID (required) --service string Restrict to metrics of this service prefix, e.g. compute.googleapis.com (recommended: unfiltered listings page through every metric and can be slow) ``` Inherits `--config` from [`gcx datasources cloudmonitoring`](#gcx-datasources-cloudmonitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudmonitoring list-projects` List the Google Cloud projects the datasource’s credentials can access. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudmonitoring list-projects [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudmonitoring list-projects -d UID gcx datasources cloudmonitoring list-projects -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.cloudmonitoring is configured) -h, --help help for list-projects --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources cloudmonitoring`](#gcx-datasources-cloudmonitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudmonitoring query` Execute a Google Cloud Monitoring (formerly Stackdriver) metrics query. Queries are structured (project, metric type, reducer, aligner) — there is no expression language. Use –group-by to split the result into one series per label value, and –filter to narrow by labels. –group-by only has an effect when –reducer is set to something other than the default REDUCE\_NONE: GCP’s Aggregation API ignores groupByFields unless a cross-series reducer combines them, so –group-by without –reducer is rejected rather than silently returning one ungrouped series. –filter matches are exact and case-sensitive, not regex or wildcard — GCM has no equivalent of “=~”. Repeated –filter flags are AND-combined. A filter like “zone=~us-east.\*” is not a regex match; it is a literal equality comparison against that exact string, which will not match real zone values and returns “No data” with no error. Use list-projects and list-metrics to discover valid flag values. Datasource is resolved from -d flag or datasources.cloudmonitoring in your context. Use –share-link to print the equivalent Grafana Explore URL after the query, or –open to open it in your browser. Note: when no –from/–to/–since flags are provided, the link encodes “now-1h”/“now” (relative), not the absolute window the CLI just queried. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudmonitoring query [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # CPU utilization across a project gcx datasources cloudmonitoring query -d UID --project my-project \ --metric compute.googleapis.com/instance/cpu/utilization --since 1h # Print a Grafana Explore share link for the executed query gcx datasources cloudmonitoring query -d UID --project my-project \ --metric compute.googleapis.com/instance/cpu/utilization --since 1h --share-link # Run the query and continue in Grafana Explore gcx datasources cloudmonitoring query -d UID --project my-project \ --metric compute.googleapis.com/instance/cpu/utilization --since 1h --open # Split by instance, mean-reduced gcx datasources cloudmonitoring query -d UID --project my-project \ --metric compute.googleapis.com/instance/cpu/utilization \ --reducer REDUCE_MEAN --group-by resource.label.instance_name --since 1h # Chart it gcx datasources cloudmonitoring query -d UID --project my-project \ --metric compute.googleapis.com/instance/cpu/utilization --since 6h -o graph ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --aligner string Per-series aligner: ALIGN_MEAN, ALIGN_SUM, ALIGN_MIN, ALIGN_MAX, ALIGN_RATE, ALIGN_DELTA, ... (default "ALIGN_MEAN") --alignment-period string Alignment period, e.g. +60s (default: auto-fit the time range) -d, --datasource string Datasource UID (required unless datasources.cloudmonitoring is configured) --filter stringToString Label filter key=value (repeatable, AND-combined, exact-match and case-sensitive only — no regex/wildcard; e.g. --filter resource.label.zone=us-east1-b) (default []) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --group-by stringArray Label to split series by, e.g. resource.label.instance_name (repeatable; requires --reducer other than REDUCE_NONE) -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --metric string Metric type, e.g. compute.googleapis.com/instance/cpu/utilization (required) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --project string GCP project ID (required) --reducer string Cross-series reducer: REDUCE_NONE, REDUCE_MEAN, REDUCE_SUM, REDUCE_MIN, REDUCE_MAX, REDUCE_COUNT, ... (default "REDUCE_NONE") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources cloudmonitoring`](#gcx-datasources-cloudmonitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudwatch` Query AWS CloudWatch datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for cloudwatch ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudwatch list-accounts` List the AWS accounts accessible via this CloudWatch datasource. Only returns data for cross-account monitoring datasources; other datasources may return a 404 which is surfaced as a clear error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-accounts [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-accounts -d UID --region us-east-1 gcx datasources cloudwatch list-accounts -d UID --region us-east-1 -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.cloudwatch is configured) -h, --help help for list-accounts --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --region string AWS region (required) ``` Inherits `--config` from [`gcx datasources cloudwatch`](#gcx-datasources-cloudwatch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudwatch list-dimensions` List the dimension keys available for a CloudWatch metric within a namespace and region. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-dimensions [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-dimensions -d UID --region us-east-1 --namespace AWS/EC2 --metric CPUUtilization gcx datasources cloudwatch list-dimensions -d UID --region us-east-1 --namespace AWS/EC2 --metric CPUUtilization -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --account-id string AWS account ID for cross-account monitoring (or 'all') -d, --datasource string Datasource UID (required unless datasources.cloudwatch is configured) -h, --help help for list-dimensions --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --metric string CloudWatch metric name (required) --namespace string CloudWatch namespace (required) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --region string AWS region (required) ``` Inherits `--config` from [`gcx datasources cloudwatch`](#gcx-datasources-cloudwatch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudwatch list-metrics` List the CloudWatch metrics available within a namespace and region from a CloudWatch datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-metrics [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-metrics -d UID --region us-east-1 --namespace AWS/EC2 gcx datasources cloudwatch list-metrics -d UID --region us-east-1 --namespace AWS/Lambda -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --account-id string AWS account ID for cross-account monitoring (or 'all') -d, --datasource string Datasource UID (required unless datasources.cloudwatch is configured) -h, --help help for list-metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --namespace string CloudWatch namespace (required) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --region string AWS region (required) ``` Inherits `--config` from [`gcx datasources cloudwatch`](#gcx-datasources-cloudwatch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudwatch list-namespaces` List the CloudWatch namespaces visible in the given region from a CloudWatch datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-namespaces [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-namespaces -d UID --region us-east-1 gcx datasources cloudwatch list-namespaces -d UID --region us-east-1 -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --account-id string AWS account ID for cross-account monitoring (or 'all') -d, --datasource string Datasource UID (required unless datasources.cloudwatch is configured) -h, --help help for list-namespaces --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --region string AWS region (required) ``` Inherits `--config` from [`gcx datasources cloudwatch`](#gcx-datasources-cloudwatch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudwatch list-regions` List the AWS regions exposed by the configured CloudWatch datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-regions [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-regions -d UID gcx datasources cloudwatch list-regions -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.cloudwatch is configured) -h, --help help for list-regions --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources cloudwatch`](#gcx-datasources-cloudwatch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudwatch query` Execute a CloudWatch metric query. Queries are structured (namespace, metric, region, statistic, period, dimensions) — there is no expression language for CloudWatch. Use –dimensions (repeatable) for dimension filters, or omit them to aggregate across all combinations. Use –share-link to print the equivalent Grafana Explore URL after the query. Note: when no –from/–to/–since flags are provided, the share link encodes “now-1h”/“now” (relative), not the absolute window the CLI just queried. Cross-account monitoring datasources: if your datasource is configured for cross-account monitoring (a “monitoring account”), –dimensions filters scope to the datasource’s own account by default. To surface dimensions from source accounts, pass –account-id (run list-accounts to discover IDs) or –account-id all to query all linked accounts. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch query [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Query with required flags gcx datasources cloudwatch query -d UID --region us-east-1 --namespace AWS/EC2 --metric CPUUtilization # With time range gcx datasources cloudwatch query -d UID --region us-east-1 --namespace AWS/EC2 --metric CPUUtilization --since 1h # With dimension filter gcx datasources cloudwatch query -d UID --region us-east-1 --namespace AWS/EC2 --metric CPUUtilization \ --dimensions InstanceId=i-0123456789abcdef0 --since 1h # Print as JSON gcx datasources cloudwatch query -d UID --region us-east-1 --namespace AWS/EC2 --metric CPUUtilization -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --account-id string AWS account ID for cross-account monitoring; pass 'all' to query all linked accounts, or a specific ID from list-accounts. Required to surface dimensions from source accounts on monitoring datasources. -d, --datasource string Datasource UID (required unless datasources.cloudwatch is configured) --dimensions stringToString Dimension key=value pairs (repeatable, e.g. --dimensions InstanceId=i-abc) (default []) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --metric string CloudWatch metric name, e.g. CPUUtilization (required) --namespace string CloudWatch namespace, e.g. AWS/EC2 (required) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --period string Period in seconds (e.g. 60, 300) or "auto" to let CloudWatch pick a period that fits the time range (default "auto") --region string AWS region, e.g. us-east-1 (required) --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --statistic string Statistic: Average, Sum, Maximum, Minimum, SampleCount, or a percentile/trimmed-mean (e.g. p95, p99, tm99) (default "Average") --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources cloudwatch`](#gcx-datasources-cloudwatch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources create` Create a datasource instance from a declarative manifest file. The manifest is a Kubernetes-style envelope. spec.type is the plugin ID (e.g. grafana-sentry-datasource) and selects the API group. Secret values go in the top-level secure block via {create: }, {fromEnv: `}, or {fromFile: }; they are never returned on read.` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources create [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Create a datasource from a YAML manifest gcx datasources create -f sentry.yaml # Create from stdin cat sentry.yaml | gcx datasources create -f - # Preview without writing gcx datasources create -f sentry.yaml --dry-run ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use --dry-run Render the object that would be created without writing it -f, --filename string File containing the datasource manifest (use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") --secrets-file string File containing secret values to merge into the secure block ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources delete` Delete one or more datasources by UID. Deletion prompts for confirmation unless –dry-run, –force/–yes, or enabled GCX\_AUTO\_APPROVE. Agent mode does not auto-approve destructive deletion: without an explicit bypass it fails with an actionable error. Exit codes: 0 (all deleted), 4 (some deletions failed). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources delete UID... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Delete one datasource (prompts to confirm) gcx datasources delete sentry-dev # Delete several without prompting gcx datasources delete sentry-dev sentry-staging --yes # Preview only gcx datasources delete sentry-dev --dry-run ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use --dry-run Report what would be deleted without deleting --force Skip the confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") -y, --yes Skip the confirmation prompt ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources elasticsearch` Query Elasticsearch datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for elasticsearch ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources elasticsearch list-fields` List the mapped fields and their types, per index. Nested object fields are flattened with dotted names. Use these names in Lucene queries and –group-by. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources elasticsearch list-fields [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # All fields across indices gcx datasources elasticsearch list-fields # Fields of one index gcx datasources elasticsearch list-fields -d UID --index grafana-logs -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.elasticsearch is configured) -h, --help help for list-fields --index string Restrict to this index or index pattern --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources elasticsearch`](#gcx-datasources-elasticsearch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources elasticsearch list-indices` List the indices visible to an Elasticsearch datasource, with their mapped field counts. Pass –index to restrict to one index or pattern; fetching the mapping for every index can hit the response size cap on a large cluster. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources elasticsearch list-indices [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources elasticsearch list-indices gcx datasources elasticsearch list-indices -d UID -o json # Restrict to one index or pattern gcx datasources elasticsearch list-indices -d UID --index grafana-logs ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.elasticsearch is configured) -h, --help help for list-indices --index string Restrict to this index or index pattern --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources elasticsearch`](#gcx-datasources-elasticsearch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources elasticsearch metrics` Run a metric aggregation bucketed by a time histogram, optionally split into series by a terms field. EXPR is a Lucene query string scoping the documents; omit it to aggregate all. Returns (time, value, series) rows. Use –step to control bucket size. Datasource is resolved from -d flag or datasources.elasticsearch in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources elasticsearch metrics [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Document count over time gcx datasources elasticsearch metrics --since 6h # Error count per app gcx datasources elasticsearch metrics 'level:error' --group-by app.keyword --since 6h # Average value of a numeric field gcx datasources elasticsearch metrics --agg avg --field duration_ms --since 1h -o json # Print a Grafana Explore share link for the executed query gcx datasources elasticsearch metrics 'level:error' --since 6h --share-link # Continue the same aggregation in Grafana Explore gcx datasources elasticsearch metrics 'level:error' --since 6h --open ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --agg string Metric aggregation: count, avg, sum, min, max, or cardinality (default "count") -d, --datasource string Datasource UID (required unless datasources.elasticsearch is configured) --expr string Query expression (alternative to positional argument) --field string Field to aggregate (required unless --agg count) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --group-by string Split series by this field's terms (use .keyword for text fields) --group-size int Max number of series when using --group-by (default 10) -h, --help help for metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --time-field string Time field for the date histogram bucket (defaults to the datasource's configured time field if omitted) --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources elasticsearch`](#gcx-datasources-elasticsearch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources elasticsearch query` Search documents in an Elasticsearch datasource with a Lucene query. EXPR is a Lucene query string (e.g. ‘app:frontend AND level:error’); omit it to match all documents in the time range. The index pattern comes from the datasource configuration. –mode documents (default) returns raw source documents. –mode logs returns the same documents newest-first with plugin-internal fields (\_source, sort, highlight, \_type) omitted, matching how Grafana Explore’s Logs view reads them. Datasource is resolved from -d flag or datasources.elasticsearch in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources elasticsearch query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Match all documents in the last hour gcx datasources elasticsearch query --since 1h # Lucene query with explicit datasource gcx datasources elasticsearch query -d UID 'app:frontend AND level:error' --since 1h # Newest-first logs, plugin-internal fields omitted gcx datasources elasticsearch query -d UID 'level:error' --mode logs --since 6h --limit 50 # Output as JSON, limit results gcx datasources elasticsearch query -d UID 'datacenter:us-east' --limit 20 -o json # Print a Grafana Explore share link for the executed query gcx datasources elasticsearch query 'level:error' --since 1h --share-link # Continue the same search in Grafana Explore gcx datasources elasticsearch query 'level:error' --since 1h --open ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.elasticsearch is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Max documents to return (1-1000) (default 100) --mode string Search mode: "documents" (raw documents) or "logs" (newest-first, plugin-internal fields omitted) (default "documents") --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources elasticsearch`](#gcx-datasources-elasticsearch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources get` Get a datasource by its UID. The default text output shows a human-readable detail view. -o yaml/json emits an apply-ready manifest that can be edited and re-applied via update -f -. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources get UID [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Human-readable detail gcx datasources get my-prometheus # Apply-ready manifest (round-trips into update -f -) gcx datasources get my-prometheus -o yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources health` Check datasource health via the Grafana datasource health endpoint. With a UID, checks a single datasource. Without arguments, checks all datasources. Use –type to check all datasources of a given plugin type. Exit codes distinguish resource failure from command failure: 0 - all checked datasources are healthy 4 - the check ran but one or more datasources are unhealthy (resource failure) 1/2/3 - the check could not run (operational, usage, or auth failure) shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources health [UID] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Check a single datasource gcx datasources health my-ds-uid # Check all datasources gcx datasources health # Check all datasources of a given type gcx datasources health --type grafana-sentry-datasource ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use -h, --help help for health --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") -t, --type string Filter by datasource type (e.g., prometheus, grafana-sentry-datasource) ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources infinity` Query Infinity datasources (JSON, CSV, XML, GraphQL from any URL) **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for infinity ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources infinity query` Query a Grafana Infinity datasource using its saved configuration. The datasource’s URL, type, method, and headers are read from its saved configuration. EXPR is an optional root selector expression (JSONPath for JSON, XPath for XML/HTML) that narrows the returned data. Datasource is resolved from -d flag or datasources.infinity in your context. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources infinity query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Query using datasource UID gcx datasources infinity query -d UID # Narrow results with a JSONPath expression gcx datasources infinity query -d UID '$.items' # Output as JSON gcx datasources infinity query -d UID '$.results' -o json # Query with a time range gcx datasources infinity query -d UID --from now-24h --to now ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.infinity is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources infinity`](#gcx-datasources-infinity-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources influxdb` Query InfluxDB datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for influxdb ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources influxdb list-field-keys` List field keys from an InfluxDB datasource. Only supported in InfluxQL mode. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources influxdb list-field-keys [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all field keys (use datasource UID, not name) gcx datasources influxdb list-field-keys -d UID # Filter by measurement gcx datasources influxdb list-field-keys -d UID --measurement cpu # Output as JSON gcx datasources influxdb list-field-keys -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.influxdb is configured) -h, --help help for list-field-keys --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -m, --measurement string Filter by measurement name -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources influxdb`](#gcx-datasources-influxdb-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources influxdb list-measurements` List measurement names from an InfluxDB datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources influxdb list-measurements [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all measurements (use datasource UID, not name) gcx datasources influxdb list-measurements -d UID # List measurements with Flux mode (requires --bucket) gcx datasources influxdb list-measurements -d UID --bucket my-bucket # Output as JSON gcx datasources influxdb list-measurements -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --bucket string Bucket name for Flux mode (defaults to datasource defaultBucket) -d, --datasource string Datasource UID (required unless datasources.influxdb is configured) -h, --help help for list-measurements --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources influxdb`](#gcx-datasources-influxdb-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources influxdb list-tag-keys` List tag keys from an InfluxDB datasource. Only supported in InfluxQL mode. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources influxdb list-tag-keys [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all tag keys (use datasource UID, not name) gcx datasources influxdb list-tag-keys -d UID # Filter by measurement gcx datasources influxdb list-tag-keys -d UID --measurement cpu # Output as JSON gcx datasources influxdb list-tag-keys -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.influxdb is configured) -h, --help help for list-tag-keys --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -m, --measurement string Filter by measurement name -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources influxdb`](#gcx-datasources-influxdb-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources influxdb list-tag-values` List tag values for a given key from an InfluxDB datasource. Only supported in InfluxQL mode. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources influxdb list-tag-values [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List values for a tag key (use datasource UID, not name) gcx datasources influxdb list-tag-values -d UID --key host # Filter by measurement gcx datasources influxdb list-tag-values -d UID --key host --measurement cpu # Output as JSON gcx datasources influxdb list-tag-values -d UID --key host -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.influxdb is configured) -h, --help help for list-tag-values --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -k, --key string Tag key to get values for (required) -m, --measurement string Filter by measurement name -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources influxdb`](#gcx-datasources-influxdb-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources influxdb query` Execute a query against an InfluxDB datasource. EXPR is the InfluxQL, Flux, or SQL expression to evaluate, passed as a positional argument or via –expr. The query language mode is auto-detected from the datasource configuration. Datasource is resolved from -d flag or datasources.influxdb in your context. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources influxdb query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # InfluxQL instant query gcx datasources influxdb query -d UID 'SELECT mean("value") FROM "cpu" WHERE time > now() - 1h' # InfluxQL range query gcx datasources influxdb query -d UID 'SELECT mean("value") FROM "cpu"' --from now-1h --to now # Output as JSON gcx datasources influxdb query -d UID 'SELECT * FROM "cpu" LIMIT 10' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.influxdb is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources influxdb`](#gcx-datasources-influxdb-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources list` List all datasources configured in Grafana. Filter by type and/or name (case-insensitive substring match). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all datasources gcx datasources list # List only Prometheus datasources gcx datasources list --type prometheus # Filter by name substring (matches "prometheus-prod-eu", "loki-prod-us", ...) gcx datasources list --name prod # Combine type and name filters gcx datasources list --type prometheus --name prod # Output as JSON gcx datasources list -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of datasources to return. 0 means all results are returned --name string Filter by datasource name (case-insensitive substring match) -o, --output string Output format. One of: agents, json, table, yaml (default "table") -t, --type string Filter by datasource type (e.g., prometheus, loki) ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources loki` Query Loki datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for loki ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources loki labels` List all labels or get values for a specific label from a Loki datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources loki labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all labels (use datasource UID, not name) gcx datasources loki labels -d UID # Get values for a specific label gcx datasources loki labels -d UID --label job # Filter labels with a query gcx datasources loki labels -d UID --query '{app="foo"}' # Filter label values with a query gcx datasources loki labels -d UID --label job --query '{app="foo"}' # Output as JSON gcx datasources loki labels -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.loki is configured) -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label string Get values for this label (omit to list all labels) -o, --output string Output format. One of: agents, json, table, yaml (default "table") -q, --query string LogQL stream selector to scope labels, e.g. '{app="foo"}' (pipeline stages are not supported) ``` Inherits `--config` from [`gcx datasources loki`](#gcx-datasources-loki-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources loki metrics` Execute a metric LogQL query and return time-series results. EXPR is a metric LogQL expression (e.g., rate, count\_over\_time, sum). Datasource is resolved from -d flag or datasources.loki in your context. Unlike ’logs query’ which returns log lines, ’logs metrics’ returns time-series data with proper table, graph, and JSON formatters. Instant vs range is deduced from time flags: no time flags = instant query, –since or –from/–to = range query. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources loki metrics [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Rate of log lines over 5 minutes gcx datasources loki metrics 'rate({job="varlogs"}[5m])' --since 1h -o table # Count of error logs gcx datasources loki metrics 'count_over_time({job="varlogs"} |= "error" [5m])' --since 1h # Print a Grafana Explore share link for the query gcx datasources loki metrics 'rate({job="varlogs"}[5m])' --share-link # Line chart output gcx datasources loki metrics -d loki-001 'rate({job="varlogs"}[5m])' --since 1h -o graph # Output as JSON gcx datasources loki metrics 'rate({job="varlogs"}[5m])' --since 1h -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.loki is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources loki`](#gcx-datasources-loki-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources loki query` Execute a LogQL query against a Loki datasource. EXPR is the LogQL expression to evaluate. Datasource is resolved from -d flag or datasources.loki in your context. Default table output is optimized for humans. Use -o raw for original line bodies or -o json for the full structured response. Default –limit is 50; use –limit 0 for no cap. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources loki query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Query logs using configured default datasource gcx datasources loki query '{job="varlogs"}' # Query with explicit datasource UID gcx datasources loki query -d UID '{job="varlogs"} |= "error"' # Print a Grafana Explore share link for the query gcx datasources loki query '{job="varlogs"}' --share-link # Raw line bodies only gcx datasources loki query -d UID '{job="varlogs"}' -o raw # Output as JSON gcx datasources loki query -d UID '{job="varlogs"}' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.loki is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of log lines to return (0 means no limit) (default 50) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, raw, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources loki`](#gcx-datasources-loki-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources loki series` List log streams (series) from a Loki datasource using LogQL stream selectors. At least one –match selector is required. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources loki series [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List series matching a selector (use datasource UID, not name) gcx datasources loki series -d UID --match '{job="varlogs"}' # Match with regex and multiple labels gcx datasources loki series -d UID --match '{container_name=~"prometheus.*", component="server"}' # Multiple matchers (OR logic) gcx datasources loki series -d UID --match '{job="varlogs"}' --match '{namespace="default"}' # Output as JSON gcx datasources loki series -d UID --match '{job="varlogs"}' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.loki is configured) -h, --help help for series --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -M, --match stringArray LogQL stream selector (required, e.g., '{job="varlogs"}') -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources loki`](#gcx-datasources-loki-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources mssql` Query Microsoft SQL Server datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for mssql ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources mssql describe-table` List the columns of the specified table from INFORMATION\_SCHEMA.COLUMNS, reporting name, data type, nullability, max length, and default. Disambiguate a table that exists in multiple schemas with a schema-qualified name (SCHEMA.TABLE) or the –schema flag. INFORMATION\_SCHEMA is per-database, so this only sees tables in the datasource’s configured database — it cannot describe a table in another database on the same server. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources mssql describe-table TABLE [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Describe a table gcx datasources mssql describe-table WORLD_DATA # Restrict to a schema (equivalent forms) gcx datasources mssql describe-table dbo.WORLD_DATA gcx datasources mssql describe-table WORLD_DATA --schema dbo # Output as JSON gcx datasources mssql describe-table WORLD_DATA -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.mssql is configured) -h, --help help for describe-table --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --schema string Schema the table belongs to (e.g. dbo) ``` Inherits `--config` from [`gcx datasources mssql`](#gcx-datasources-mssql-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources mssql list-tables` List base tables and views from INFORMATION\_SCHEMA.TABLES, optionally filtered to a single schema. Reports schema, name, and type for each. INFORMATION\_SCHEMA is per-database, so this only sees tables in the datasource’s configured database — it cannot list tables in another database on the same server. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources mssql list-tables [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all tables and views gcx datasources mssql list-tables # Filter to the dbo schema gcx datasources mssql list-tables --schema dbo # Output as JSON gcx datasources mssql list-tables -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.mssql is configured) -h, --help help for list-tables --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --schema string Filter tables to this schema (e.g. dbo) ``` Inherits `--config` from [`gcx datasources mssql`](#gcx-datasources-mssql-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources mssql query` Execute a SQL query against a Microsoft SQL Server datasource. EXPR is the SQL query to execute, passed as a positional argument or via –expr. Datasource is resolved from -d flag or datasources.mssql in your context. Server-side macros ($\_\_timeFilter, $\_\_timeGroup, etc.) are supported. Use –step to set the interval the $\_\_interval / $\_\_timeGroup(col, $\_\_interval) macros resolve to (e.g. –step 1h buckets time-series results hourly). T-SQL has no LIMIT keyword. By default the result is capped with an injected TOP (n) clause (see –limit); use –limit 0 to disable it, or write your own TOP / OFFSET … FETCH. Injection only applies to simple leading-SELECT statements — CTEs (WITH), set operations (UNION/INTERSECT/EXCEPT), queries that already use TOP, and OFFSET/FETCH queries are left unchanged. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources mssql query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Simple query (capped at TOP (100)) gcx datasources mssql query 'SELECT name, id FROM dbo.WORLD_DATA' # With time macro and explicit datasource gcx datasources mssql query -d UID 'SELECT * FROM events WHERE $__timeFilter(created_at)' --since 1h # Time-series query bucketed hourly via --step (feeds $__interval) gcx datasources mssql query -d UID 'SELECT $__timeGroup(created_at, $__interval) AS t, COUNT(*) FROM events GROUP BY $__timeGroup(created_at, $__interval)' --since 24h --step 1h # Cap at 10 rows (injects TOP (10)) gcx datasources mssql query -d UID 'SELECT * FROM dbo.WORLD_DATA' --limit 10 # Disable TOP injection and output JSON gcx datasources mssql query 'SELECT * FROM dbo.WORLD_DATA' --limit 0 -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.mssql is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Max rows to return via injected TOP (n) (0 disables injection) (default 100) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources mssql`](#gcx-datasources-mssql-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources mysql` Query MySQL datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for mysql ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources mysql describe-table` Show the columns of a MySQL table: name, column type, nullability, and default. The table can be database-qualified (db.table); otherwise use –database to disambiguate when the same table name exists in multiple databases. TABLE and –database both match exactly and are case-sensitive, which can differ from how information\_schema itself compares names depending on the server’s platform and lower\_case\_table\_names setting. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources mysql describe-table TABLE [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Describe a table gcx datasources mysql describe-table orders -d UID # Disambiguate by database gcx datasources mysql describe-table mydb.orders gcx datasources mysql describe-table orders --database mydb # Output as JSON gcx datasources mysql describe-table orders -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --database string Database of the table (exact match, case-sensitive; defaults to all databases) -d, --datasource string Datasource UID (required unless datasources.mysql is configured) -h, --help help for describe-table --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx datasources mysql`](#gcx-datasources-mysql-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources mysql list-tables` List tables and views from all non-system databases, or filter to a specific database. Shows database, name, and type for each table. –database matches exactly and is case-sensitive. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources mysql list-tables [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all tables gcx datasources mysql list-tables -d UID # Filter to a specific database gcx datasources mysql list-tables --database mydb # Output as JSON gcx datasources mysql list-tables -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --database string Filter tables to this database (exact match, case-sensitive) -d, --datasource string Datasource UID (required unless datasources.mysql is configured) -h, --help help for list-tables --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx datasources mysql`](#gcx-datasources-mysql-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources mysql query` Execute a SQL query against a MySQL datasource. EXPR is the SQL query to execute, passed as a positional argument or via –expr. Datasource is resolved from -d flag or datasources.mysql in your context. Server-side macros ($\_\_timeFilter, $\_\_timeGroup, etc.) are supported. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources mysql query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Simple query gcx datasources mysql query 'SELECT count(*) FROM orders' # With time macro and explicit datasource gcx datasources mysql query -d UID 'SELECT * FROM events WHERE $__timeFilter(created_at)' --since 1h # Output as JSON gcx datasources mysql query -d UID 'SELECT 1' -o json # Disable limit enforcement gcx datasources mysql query 'SELECT * FROM big_table' --limit 0 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.mysql is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Max rows to return; requests above 1000 are capped, with a warning (0 disables enforcement) (default 100) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources mysql`](#gcx-datasources-mysql-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources opensearch` Query OpenSearch datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for opensearch ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources opensearch list-fields` List the mapped fields and their types, per index. Nested object fields are flattened with dotted names. Use these names in Lucene queries and –group-by. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources opensearch list-fields [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # All fields across indices gcx datasources opensearch list-fields # Fields of one index gcx datasources opensearch list-fields -d UID --index grafana-logs -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.opensearch is configured) -h, --help help for list-fields --index string Restrict to this index or index pattern --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources opensearch`](#gcx-datasources-opensearch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources opensearch list-indices` List the indices visible to an OpenSearch datasource, with their mapped field counts. Pass –index to restrict to one index or pattern; fetching the mapping for every index can hit the response size cap on a large cluster. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources opensearch list-indices [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources opensearch list-indices gcx datasources opensearch list-indices -d UID -o json # Restrict to one index or pattern gcx datasources opensearch list-indices -d UID --index grafana-logs ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.opensearch is configured) -h, --help help for list-indices --index string Restrict to this index or index pattern --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources opensearch`](#gcx-datasources-opensearch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources opensearch metrics` Run a metric aggregation bucketed by a time histogram, optionally split into series by a terms field. EXPR is a Lucene query string scoping the documents; omit it to aggregate all. Returns (time, value, series) rows. Use –step to control bucket size. Datasource is resolved from -d flag or datasources.opensearch in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources opensearch metrics [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Document count over time gcx datasources opensearch metrics --since 6h # Error count per app gcx datasources opensearch metrics 'level:error' --group-by app.keyword --since 6h # Average value of a numeric field gcx datasources opensearch metrics --agg avg --field duration_ms --since 1h -o json # Print a Grafana Explore share link for the executed query gcx datasources opensearch metrics 'level:error' --since 6h --share-link # Continue the same aggregation in Grafana Explore gcx datasources opensearch metrics 'level:error' --since 6h --open ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --agg string Metric aggregation: count, avg, sum, min, max, or cardinality (default "count") -d, --datasource string Datasource UID (required unless datasources.opensearch is configured) --expr string Query expression (alternative to positional argument) --field string Field to aggregate (required unless --agg count) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --group-by string Split series by this field's terms (use .keyword for text fields) --group-size int Max number of series when using --group-by (1-1000) (default 10) -h, --help help for metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --time-field string Time field for the date histogram bucket (defaults to the datasource's configured time field if omitted) --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources opensearch`](#gcx-datasources-opensearch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources opensearch query` Search documents in an OpenSearch datasource with a Lucene query. EXPR is a Lucene query string (e.g. ‘app:frontend AND level:error’); omit it to match all documents in the time range. The index pattern comes from the datasource configuration. –mode documents (default) returns raw source documents. –mode logs returns the same documents newest-first with plugin-internal fields (\_source, sort, highlight, \_type) omitted, matching how Grafana Explore’s Logs view reads them. Datasource is resolved from -d flag or datasources.opensearch in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources opensearch query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Match all documents in the last hour gcx datasources opensearch query --since 1h # Lucene query with explicit datasource gcx datasources opensearch query -d UID 'app:frontend AND level:error' --since 1h # Newest-first logs, plugin-internal fields omitted gcx datasources opensearch query -d UID 'level:error' --mode logs --since 6h --limit 50 # Output as JSON, limit results gcx datasources opensearch query -d UID 'datacenter:us-east' --limit 20 -o json # Print a Grafana Explore share link for the executed query gcx datasources opensearch query 'level:error' --since 1h --share-link # Continue the same search in Grafana Explore gcx datasources opensearch query 'level:error' --since 1h --open ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.opensearch is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Max documents to return (1-1000) (default 100) --mode string Search mode: "documents" (raw documents) or "logs" (newest-first, plugin-internal fields omitted) (default "documents") --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources opensearch`](#gcx-datasources-opensearch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pinot` Query StarTree Pinot datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for pinot ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pinot query` Execute a PinotQL query against a StarTree Pinot datasource. EXPR is the SQL query to execute, passed as a positional argument or via –expr. Datasource is resolved from -d flag or datasources.pinot in your context. Server-side macros ($\_\_timeFilter, $\_\_timeGroup, etc.) are supported. Table name (StarTree tableName field): - StarTree requires tableName to load schema and expand macros before it runs pinotQlCode (sent alongside your SQL in the query request). - By default, gcx derives tableName from the first real FROM in the SQL. - Derivation supports schema.table, double-quoted identifiers, and the inner table in FROM (subquery) … (for example SELECT … FROM (SELECT … FROM events)). - Ignored for derivation: FROM inside string literals, line or block comments, or EXTRACT/TRIM/SUBSTRING/OVERLAY calls (they are not table clauses). - When the SQL has no extractable table (for example SELECT 1), pass –table with a table the query actually uses; the command fails otherwise. - –table overrides any name that would be derived from the SQL. Row limit (–limit): - Default 100 when –limit is omitted on this command and the expression does not have a LIMIT; generic gcx datasources query uses the same Pinot default when the datasource kind is pinot. - –limit 0 disables enforcement (SQL is sent unchanged) and prints no notice. - Requests above 1000 are capped to 1000 in the emitted LIMIT when the SQL can be rewritten. –limit never overwrites an existing LIMIT n that is already at or below 1000. - Only SELECT/WITH-shaped PinotQL may be rewritten; optional leading SET …; prefixes are ignored for this check. - Left unchanged (no append): UNION, OFFSET, LIMIT offset,count, OPTION(…), trailing line comments, LIMIT before a trailing comment, unclosed block comments; keywords only in string literals or comments do not trigger these. - A LIMIT inside a comment (LIMIT /* note \*/ n) still counts as an existing LIMIT. The number is read after comments are blanked but the SQL is not rewritten because it is not safe to modify. Stderr notices (one line, never the full SQL): When –limit N is set: | Query | Sent | Notice | |——————————-|—————–|——–| | no LIMIT, safe | append LIMIT N | Query adjusted: appended LIMIT N (–limit). Use –limit 0 to disable enforcement. | | no LIMIT, not safe | unchanged | You asked for –limit N, but a row limit was not appended (this query shape is not safe to modify). Add LIMIT in the SQL or use –limit 0. | | has LIMIT, n == N | unchanged | (none) | | has LIMIT, n != N, n <= 1000 | unchanged | You requested –limit N but the query already has a LIMIT, so no change was applied. | | bare LIMIT n, n > 1000 | LIMIT 1000 | You requested –limit N but the existing LIMIT was above the maximum, so it was reduced to 1000. | | LIMIT /* … \*/ n, n > 1000 | unchanged | The query has a LIMIT above 1000 that should be reduced to 1000, but the query is not safe to modify. | When –limit is omitted (default 100): | Query | Sent | Notice | |——————————-|—————–|——–| | no LIMIT, safe | append LIMIT 100 | Query adjusted: appended default LIMIT 100. Use –limit 0 to disable enforcement. | | no LIMIT, not safe | unchanged | (none) | | has LIMIT, n <= 1000 | unchanged | (none) | | bare LIMIT n, n > 1000 | LIMIT 1000 | Query adjusted: LIMIT reduced to 1000 (maximum). Use –limit 0 to disable enforcement. | | LIMIT /* … \*/ n, n > 1000 | unchanged | The query has a LIMIT above 1000 that should be reduced to 1000, but the query is not safe to modify. | Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pinot query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Simple query gcx datasources pinot query -d UID 'SELECT count(*) FROM events' # With time range gcx datasources pinot query -d UID --since 7d \ 'SELECT count(*) FROM events WHERE $__timeFilter("timestamp")' # Output as JSON gcx datasources pinot query -d UID 'SELECT 1 FROM events' -o json # Print a Grafana Explore share link for the executed query gcx datasources pinot query -d UID 'SELECT 1 FROM events' --share-link # Disable limit enforcement gcx datasources pinot query -d UID 'SELECT * FROM events' --limit 0 # SQL with no extractable table gcx datasources pinot query -d UID --table events 'SELECT 1' ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pinot is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Max rows to return; requests above 1000 are capped (stderr notice when the query is adjusted). 0 disables enforcement (default 100) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --table string StarTree table name when the SQL has no extractable FROM (required in that case) --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources pinot`](#gcx-datasources-pinot-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources postgres` Query PostgreSQL datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for postgres ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources postgres describe-table` Show the columns of a PostgreSQL table: name, data type, nullability, and default. The table can be schema-qualified (schema.table); otherwise use –schema to disambiguate when the same table name exists in multiple schemas. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources postgres describe-table TABLE [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Describe a table gcx datasources postgres describe-table orders -d UID # Disambiguate by schema gcx datasources postgres describe-table public.orders gcx datasources postgres describe-table orders --schema public # Output as JSON gcx datasources postgres describe-table orders -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.postgres is configured) -h, --help help for describe-table --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --schema string Schema of the table (exact match, case-sensitive; defaults to all schemas) ``` Inherits `--config` from [`gcx datasources postgres`](#gcx-datasources-postgres-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources postgres list-tables` List tables and views from all non-system schemas, or filter to a specific schema. Shows schema, name, and type for each table. –schema matches exactly and is case-sensitive. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources postgres list-tables [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all tables gcx datasources postgres list-tables -d UID # Filter to a specific schema gcx datasources postgres list-tables --schema public # Output as JSON gcx datasources postgres list-tables -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.postgres is configured) -h, --help help for list-tables --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --schema string Filter tables to this schema (exact match, case-sensitive) ``` Inherits `--config` from [`gcx datasources postgres`](#gcx-datasources-postgres-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources postgres query` Execute a SQL query against a PostgreSQL datasource. EXPR is the SQL query to execute, passed as a positional argument or via –expr. Datasource is resolved from -d flag or datasources.postgres in your context. Server-side macros ($\_\_timeFilter, $\_\_timeGroup, etc.) are supported. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources postgres query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Simple query gcx datasources postgres query 'SELECT count(*) FROM orders' # With time macro and explicit datasource gcx datasources postgres query -d UID 'SELECT * FROM events WHERE $__timeFilter(created_at)' --since 1h # Output as JSON gcx datasources postgres query -d UID 'SELECT 1' -o json # Disable limit enforcement gcx datasources postgres query 'SELECT * FROM big_table' --limit 0 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.postgres is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Max rows to return; requests above 1000 are capped, with a warning (0 disables enforcement) (default 100) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources postgres`](#gcx-datasources-postgres-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources prometheus` Query Prometheus datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for prometheus ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources prometheus labels` List all labels or get values for a specific label from a Prometheus datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources prometheus labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all labels (use datasource UID, not name) gcx datasources prometheus labels -d UID # Get values for a specific label gcx datasources prometheus labels -d UID --label job # List labels present on a metric gcx datasources prometheus labels -d UID --metric http_requests_total # Get values a label takes on a metric gcx datasources prometheus labels -d UID --metric http_requests_total --label job # Scope with an arbitrary series selector gcx datasources prometheus labels -d UID --match '{job="api"}' # Output as JSON gcx datasources prometheus labels -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label string Get values for this label (omit to list all labels) --match stringArray Series selector(s) to scope results; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) --metric string Only results from series of this metric (narrows every --match selector) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources prometheus`](#gcx-datasources-prometheus-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources prometheus metadata` Get metadata (type, help text) for metrics from a Prometheus datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources prometheus metadata [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Get all metric metadata (use datasource UID, not name) gcx datasources prometheus metadata -d UID # Get metadata for a specific metric gcx datasources prometheus metadata -d UID --metric http_requests_total # Output as JSON gcx datasources prometheus metadata -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) -h, --help help for metadata --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -m, --metric string Filter by metric name -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources prometheus`](#gcx-datasources-prometheus-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources prometheus query` Execute a PromQL query against a Prometheus datasource. EXPR is the PromQL expression to evaluate, passed as a positional argument or via –expr (familiar to promtool users). Datasource is resolved from -d flag or datasources.prometheus in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources prometheus query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Instant query using configured default datasource gcx datasources prometheus query 'up{job="grafana"}' # Instant query at a specific time gcx datasources prometheus query 'rate(http_requests_total[5m])' --time 2026-01-15T10:30:00Z # Range query with explicit datasource UID gcx datasources prometheus query -d UID 'rate(http_requests_total[5m])' --from now-1h --to now --step 1m # Query the last hour gcx datasources prometheus query 'up' --since 1h # Print a Grafana Explore share link for the executed query gcx datasources prometheus query 'up' --share-link # Output as JSON gcx datasources prometheus query -d UID 'up' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --time string Evaluation time for an instant query (RFC3339, Unix timestamp, or relative like 'now-5m'). Mutually exclusive with --from/--to/--since --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources prometheus`](#gcx-datasources-prometheus-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources prometheus search-label-names` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Search label names from a Prometheus/Mimir datasource. Requires TERM (performs a fuzzy search; multiple TERM values combine as OR), or a scope instead: –metric, –metric-regex or –match. sort\_by=score (the default) requires a search term — omitting TERM in favor of a scope falls back to sort\_by=alpha, and an explicit –sort-by=score without TERM is rejected. –metric-regex is used exactly as given — PromQL anchors =~ at ^…$, so “kube” matches only a metric literally named “kube”, not one containing it. Write “.*kube.*” for a contains search. Without –from/–to or –since, the server searches only the last hour; use –since (for example –since 7d) to look further back. This API is experimental and disabled by default on both self-hosted Prometheus (requires –enable-feature=search-api) and self-hosted Mimir (requires -querier.experimental-search-api-enabled). See also the sibling metric-name search and label-value search commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources prometheus search-label-names [TERM...] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Fuzzy search label names (use datasource UID, not name) gcx datasources prometheus search-label-names job -d UID # Show label names available on a given metric gcx datasources prometheus search-label-names -d UID --metric http_requests_total # Show label names on series matching a selector gcx datasources prometheus search-label-names -d UID --match '{job="api"}' # Search for label names on a given metric gcx datasources prometheus search-label-names namespace -d UID --metric http_requests_total # Search for label names across a range of metrics gcx datasources prometheus search-label-names namespace -d UID --metric-regex '.*kube.*' # Search label names seen in the last 7 days (default: the last hour) gcx datasources prometheus search-label-names job -d UID --since 7d # Output as JSON gcx datasources prometheus search-label-names job -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --case-sensitive Case-sensitive search term matching (case-insensitive by default) -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --fuzz-alg string Fuzzy match algorithm: jarowinkler or subsequence (default "jarowinkler") --fuzz-threshold int Minimum fuzzy match score as a percentage, 0-100; scores are reported from 0 to 1. With jarowinkler the threshold applies only to fuzzy matches: substring matches are always kept, and 0 turns fuzzy matching off (default 70) -h, --help help for search-label-names --include-score Include each result's relevance score (0 to 1; higher is a closer match) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum results to return (0: unlimited on Mimir, subject to server-side caps; Prometheus requires a positive value) (default 50) --match stringArray PromQL series selector(s) restricting candidates; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) --metric string Only results from series of this metric name; mutually exclusive with --metric-regex --metric-regex string Only results from series whose metric name matches this regex. Used exactly as given. To match all metric names which contain "kube" use ".*kube.*". Mutually exclusive with --metric. -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --sort-by string Sort by: score (requires a search term) or alpha (default "score") --sort-dir string Sort direction for --sort-by alpha: asc (default) or dsc --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources prometheus`](#gcx-datasources-prometheus-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources prometheus search-label-values` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Search the values of a single label from a Prometheus/Mimir datasource. LABEL is always required; TERM (multiple values combine as OR), –metric, –metric-regex and –match are all optional and may be combined or omitted — LABEL alone lists that label’s values. sort\_by=score (the default) requires a search term — omitting TERM falls back to sort\_by=alpha, and an explicit –sort-by=score without TERM is rejected. –metric-regex is used exactly as given — PromQL anchors =~ at ^…$, so “kube” matches only a metric literally named “kube”, not one containing it. Write “.*kube.*” for a contains search. Without –from/–to or –since, the server searches only the last hour; use –since (for example –since 7d) to look further back. This API is experimental and disabled by default on both self-hosted Prometheus (requires –enable-feature=search-api) and self-hosted Mimir (requires -querier.experimental-search-api-enabled). See also the sibling metric-name search and label-name search commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources prometheus search-label-values LABEL [TERM...] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List values of the "job" label (use datasource UID, not name) gcx datasources prometheus search-label-values job -d UID # Fuzzy search values of the "job" label gcx datasources prometheus search-label-values job pro -d UID # List "job" label values present on a specific metric gcx datasources prometheus search-label-values job -d UID --metric http_requests_total # List "job" label values present on a range of metrics gcx datasources prometheus search-label-values job -d UID --metric-regex '.*kube.*' # List "job" label values seen in the last 7 days (default: the last hour) gcx datasources prometheus search-label-values job -d UID --since 7d # Output as JSON gcx datasources prometheus search-label-values job pro -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --case-sensitive Case-sensitive search term matching (case-insensitive by default) -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --fuzz-alg string Fuzzy match algorithm: jarowinkler or subsequence (default "jarowinkler") --fuzz-threshold int Minimum fuzzy match score as a percentage, 0-100; scores are reported from 0 to 1. With jarowinkler the threshold applies only to fuzzy matches: substring matches are always kept, and 0 turns fuzzy matching off (default 70) -h, --help help for search-label-values --include-score Include each result's relevance score (0 to 1; higher is a closer match) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum results to return (0: unlimited on Mimir, subject to server-side caps; Prometheus requires a positive value) (default 50) --match stringArray PromQL series selector(s) restricting candidates; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) --metric string Only results from series of this metric name; mutually exclusive with --metric-regex --metric-regex string Only results from series whose metric name matches this regex. Used exactly as given. To match all metric names which contain "kube" use ".*kube.*". Mutually exclusive with --metric. -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --sort-by string Sort by: score (requires a search term) or alpha (default "score") --sort-dir string Sort direction for --sort-by alpha: asc (default) or dsc --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources prometheus`](#gcx-datasources-prometheus-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources prometheus search-metric-names` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Search metric names from a Prometheus/Mimir datasource. At least one TERM is required. This API allows for metric names to be discovered via a configurable fuzzy search. Multiple TERM values combine as OR. Search terms can be augmented with matchers for additional filtering of considered series. Without –from/–to or –since, the server searches only the last hour; use –since (for example –since 7d) to look further back. This API is experimental and disabled by default on both self-hosted Prometheus (requires –enable-feature=search-api) and self-hosted Mimir (requires -querier.experimental-search-api-enabled). See also the sibling label-name search and label-value search commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources prometheus search-metric-names TERM... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Fuzzy search metric names (use datasource UID, not name) gcx datasources prometheus search-metric-names http -d UID # Search metric names seen in the last 7 days (default: the last hour) gcx datasources prometheus search-metric-names http -d UID --since 7d # Refine fuzzy search algorithm gcx datasources prometheus search-metric-names http -d UID --fuzz-alg=subsequence --fuzz-threshold=85 # Limit result sets and control ordering gcx datasources prometheus search-metric-names http -d UID --limit=10 --sort-by=alpha # Include relevance score and metric metadata gcx datasources prometheus search-metric-names http -d UID --include-score --include-metadata # Output as JSON gcx datasources prometheus search-metric-names http -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --case-sensitive Case-sensitive search term matching (case-insensitive by default) -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --fuzz-alg string Fuzzy match algorithm: jarowinkler or subsequence (default "jarowinkler") --fuzz-threshold int Minimum fuzzy match score as a percentage, 0-100; scores are reported from 0 to 1. With jarowinkler the threshold applies only to fuzzy matches: substring matches are always kept, and 0 turns fuzzy matching off (default 70) -h, --help help for search-metric-names --include-metadata Include each result's metric type, help text, and unit (when available) --include-score Include each result's relevance score (0 to 1; higher is a closer match) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum results to return (0: unlimited on Mimir, subject to server-side caps; Prometheus requires a positive value) (default 50) --match stringArray PromQL series selector(s) restricting candidates; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --sort-by string Sort by: score (requires a search term) or alpha (default "score") --sort-dir string Sort direction for --sort-by alpha: asc (default) or dsc --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources prometheus`](#gcx-datasources-prometheus-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope` Query Pyroscope datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for pyroscope ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope data-range` Show the range of profiling data a Pyroscope datasource holds: whether any data was ever ingested, and the oldest and newest profile times. The range covers everything behind the datasource (the whole tenant), not any particular service or label selector. Use this to disambiguate empty query results: if no data was ever ingested, fix ingestion before adjusting selectors; otherwise the oldest/newest bounds show the currently queryable window. Note that data-ingested is a lifetime flag: it stays true even after all data has aged out of the retention period (31 days by default, tenant-configurable), in which case the bounds render as ‘-’ (0 in JSON). Older backends may also report an unknown oldest bound the same way. If gcx auto-discovers the datasource from your Grafana Cloud stack, the discovered datasource UID may be saved to your gcx configuration for future commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pyroscope data-range [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Check whether the datasource holds profiling data, and for what range gcx datasources pyroscope data-range -d UID # Output as JSON (times are milliseconds since epoch) gcx datasources pyroscope data-range -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) -h, --help help for data-range --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope exemplars` Query profile or span exemplars from a Pyroscope datasource. Exemplars link profile data to concrete samples or trace spans, enabling a pivot from “which service was slow” to “which exact profile” (profile exemplars) or “which trace span” (span exemplars). **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for exemplars ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope exemplars profile` List individual profile exemplars by calling SelectSeries with EXEMPLAR\_TYPE\_INDIVIDUAL. Each row is a concrete profile sample identified by Profile ID. When profiles are span-aware (e.g. via otelpyroscope), a Span ID column is included linking to the associated trace span. EXPR is the label selector (e.g. ‘{service\_name=“frontend”}’). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pyroscope exemplars profile [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Top profile exemplars in the last hour gcx datasources pyroscope exemplars profile '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # JSON output gcx datasources pyroscope exemplars profile '{}' --since 30m -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --expr string Label selector (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for profile --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-label-columns int Max label columns in table output (0 hides label columns) (default 3) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --profile-type string Profile type ID (default "process_cpu:cpu:nanoseconds:cpu:nanoseconds") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') --top-n int Maximum number of exemplars to return (default 100) ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope exemplars span` List span exemplars by calling SelectHeatmap with HEATMAP\_QUERY\_TYPE\_SPAN. Each row is a span-linked profile sample identified by Span ID. When supplied by the server, Trace ID is also included for direct correlation with Tempo. Requires span-aware instrumentation upstream (e.g. otelpyroscope); without it the query returns an empty list. EXPR is the label selector (e.g. ‘{service\_name=“frontend”}’). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pyroscope exemplars span [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Top span exemplars in the last hour gcx datasources pyroscope exemplars span '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # JSON output, more label context gcx datasources pyroscope exemplars span '{}' --since 30m --max-label-columns 5 -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --expr string Label selector (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for span --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-label-columns int Max label columns in table output (0 hides label columns) (default 3) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --profile-type string Profile type ID (default "process_cpu:cpu:nanoseconds:cpu:nanoseconds") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') --top-n int Maximum number of exemplars to return (default 100) ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope labels` List all labels or get values for a specific label from a Pyroscope datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pyroscope labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all labels (use datasource UID, not name) gcx datasources pyroscope labels -d UID # Get values for a specific label gcx datasources pyroscope labels -d UID --label service_name # Search a wider window than the default last hour gcx datasources pyroscope labels -d UID --since 24h # Output as JSON gcx datasources pyroscope labels -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label string Get values for this label (omit to list all labels) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope list-profile-types` List available profile types from a Pyroscope datasource. If gcx auto-discovers the datasource from your Grafana Cloud stack, the discovered datasource UID may be saved to your gcx configuration for future commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pyroscope list-profile-types [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List profile types (use datasource UID, not name) gcx datasources pyroscope list-profile-types -d UID # Search a wider window than the default last hour gcx datasources pyroscope list-profile-types -d UID --since 24h # Output as JSON gcx datasources pyroscope list-profile-types -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for list-profile-types --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope metrics` Query profile time-series data via SelectSeries from a Pyroscope datasource. Shows how a profile metric (e.g., CPU, memory) changes over time. Useful for identifying performance regressions and trends before diving into flamegraphs. Use –top to aggregate the time range into a ranked leaderboard of the heaviest consumers (equivalent to profilecli query top). Without –top, returns raw time-series data points for trend analysis. EXPR is the label selector (e.g., ‘{service\_name=“frontend”}’). Datasource is resolved from -d flag or datasources.pyroscope in your context. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pyroscope metrics [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Top services by CPU usage (ranked leaderboard) gcx datasources pyroscope metrics '{}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds \ --since 1h --top # Top 20 services by memory, grouped by namespace gcx datasources pyroscope metrics '{}' \ --profile-type memory:inuse_space:bytes:space:bytes \ --since 1h --top --group-by namespace --limit 20 # CPU usage over the last hour with 1-minute resolution gcx datasources pyroscope metrics -d pyro-001 '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds \ --since 1h --step 1m # Line chart output gcx datasources pyroscope metrics '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds \ --since 1h --step 1m -o graph ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --aggregation string Aggregation type: 'sum' or 'average' -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --group-by strings Group series by label (repeatable, defaults to service_name) -h, --help help for metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of series to return (default 10) -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --profile-type string Profile type ID (e.g., 'process_cpu:cpu:nanoseconds:cpu:nanoseconds') (required) --since string Duration before --to (or now if omitted); mutually exclusive with --from --step string Query step (e.g., '15s', '1m'); defaults to the Pyroscope datasource minStep (or 15s) when omitted --to string End time (RFC3339, Unix timestamp, or relative like 'now') --top Aggregate into a ranked leaderboard (equivalent to profilecli query top) ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope query` Execute a profiling query against a Pyroscope datasource. EXPR is the label selector (e.g., ‘{service\_name=“frontend”}’). Datasource is resolved from -d flag or datasources.pyroscope in your context. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pyroscope query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Profile query with explicit datasource UID gcx datasources pyroscope query -d UID '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # Using configured default datasource gcx datasources pyroscope query '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # Output as JSON gcx datasources pyroscope query -d UID '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds -o json # Drill into one or more specific profiles found via exemplars # (--profile-id is repeatable; pass it once per UUID) gcx datasources pyroscope query '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h \ --profile-id 550e8400-e29b-41d4-a716-446655440000 \ --profile-id 7c9e6679-7425-40de-944b-e07fc1f90ae7 # Restrict the query to one or more trace spans gcx datasources pyroscope query '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h \ --span-id 00f067aa0ba902b7 # Restrict the query to samples from one or more traces gcx datasources pyroscope query '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h \ --trace-id 4bf92f3577b34da6a3ce929d0e0e4736 # Restrict the flamegraph to stacks rooted at a specific call site # (--stacktrace-selector is repeatable; pass it once per frame, root first) gcx datasources pyroscope query '{service_name="my-go-service"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h \ --stacktrace-selector 'github.com/prometheus/client_golang/prometheus.(*Registry).Gather.func1' # Download as pprof binary (for use with go tool pprof) gcx datasources pyroscope query -d UID '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds -o pprof # Download as pprof binary to a specific path gcx datasources pyroscope query -d UID '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds -o pprof --pprof-path ./cpu.pb.gz # Caller-callee call graph as Graphviz DOT text (function names, file:line, # self/cumulative values) — the most readable format for LLM analysis. # Requires a pure-v2 backend (-architecture.storage=v2); other backends # fall back to the table. Dotted edges mean intermediate frames were # elided by the 100-node default — raise --max-nodes for fuller chains. gcx datasources pyroscope query -d UID '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds -o dot --max-nodes 250 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-nodes int Maximum nodes in the result (defaults: pprof 0/unlimited, dot 100-node call graph rendered server-side, 50000 for all other formats) -o, --output string Output format. One of: agents, dot, graph, json, pprof, table, wide, yaml (default "table") --pprof-overwrite Overwrite the output file if it already exists (only with -o pprof) --pprof-path string Destination path for pprof binary output (only with -o pprof; default: profile-YYYY-MM-DD-HHMMSS.pb.gz) --profile-id strings Drill down to specific profile UUIDs from exemplar queries (repeatable) --profile-type string Profile type ID (e.g., 'process_cpu:cpu:nanoseconds:cpu:nanoseconds'); use 'gcx profiles list-profile-types' to list available (required) --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --span-id strings Only query profiles with these 16-character hex span IDs (repeatable; unavailable with -o pprof and -o dot) --stacktrace-selector strings Only query locations with these function names, starting from the root (repeatable) --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') --trace-id strings Only query samples with these 32-character hex trace IDs (repeatable) ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope query-anomalies` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Query profiles flagged as anomalies by an external anomaly source and confirmed present in ingested data for the given label selector and time range. Requires the datasource’s query-frontend to have an anomaly source configured (query-frontend.anomaly-api.url); returns FAILED\_PRECONDITION otherwise. EXPR is the label selector (e.g. ‘{service\_name=“frontend”}’). It may resolve to more than one service\_name; anomalies from every matching service are queried and confirmed in one call. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pyroscope query-anomalies [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Anomalies for a service in the last hour gcx datasources pyroscope query-anomalies -d UID '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # Every service in a namespace gcx datasources pyroscope query-anomalies -d UID '{namespace="prod"}' --since 1h # JSON output gcx datasources pyroscope query-anomalies -d UID '{service_name="frontend"}' --since 1h -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --anomaly-type strings Anomaly source(s) to query. Only 'stacktrace' is supported today. Repeatable (default [stacktrace]) -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --expr string Label selector (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query-anomalies --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-label-columns int Max label columns in table output (0 hides label columns) (default 3) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --profile-type string Profile type ID (default "process_cpu:cpu:nanoseconds:cpu:nanoseconds") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') --top-n int Maximum number of anomalies to return (default 100) ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope series` List unique profile label sets from a Pyroscope datasource. The command uses Pyroscope’s Series endpoint and does not require a profile type. SELECTOR is optional; use –match for repeatable selectors. Multiple selectors are combined as a union. By default, the response includes every label. Use –label-name to request only the labels needed for discovery. This reduces the response size and can significantly speed up queries with high-cardinality labels. For example, use –label-name service\_name –label-name namespace to discover services and namespaces without fetching pod, instance, or custom labels. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pyroscope series [SELECTOR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List service and workload combinations from the last hour gcx datasources pyroscope series -d UID --since 1h # Faster discovery: request only the labels needed gcx datasources pyroscope series -d UID '{service_name="checkout"}' \ --label-name service_name --label-name namespace --label-name pod --since 7d # Use multiple selectors and JSON output gcx datasources pyroscope series -d UID \ --match '{namespace="payments"}' --match '{namespace="checkout"}' \ --since 24h -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for series --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --label-name strings Label name to return (repeatable; limit labels to reduce response size and speed up discovery) --match stringArray Profile label selector (repeatable; selectors are combined as a union) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources query` Execute a query against any datasource, automatically detecting the datasource type. DATASOURCE\_UID is always required (no default resolution for generic). EXPR is the query expression appropriate for the datasource type. The datasource type is detected via the Grafana API and the appropriate query client is used automatically. This is the escape hatch for datasource types that do not have a dedicated subcommand. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources query DATASOURCE_UID [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Auto-detect and query any supported datasource gcx datasources query ds-001 'up{job="grafana"}' --from now-1h --to now # Loki via auto-detect (with limit) gcx datasources query loki-001 '{job="varlogs"}' --from now-1h --to now --limit 200 # Pyroscope via auto-detect gcx datasources query pyro-001 '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --from now-1h --to now ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum log lines for loki, or max rows for pinot (0 means no limit). Pinot uses 100 when --limit is omitted; stderr notes when PinotQL is adjusted (default 50) --max-nodes int Maximum nodes in flame graph (pyroscope only) (default 1024) -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --profile-type string Profile type ID for pyroscope queries (e.g., 'process_cpu:cpu:nanoseconds:cpu:nanoseconds') --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --table string StarTree table name for pinot queries when the SQL has no extractable FROM --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources schemas` Inspect the configuration schema of a datasource plugin type, to author manifests correctly. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for schemas ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources schemas get` Get the configuration schema for a datasource plugin type. The schema lists the configuration fields available for a plugin, derived from the server’s OpenAPI document. Use it to author create/update manifests. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources schemas get [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Show a plugin's configuration schema gcx datasources schemas get --type grafana-sentry-datasource # As JSON gcx datasources schemas get --type grafana-sentry-datasource -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --kind string Schema kind: config (query is not yet supported) (default "config") -o, --output string Output format. One of: agents, json, yaml (default "yaml") -t, --type string Datasource plugin id (e.g. grafana-sentry-datasource) ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources schemas list` List the datasource plugin types installed on the Grafana instance. The TYPE column is the plugin id — pass it to ‘schemas get –type’, and use it as spec.type when authoring a datasource manifest. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources schemas list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List available datasource plugin types gcx datasources schemas list # As JSON gcx datasources schemas list -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources tempo` Query Tempo datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for tempo ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources tempo baseline` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Find unranked candidates when you have a seed trace (TRACE\_ID) but need a useful comparison; if you already have both trace IDs, use ‘gcx traces diff’ directly. Retrieval fetches the seed, matches its root service/operation, requires root status != error (including unset), retains downstream errors, and pins up to three busiest downstream services; these heuristics do not prove health or comparable work. Apply verified environment, tenant, or operation constraints with –filter from the first request, then fetch a small batch of plausible candidates with ‘gcx traces get –llm’ when their summaries lack enough context. Use candidate bodies and exploratory diffs to accept or reject controls for the actual symptom, rather than requiring exact workload filters before the first diff or treating the first result as healthy. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources tempo baseline TRACE_ID [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Find a small shortlist; COHORT is an already-verified TraceQL spanset gcx traces baseline --context prod -d UID --filter "$COHORT" --limit 5 # With no additional known scope, use the seed-derived defaults gcx traces baseline --context prod -d UID --limit 5 # Inspect selected candidates; repeat for a small batch, not every result gcx traces get --context prod -d UID --llm -o agents # Assess a candidate with an exploratory diff (seed minus candidate) gcx traces diff --context prod -d UID # Set the candidate window; this does not bound the seed trace lookup gcx traces baseline --context prod -d UID --filter "$COHORT" --limit 5 \ --from 2026-01-15T08:00:00Z --to 2026-01-15T09:00:00Z ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --filter stringArray Raw TraceQL spanset expression to constrain candidates (repeatable; ANDed server-side with the generated query) --from string Absolute start time override (RFC3339, Unix timestamp, or relative like 'now-1h'); requires --to -h, --help help for baseline --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of candidates to return; must be at least 1 (default 20) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --to string Absolute end time override (RFC3339, Unix timestamp, or relative like 'now'); requires --from --window string Search window padding applied before and after the seed trace's time range, so candidates from before or after the seed are eligible (e.g., 30m, 6h, 7d). Ignored when --from/--to are set (default "30m") ``` Inherits `--config` from [`gcx datasources tempo`](#gcx-datasources-tempo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources tempo diff` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Compare two known trace IDs using the Grafana Cloud-only trace-diff API; use ‘gcx traces baseline’ first only when you need candidate IDs. TRACE\_A is the prospective baseline and TRACE\_B is the comparison, with deltas B - A: positive duration means B is slower and negative means faster, not automatically a regression or improvement (a request can fail early). Use candidate bodies and exploratory diffs to assess comparability, rejecting obvious context mismatches first and interpreting timing at the affected request boundary; a diff localizes execution changes but does not establish their cause. Keep the same context/datasource and make –from/–to (or –since) cover both executions; without time bounds the lookup uses the full lookback, and if the endpoint is unavailable, use ‘gcx traces get –llm’ to compare both bodies manually instead. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources tempo diff TRACE_A TRACE_B [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Compare an already-known pair directly; baseline search is not required gcx traces diff --context prod -d UID # Inspect a plausible candidate before using a diff to assess it gcx traces get --context prod -d UID --llm -o agents # Assess selected candidates against the seed; repeat only as useful gcx traces diff --context prod -d UID # Bound BOTH trace lookups, including an older candidate, and allow spilling gcx traces diff --context prod -d UID \ --from 2026-01-15T08:00:00Z --to 2026-01-15T10:00:00Z -o agents ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for diff --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources tempo`](#gcx-datasources-tempo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources tempo get` Retrieve a single trace by its trace ID from a Tempo datasource. TRACE\_ID is the hex-encoded trace identifier to retrieve. Datasource is resolved from -d flag or datasources.tempo in your context. Pass –since or –from/–to (e.g. the search’s time range) to make the lookup much faster. Omit them when the time range is unknown; a range that misses the trace returns not found. Use –share-link to print a Grafana Explore URL for the trace, or –open to open it in your browser after retrieval succeeds. Share links require an explicit time range via –since or –from/–to. Experimental: –llm requests the trace in a new LLM-friendly JSON format by sending the “Accept: application/vnd.grafana.llm” header. Datasources that do not support this format return the standard response. Experimental: for large traces, –filter narrows the response to spans matching a TraceQL spanset filter (V2 only). –keep-hierarchy, –match-depth, and –ancestor-depth shape how much context around each match is kept, and are ignored without –filter. Experimental: –prune collapses repeated sibling spans (for example, a fan-out of identical DB calls) into a single aggregated span. Off unless set. –prune-group-by, –prune-min-spans, and –prune-max-parent-depth tune the pruning behavior and apply only when –prune enables pruning. If the trace is too large for -o agents, the response is spilled to a file with a hint to read it directly or re-run narrower (e.g. with –filter or –prune). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources tempo get TRACE_ID [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Get LLM-friendly output for agent analysis gcx datasources tempo get abc123def456 --llm -o json # Get LLM-friendly output with explicit datasource UID gcx datasources tempo get -d tempo-001 abc123def456 --llm -o json # Print a Grafana Explore share link for the trace gcx datasources tempo get abc123def456 --share-link # Get a human-readable trace table gcx datasources tempo get abc123def456 # Get LLM-friendly output within a time range gcx datasources tempo get abc123def456 --since 1h --llm -o json # Narrow a large trace to error spans and their ancestor path gcx datasources tempo get abc123def456 --filter '{ status = error }' --keep-hierarchy # Collapse repeated sibling spans to shrink a huge trace before analysis gcx datasources tempo get abc123def456 --prune --llm -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --ancestor-depth int [experimental] Levels of ancestors to keep above each matched span: -1 = all (default), 0 = none, n = n levels (ignored without --filter or --keep-hierarchy) (default -1) -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --filter string [experimental] TraceQL spanset filter; only matching spans are returned (V2 only) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --keep-hierarchy [experimental] Include each matched span's ancestor path to the root (ignored without --filter) --llm [experimental] Request LLM-friendly trace format by sending the 'Accept: application/vnd.grafana.llm' header. Falls back to default JSON --match-depth int [experimental] Levels of descendants to keep below each matched span: -1 = all, 0 = matched spans only, n = n levels (ignored without --filter) --open Open the retrieved trace in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --prune [experimental] Collapse repeated sibling spans (e.g. a fan-out of identical DB calls) into a single aggregated span to shrink large traces. Off unless set --prune-group-by string [experimental] Comma-separated attribute glob patterns siblings must match to be grouped for pruning, e.g. 'db.*,http.method'. Applies only when --prune enables pruning --prune-max-parent-depth int [experimental] Ancestor levels above pruned leaves that may also be pruned; Tempo defaults to 1. Applies only when --prune enables pruning --prune-min-spans int [experimental] Minimum sibling span count required before a group is pruned; Tempo defaults to 5. Applies only when --prune enables pruning --share-link Print the Grafana Explore URL for the retrieved trace to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources tempo`](#gcx-datasources-tempo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources tempo labels` List all trace labels or get values for a specific label from a Tempo datasource. When -l/–label is provided, returns values for that label. When -l is omitted, returns all label names. Datasource is resolved from -d flag or datasources.tempo in your context. Experimental: –llm requests label values in a new LLM-friendly JSON format by sending the “Accept: application/vnd.grafana.llm” header. Datasources that do not support this format return the standard response. **Aliases:** `tags` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources tempo labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all labels gcx datasources tempo labels -d UID # Get values for a specific label gcx datasources tempo labels -d UID -l service.name # Get LLM-friendly values for a specific label gcx datasources tempo labels -d UID -l service.name --llm -o json # Using the tags alias gcx datasources tempo tags -d UID -l service.name # Filter by scope gcx datasources tempo labels -d UID -l service.name --scope span # Filter with a TraceQL query gcx datasources tempo labels -d UID -q '{ span.http.status_code >= 500 }' # Output as JSON gcx datasources tempo labels -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label string Get values for this label (omit to list all labels) --llm [experimental] Request LLM-friendly label values format by sending the 'Accept: application/vnd.grafana.llm' header. Falls back to default JSON (requires --label) -o, --output string Output format. One of: agents, json, table, yaml (default "table") -q, --query string TraceQL query to filter labels --scope string Tag scope filter (resource, span, event, link, instrumentation) ``` Inherits `--config` from [`gcx datasources tempo`](#gcx-datasources-tempo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources tempo metrics` Execute a TraceQL metrics query against a Tempo datasource. TRACEQL is the TraceQL metrics expression to evaluate. Datasource is resolved from -d flag or datasources.tempo in your context. Metrics queries support arithmetic (+, -, \*, /) with other queries or numeric scalars on supported Tempo backends. Wrap each metrics subquery in parentheses. Instant vs range is deduced from time flags: no time flags = instant query, –since or –from/–to = range query. Use –instant to force an instant query even when a time range is provided. If no time flags are set, gcx queries the last hour by default. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources tempo metrics [TRACEQL] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Instant query over the last hour (default, no time flags) gcx datasources tempo metrics '{ } | rate()' # Instant query with explicit time range gcx datasources tempo metrics '{ } | rate()' --instant --since 1h # Range query with explicit bounds, step, and an Explore share link gcx datasources tempo metrics '{ } | rate()' --from now-1h --to now --step 30s --share-link # Error percentage among observed server spans (not unsampled traffic) gcx datasources tempo metrics '100 * ({ kind = server && status = error } | rate()) / ({ kind = server } | rate())' --since 1h -o json # Each service's share of observed server-span throughput gcx datasources tempo metrics '100 * ({ kind = server } | rate() by (resource.service.name)) / ({ kind = server } | rate())' --since 1h ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for metrics --instant Run an instant query over the selected time range instead of a range query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources tempo`](#gcx-datasources-tempo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources tempo query` Search for traces using a TraceQL query against a Tempo datasource. TRACEQL is the TraceQL expression to evaluate. Datasource is resolved from -d flag or datasources.tempo in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. Share links require an explicit time range via –since or –from/–to. **Aliases:** `search` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources tempo query [TRACEQL] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Search traces using configured default datasource gcx datasources tempo query '{ span.http.status_code >= 500 }' # Search with explicit datasource UID and time range gcx datasources tempo query -d UID '{ span.http.status_code >= 500 }' --since 1h # Print a Grafana Explore share link for the query gcx datasources tempo query '{ span.http.status_code >= 500 }' --share-link # With custom limit gcx datasources tempo query -d UID '{ span.http.status_code >= 500 }' --since 1h --limit 50 # Output as JSON gcx datasources tempo query -d UID '{ span.http.status_code >= 500 }' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of traces to return (0 means no limit) (default 20) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources tempo`](#gcx-datasources-tempo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources update` Update an existing datasource instance from a declarative manifest file. This is a full replace: fields omitted from the manifest are reset. The current resourceVersion is fetched and applied automatically (optimistic concurrency). Secret values are updated via the top-level secure block. update does not prompt; use –dry-run to preview the change. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources update UID [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Update a datasource from a YAML manifest gcx datasources update my-ds-uid -f sentry.yaml # Preview the change gcx datasources update my-ds-uid -f sentry.yaml --dry-run ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use --dry-run Preview the change without applying it -f, --filename string File containing the datasource manifest (use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") --secrets-file string File containing secret values to merge into the secure block ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dbo11y` Inspect Grafana Database Observability instances and query performance **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for dbo11y ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dbo11y instances` Inspect Database Observability instances discovered from telemetry **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for instances ``` Inherits `--config` from [`gcx dbo11y`](#gcx-dbo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dbo11y instances get` Show exporter health and a query-performance snapshot for one database instance. The argument is the instance’s service\_name (the identifier “gcx dbo11y instances list” reports as NAME). What’s available depends on the instance’s engine (from “gcx dbo11y instances list”): - Health (up/down) is engine-agnostic, from the standard Prometheus scrape target gauge. - Postgres additionally reports exporter self-scrape health, per-state connection counts, active wait events, and the longest running transaction, all from postgres\_exporter’s pg\_stat\_activity collector. - MySQL reports a single current-connections count (mysql\_global\_status\_threads\_connected); wait events and exporter self-scrape health have no confirmed live metric for MySQL and are omitted rather than guessed. - Top queries (both engines) are ranked by time share (seconds of database time spent per second) over –since (default 5m): pg\_stat\_statements for Postgres, mysqld\_exporter’s Performance Schema eventsstatements collector for MySQL. –filter only scopes the connections/query-performance queries — health and inventory metadata don’t carry a datname/schema label and are unaffected. When no telemetry is found for the instance, this command checks whether Database Observability has been activated for the stack and, if not, exits non-zero with a hint to activate it in Grafana Cloud instead of a generic “no telemetry” message. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dbo11y instances get [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Health, connections, and top queries for one instance (Postgres or MySQL) gcx dbo11y instances get quickpizza-db # Widen the query window and show more top queries gcx dbo11y instances get quickpizza-db --since 1h --top 20 # Scope connections/queries to a single database on a multi-database instance gcx dbo11y instances get quickpizza-db --filter datname=payments # JSON for scripting gcx dbo11y instances get quickpizza-db -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Prometheus datasource UID (defaults to datasources.prometheus in config or auto-discovery) --filter stringArray Scope the connections/query-performance queries to series matching a label matcher, e.g. --filter datname=payments for Postgres or --filter schema=payments for MySQL (repeatable). Does not affect health/inventory metrics, which don't carry that label -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --since string Rate window applied to pg_stat_statements (e.g. 1m, 5m, 1h) — PromQL duration syntax (default "5m") --top int Limit the number of top queries returned, ranked by time share (0 = unlimited) (default 10) ``` Inherits `--config` from [`gcx dbo11y`](#gcx-dbo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dbo11y instances list` List the database instances Grafana Cloud Database Observability has discovered. Discovery uses the database\_observability\_connection\_info inventory metric emitted by the database\_observability.postgres Alloy component (job “integrations/db-o11y”): one row per monitored database instance, with engine and cloud-provider metadata. Related: “gcx dbo11y instances get ” drills into one instance’s health, connections, wait events, and top queries by time share. When no instances are found, this command checks whether Database Observability has been activated for the stack and, if not, exits non-zero with a hint to activate it in Grafana Cloud instead of a generic empty result. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dbo11y instances list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all database instances in the current stack gcx dbo11y instances list # Filter to Postgres instances gcx dbo11y instances list --filter engine=postgres # Pin a datasource and output JSON gcx dbo11y instances list -d grafanacloud-prom -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Prometheus datasource UID (defaults to datasources.prometheus in config or auto-discovery) --filter stringArray Restrict to instances matching a label matcher, e.g. --filter engine=postgres (repeatable) -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Limit the number of instances returned (0 = unlimited) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx dbo11y`](#gcx-dbo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev` Tools for managing Grafana resources as code: scaffold new projects, import existing resources from Grafana, generate typed Go stubs for new resources, lint resources, and serve resources locally. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for dev ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev generate` Generate typed Go code stubs using grafana-foundation-sdk builder types. The resource type is inferred from the immediate parent directory name: dashboards/ → dashboard alerts/ → alertrule alertrules/ → alertrule The resource name is inferred from the filename (without .go extension). Use –type to override type inference when the directory name does not match. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dev generate [FILE_PATH]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Generate a dashboard stub gcx dev generate dashboards/my-service-overview.go # Generate an alert rule stub gcx dev generate alerts/high-cpu-usage.go # Generate multiple stubs at once gcx dev generate dashboards/a.go dashboards/b.go alerts/c.go # Override type inference with --type gcx dev generate internal/monitoring/cpu-alert.go --type alertrule ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for generate --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") -t, --type string Resource type to generate (dashboard, alertrule). Overrides directory-based inference. ``` Inherits `--config`, `--context` from [`gcx dev`](#gcx-dev-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev import` Import resources from a Grafana instance and convert them into Go files using the grafana-foundation-sdk builder pattern. Each imported resource is written as a function returning \*resource.ManifestBuilder. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dev import [RESOURCE_SELECTOR]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Import all dashboards into the default path (imported/): gcx dev import dashboards # Import a specific dashboard by name: gcx dev import dashboards/my-dashboard # Import multiple resource types: gcx dev import dashboards folders # Import into a custom directory: gcx dev import dashboards --path src/grafana ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use -h, --help help for import --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") -p, --path string Import path. (default "imported") ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev lint` Lint Grafana resources. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for lint ``` Inherits `--config`, `--context` from [`gcx dev`](#gcx-dev-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev lint list-rules` List all built-in and custom linter rules with their name, description, resource type, and category. Use –rules to include custom rules from a directory. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dev lint list-rules [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List built-in rules: gcx dev lint list-rules # List built-in and custom rules: gcx dev lint list-rules -r ./custom-rules ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-rules --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") -r, --rules stringArray Path to custom rules. ``` Inherits `--config`, `--context` from [`gcx dev`](#gcx-dev-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev lint new` Scaffold a new Rego-based linter rule with a starter template, test fixture, and expected output file. Creates files in the current directory or the path specified by –output. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dev lint new RESOURCE_TYPE NAME [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Creates a new dashboard linter rule in the current directory: gcx dev lint new dashboard test-linter # Creates a new dashboard linter rule in another directory: gcx dev lint new dashboard test-linter -o custom-rules ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -c, --category string Rule category (default "idiomatic") -h, --help help for new -o, --output string Output directory ``` Inherits `--config`, `--context` from [`gcx dev`](#gcx-dev-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev lint run` Lint Grafana resources against Rego-based rules. Checks dashboards and other resource types for best practices, naming conventions, and configuration issues. Use –rules to load custom rules alongside built-in ones. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dev lint run PATH... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Lint Grafana resources using builtin rules: gcx dev lint run ./resources # Lint specific files: gcx dev lint run ./resources/file.json ./resources/other.yaml # Display compact results: gcx dev lint run ./resources -o compact # Use custom rules: gcx dev lint run --rules ./custom-rules ./resources # Disable all rules for a resource type: gcx dev lint run --disable-resource dashboard ./resources # Disable all rules in a category: gcx dev lint run --disable-category idiomatic ./resources # Disable specific rules: gcx dev lint run --disable uneditable-dashboard --disable panel-title-description ./resources # Enable rules for specific resource types: gcx dev lint run --disable-all --enable-resource dashboard ./resources # Enable only some categories: gcx dev lint run --disable-all --enable-category idiomatic ./resources # Enable only specific rules: gcx dev lint run --disable-all --enable uneditable-dashboard ./resources ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --debug Enable debug mode --disable stringArray Disable a rule --disable-all Disable all rules --disable-category stringArray Disable all rules in a category --disable-resource stringArray Disable all rules for a resource type --enable stringArray Enable a rule --enable-all Enable all rules --enable-category stringArray Enable all rules in a category --enable-resource stringArray Enable all rules for a resource type -h, --help help for run --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-concurrent int Maximum number of concurrent operations (default 10) -o, --output string Output format. One of: agents, compact, json, pretty, yaml (default "pretty") -r, --rules stringArray Path to custom rules ``` Inherits `--config`, `--context` from [`gcx dev`](#gcx-dev-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev lint test` Run test suites for linter rules. Each rule directory should contain test fixtures and expected output files. Reports pass/fail for each test case. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dev lint test PATH... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Run all tests in a directory: gcx dev lint test ./internal/linter/bundle/gcx/ ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --bundle Enable bundle mode --coverage Report coverage --debug Enable debug mode -h, --help help for test --ignore strings File and directory names to ignore during loading (e.g., '.*' excludes hidden files) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, pretty, yaml (default "pretty") --run string Run only test cases matching the regular expression --timeout duration Set test timeout ``` Inherits `--config`, `--context` from [`gcx dev`](#gcx-dev-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev scaffold` Scaffold a new Go project pre-configured for managing Grafana resources as code. Generates a module with example dashboards, a deploy workflow, and gcx configuration. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dev scaffold [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Interactive scaffolding (prompts for project name and Go module path): gcx dev scaffold # Non-interactive with flags: gcx dev scaffold --project my-dashboards --go-module-path github.com/example/my-dashboards ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --go-module-path string Go module path. -h, --help help for scaffold -p, --project string Project name. ``` Inherits `--config`, `--context` from [`gcx dev`](#gcx-dev-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev serve` Serve Grafana resources locally. The server started by this command makes it easy to explore and review resources locally. While resources are loaded from disk, the server will use the Grafana instance described in the current context to access some data (example: to run queries when previewing dashboards). The local proxy supports token, Basic, and mTLS contexts. OAuth contexts fail before the server starts because this long-running process cannot yet persist rotated refresh-token generations safely; use a service-account token for local preview. Note on NFS/SMB and watch mode: fsnotify requires support from underlying OS to work. The current NFS and SMB protocols does not provide network level support for file notifications. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dev serve [RESOURCE_DIR]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Serve resources from a directory: gcx dev serve ./resources # Serve resources from a directory but don't watch for changes: gcx dev serve ./resources --no-watch # Serve resources from a script that outputs a YAML resource and watch for changes: # Note: the Grafana Foundation SDK can be used to generate dashboards (https://grafana.github.io/grafana-foundation-sdk/) gcx dev serve --script 'go run dashboard-generator/*.go' --watch ./dashboard-generator --script-format yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --address string Address to bind (default loopback; use 0.0.0.0 to expose on all interfaces) (default "127.0.0.1") -h, --help help for serve --max-concurrent int Maximum number of concurrent operations (default 10) --no-watch Do not watch for changes --port int Port on which the server will listen (default 8080) -S, --script string Script to execute to generate a resource -f, --script-format string Format of the data returned by the script (default "json") -w, --watch stringArray Paths to watch for changes ``` Inherits `--config`, `--context` from [`gcx dev`](#gcx-dev-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx docs` Search, fetch, and outline Grafana Labs product documentation, backed by an in-memory index of grafana.com docs. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for docs ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx docs get` Fetch a documentation page as cleaned markdown. Supports section extraction and offset/limit paging for bounded retrieval. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx docs get [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Fetch a doc gcx docs get https://grafana.com/docs/tempo/latest/traceql/construct-traceql-queries/ # Extract a single section gcx docs get https://grafana.com/docs/tempo/latest/traceql/construct-traceql-queries/ --section "Comparison operators" # Advanced: page through a long doc (Tempo Configure is ~3000 lines) gcx docs get https://grafana.com/docs/tempo/latest/configuration/ --offset 80 --limit 80 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum lines to return (0 or negative uses the default of 80) --offset int Line offset for paging (0-indexed) -o, --output string Output format. One of: agents, json, text, yaml (default "text") --section string Heading text to extract (returns only that section) ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx docs list-links` List the curated set of canonical Grafana documentation URLs that gcx surfaces in help text and error messages. Pass any URL to ‘gcx docs get’ to read the page content. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx docs list-links [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx docs list-links ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-links --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx docs list-products` List all product documentation groups in the index with their page counts. Use a product name with ‘gcx docs search –product ’ to scope search results. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx docs list-products [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx docs list-products ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-products --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx docs outline` List the headings of a documentation page so you can target a section with ‘gcx docs get –section’. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx docs outline [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx docs outline https://grafana.com/docs/tempo/latest/traceql/construct-traceql-queries/ ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for outline --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx docs search` Search the documentation index by keyword. Multiple words are joined into one phrase. Matching is case-insensitive; each word is scored independently, and entries matching more words rank higher. Returns matching pages ranked by relevance. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx docs search [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Search across all products gcx docs search "rate limiting" # Scope the search to one product gcx docs search "traceql query" --product tempo # Return more results as JSON gcx docs search dashboards --limit 10 -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for search --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of results (0 or negative uses the default) (default 5) -o, --output string Output format. One of: agents, json, text, yaml (default "text") --product string Filter results to a specific product (case-insensitive; matches exact, then prefix, then substring; empty = all products) ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet` Manage Grafana Fleet Management pipelines and collectors **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for fleet ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet collectors` Manage Fleet Management collectors. **Aliases:** `collector` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for collectors ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet collectors create` Create a collector from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet collectors create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the collector manifest (use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet collectors delete` Delete a collector. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet collectors delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet collectors get` Get one Fleet Management collector by ID or name. Structured output includes local and remote attributes plus the timestamps that the Fleet API reports. Use table or wide output for a human-readable health view. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet collectors get [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Get the full collector resource gcx fleet collectors get # Show the collector health fields as a table gcx fleet collectors get -o wide # Select attributes and update time gcx fleet collectors get --json spec.local_attributes,spec.remote_attributes,spec.updated_at ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "yaml") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet collectors list` List Fleet Management collectors and their reported health attributes. Use –limit 0 for a complete fleet audit. Structured output includes local and remote attributes plus the timestamps that the Fleet API reports. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet collectors list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List a bounded collector summary gcx fleet collectors list # Audit versions and operating systems across the complete fleet gcx fleet collectors list --limit 0 --json spec.id,spec.local_attributes,spec.updated_at # Build a compact version inventory gcx fleet collectors list --limit 0 --jq '[.[] | {id: .spec.id, version: .spec.local_attributes["collector.version"], os: (.spec.local_attributes["collector.os"] // .spec.local_attributes["os.type"]), updated_at: .spec.updated_at}]' ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of collectors to return. 0 means all results are returned (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet collectors update` Update a collector from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet collectors update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the collector manifest (use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet pipelines` Manage Fleet Management pipelines. **Aliases:** `pipeline` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for pipelines ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet pipelines create` Create a pipeline from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet pipelines create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the pipeline manifest (use - for stdin) --force Override protection guard for instrumentation-managed pipelines -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet pipelines delete` Delete a pipeline. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet pipelines delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Override protection guard for instrumentation-managed pipelines -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet pipelines get` Get a pipeline by ID or name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet pipelines get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet pipelines list` List pipelines. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet pipelines list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet pipelines update` Update a pipeline from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet pipelines update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the pipeline manifest (use - for stdin) --force Override protection guard for instrumentation-managed pipelines -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet tenant` Fleet Management tenant settings. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for tenant ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet tenant get-limits` Get tenant limits. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet tenant get-limits [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get-limits --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend` Manage Grafana Frontend Observability resources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for frontend ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend apps` Manage Frontend Observability apps. **Aliases:** `app` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for apps ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend apps apply-sourcemap` Upload a sourcemap for a Frontend Observability app. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx frontend apps apply-sourcemap [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Upload a sourcemap bundle. gcx frontend apps apply-sourcemap my-web-app-42 -f bundle.js.map ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --bundle-id string Bundle ID (auto-generated if not set) -f, --filename string Path to the sourcemap file to upload -h, --help help for apply-sourcemap --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend apps create` Create a Frontend Observability app from a file. Set spec.appType and spec.runtime at creation; the API ignores later changes to appType. Web apps use appType web with runtime web-js. Mobile apps use appType mobile with runtime flutter, react-native, android-native, or swift-native. Create sends spec.extraLogLabels, including the legacy is\_mobile label. Create and update send spec.settings. Set geolocationLevel to continent, country, subdivision, city, or network. Set geolocationCountryDenylist to ISO country codes, such as \[DE], to skip enrichment for those sessions. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx frontend apps create [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Create an app from a YAML file. gcx frontend apps create -f app.yaml # Create a native Android app from stdin. cat < [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend apps delete-sourcemap` Delete sourcemap bundles from a Frontend Observability app. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx frontend apps delete-sourcemap [bundle-id...] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Delete a single sourcemap bundle. gcx frontend apps delete-sourcemap my-web-app-42 1234567890-abc12 # Delete multiple bundles at once. gcx frontend apps delete-sourcemap my-web-app-42 bundle-1 bundle-2 bundle-3 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for delete-sourcemap --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend apps get` Get a Frontend Observability app by slug-id (my-web-app-42), numeric ID or display name. An argument that matches no app by ID is looked up by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx frontend apps get [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Get by slug-id. gcx frontend apps get my-web-app-42 # Get by name. gcx frontend apps get "My Web App" ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend apps list` List Frontend Observability apps. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx frontend apps list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of apps to return. 0 means all results are returned (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend apps list-sourcemaps` List sourcemaps for a Frontend Observability app. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx frontend apps list-sourcemaps [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all sourcemaps for an app. gcx frontend apps list-sourcemaps my-web-app-42 # List the first 10 sourcemaps. gcx frontend apps list-sourcemaps my-web-app-42 --limit 10 # Output as JSON. gcx frontend apps list-sourcemaps my-web-app-42 -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-sourcemaps --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of sourcemaps to return (0 for all) -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend apps update` Update a Frontend Observability app from a file. Omit spec.runtime to keep the stored runtime; an empty runtime is invalid. The API ignores changes to spec.appType. Omitted settings keep their stored values; an empty geolocationCountryDenylist clears it. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx frontend apps update [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Update an app using its slug-id. gcx frontend apps update my-web-app-42 -f app.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the Frontend Observability app manifest (use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend sessions` Inspect Frontend Observability sessions. **Aliases:** `session` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for sessions ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend sessions get` Fetch one Frontend Observability session and write it as plain text. Two labeled blocks are produced: session metadata (once) and events (the user journey). Metadata is named fields once (sdk, app, user, os, geo, browser, device, session times), empty values omitted. Pinot events are TSV; Loki events are timestamp then the log line with those envelope keys stripped. –save writes that same dump. Default -o is text; -o json/yaml, –json, and –jq are rejected. Use –save so agents receive a small artifact receipt on stdout and then read the file. Pinot events use faro\_pinot\_events\_v2 on grafana-ops hosts and faro\_pinot\_events\_v1 everywhere else, matching Frontend Observability. -d/–datasource is the Grafana datasource UID (required). gcx fetches the datasource and infers Loki vs Pinot from its type. Each Loki query times out after 60s so a slow scan cannot hang; try a Pinot datasource UID or a narrower window. Omit –app-type and gcx infers web vs mobile from sdkName / osName on the session (so mobile journeys exclude app\_memory / app\_cpu\_usage). It does not use the app’s stored appType, which older apps may lack or have wrong. Pass –app-type to override. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx frontend sessions get [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Pinot on stdout (metadata fields, journey TSV) gcx frontend sessions get 7TiMbCCvby --app 66 -d grafanacloud-pinot --since 7d # Pinot dump to a file; app type inferred from telemetry gcx frontend sessions get 7TiMbCCvby --app 66 -d grafanacloud-pinot --since 7d \ --save /tmp/session-7TiMbCCvby.txt # Loki dump gcx frontend sessions get 7TiMbCCvby --app 66 -d grafanacloud-logs --since 7d \ --save /tmp/session-7TiMbCCvby.txt # Force mobile SQL (app_memory / app_cpu_usage excluded) gcx frontend sessions get kwwAkkXwas --app 96 --app-type mobile \ -d grafanacloud-pinot --since 7d --save /tmp/session-kwwAkkXwas.txt ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --app string Frontend Observability app slug-id or numeric id (required) --app-type string web or mobile (case-insensitive). Optional: inferred from sdkName/osName when omitted -d, --datasource string Grafana datasource UID (required). Type is inferred (loki or pinot) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for get -o, --output string Output format. One of: text (default "text") --save string Write the session dump to this path instead of stdout --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx help` Help provides help for any command in the application. Simply type gcx help \[path to command] for full details. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx help [command] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for help ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx help-tree` Outputs a token-efficient text tree of the CLI hierarchy with inline args, flags, and agent hints. Designed for injecting into agent context windows. Use positional arguments to show only a subtree (e.g., “gcx help-tree resources get”). Use –depth to limit nesting depth. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx help-tree [COMMAND...] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --depth int Maximum nesting depth (1 = root + direct children, 0 = unlimited) -h, --help help for help-tree --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation` Manage Grafana Instrumentation Hub using action-verb commands. The instrumentation command tree provides: setup Guided onboarding wizard: configures a cluster end-to-end and prints a runnable helm install command. status Cross-cutting observed state for clusters and namespaces (RunK8sMonitoring + ListPipelines merge). check Validate OpenTelemetry instrumentation for an application running locally (env vars, SDK, collector, Beyla, Alloy, Grafana Cloud connectivity). explain Show a markdown explanation for an otel-checker finding by its explain ID. list-explanations Enumerate every registered otel-checker explain ID with its title and severity. clusters Declared and observed state per K8s cluster: list, get, configure, remove, wait. Sub-group “apps” manages namespace-level Beyla configuration. services Workload-level observed state and per-workload inclusion overrides across the fleet: list, get, include, exclude, clear. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for instrumentation ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation check` Validate OpenTelemetry instrumentation configuration for an application running locally. Checks performed: - Common OTEL\_* environment variables (resource attributes, exporter, etc.) - SDK setup and dependencies for the chosen language - OpenTelemetry Collector config file (YAML schema, pipelines, exporters) - Grafana Beyla configuration - Grafana Alloy configuration - Grafana Cloud connectivity (uses env vars for endpoint and credentials) Components is an optional comma-separated list — defaults to all when omitted. Supported components: sdk, beyla, alloy, collector, grafana-cloud. Add –fix-plan=local for a deterministic aggregation of the explanation docs (offline, no billing), or –fix-plan=assistant for a prioritized plan synthesized by Grafana Assistant (BILLABLE, requires a Grafana Cloud context — see [https://grafana.com/docs/grafana-cloud/machine-learning/assistant/pricing.md)](/docs/grafana-cloud/machine-learning/assistant/pricing.md%29). Powered by github.com/grafana/otel-checker. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation check [components] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --collector-config-path string Path to the OpenTelemetry Collector config file. --debug Print additional diagnostic output from the checker. --fix-plan string Synthesize one fix plan for every finding. Values: local - deterministic aggregation of the explanation docs (offline, no billing). assistant - prioritized plan from Grafana Assistant (BILLABLE, requires a Grafana Cloud context). See https://grafana.com/docs/grafana-cloud/machine-learning/assistant/pricing.md. Empty (flag omitted) skips the fix plan. -h, --help help for check --instrumentation-file string Path to the JS instrumentation file. Required when --language=js and --manual-instrumentation. --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --language string Application language. Required for sdk, beyla, alloy, grafana-cloud. Possible values: dotnet, go, java, js, python, ruby, php --manual-instrumentation Application is using manual instrumentation (JS only). -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --package-json-path string Path to package.json for JS dependency checks. ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters` Manage K8s monitoring configuration for clusters. Subcommands: list List all clusters with their instrumentation status get Show declared config and observed status for a single cluster configure Configure K8s monitoring flags (RMW or apply defaults) remove Remove K8s monitoring from a cluster wait Wait until a cluster reaches INSTRUMENTED status apps Manage namespace-level Beyla instrumentation for a cluster **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for clusters ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters apps` Manage namespace-level Beyla auto-instrumentation configuration for a cluster. Commands operate on the declared state stored in Grafana Cloud’s instrumentation service (GetAppInstrumentation / SetAppInstrumentation). The wait command reads observed state from RunK8sDiscovery. Identity is positional: configure and remove take and as the first two positional arguments. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for apps ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters apps configure` Configure Beyla auto-instrumentation for a namespace within the given cluster. Two mutually exclusive modes: –use-defaults –yes Apply all-on canonical defaults, overwriting current state. Requires –yes. Defaults: autoinstrument=true, all signals enabled. –\[=true|false] (one or more) Set listed features; unspecified features preserve their current value (RMW). Idempotent. No confirmation required. Combining –use-defaults with any – flag is an error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters apps configure [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --extended-metrics Set extended Beyla metrics collection. Pass --extended-metrics=false to disable. -h, --help help for configure --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --logging Set log collection. Pass --logging=false to disable. -o, --output string Output format. One of: agents, json, text, yaml (default "text") --process-metrics Set process-level metrics collection. Pass --process-metrics=false to disable. --profiling Set continuous profiling collection. Pass --profiling=false to disable. --tracing Set distributed tracing collection. Pass --tracing=false to disable. --use-defaults Apply all-on canonical defaults. Requires --yes. --yes Confirm the --use-defaults operation (required with --use-defaults) ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters apps get` Get the declared Beyla instrumentation configuration for a single namespace within the given cluster. Reads declared state from GetAppInstrumentation and filters client-side to the requested namespace. Exits non-zero with a not-found error when the namespace has no declared configuration. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters apps get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, wide, yaml (default "text") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters apps list` List all namespace-level Beyla instrumentation entries for the given cluster. Reads declared state from GetAppInstrumentation (a single RPC call). The output reflects the configuration stored in Grafana Cloud, not the live observed state. Use “gcx instrumentation status” for observed-state status. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters apps list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, wide, yaml (default "text") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters apps remove` Remove Beyla auto-instrumentation for a namespace by removing its entry from the cluster’s app instrumentation configuration. The namespace entry is removed from namespaces\[] via a whole-list replacement (SetAppInstrumentation). When no namespace entries remain with included content, the backend deletes the app pipeline entirely. This command requires –yes to proceed. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters apps remove [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for remove --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --yes Confirm removal of namespace app instrumentation ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters apps wait` Wait for the namespace Beyla instrumentation to transition out of a pending state by polling RunK8sDiscovery at 5-second intervals. Exit 0 when the namespace’s workloads reach a stable non-pending state (INSTRUMENTED, NOT\_INSTRUMENTED, EXCLUDED, or any terminal non-error state). Exit non-zero when: - INSTRUMENTATION\_ERROR is observed for any workload. - The –timeout duration elapses while still in a pending state. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters apps wait [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for wait --timeout duration Maximum time to wait (e.g. 5m, 10m, 1h) (default 5m0s) ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters configure` Configure K8s monitoring feature flags on a cluster. Two mutually exclusive modes: –use-defaults –yes Apply canonical defaults, overwriting current state. Requires –yes. Defaults: costMetrics=true, clusterEvents=true, energyMetrics=false, nodeLogs=false. –\[=true|false] (one or more) Set listed features; unspecified features preserve their current value (RMW). Idempotent. No confirmation required. Combining –use-defaults with any – flag is an error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters configure [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Apply defaults to cluster "prod-eu" gcx instrumentation clusters configure prod-eu --use-defaults --yes # Enable cost metrics, preserving other flags (RMW) gcx instrumentation clusters configure prod-eu --cost-metrics # Disable node logs (RMW) gcx instrumentation clusters configure prod-eu --node-logs=false ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --cluster-events Set clusterEvents. Pass --cluster-events=false to disable. --cost-metrics Set costMetrics. Pass --cost-metrics=false to disable. Omit to preserve current value. --energy-metrics Set energyMetrics. Pass --energy-metrics=false to disable. -h, --help help for configure --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --node-logs Set nodeLogs. Pass --node-logs=false to disable. -o, --output string Output format. One of: agents, json, text, yaml (default "text") --use-defaults Apply canonical defaults (costMetrics=true, clusterEvents=true, energyMetrics=false, nodeLogs=false). Requires --yes. --yes Confirm the --use-defaults operation (required with --use-defaults) ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters get` Show the declared K8s monitoring configuration and observed instrumentation status for a single cluster. The declared configuration is fetched via GetK8SInstrumentation. The observed status is cross-referenced with RunK8sMonitoring. If the cluster is absent from RunK8sMonitoring, ListPipelines is checked: a K8s monitoring pipeline present means PENDING\_INSTRUMENTATION; absent means NOT\_INSTRUMENTED. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters get [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Get cluster "prod-eu" in table format gcx instrumentation clusters get prod-eu # Get in JSON format gcx instrumentation clusters get prod-eu -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters list` List all clusters with their K8s monitoring configuration and observed status. Merges RunK8sMonitoring with ListPipelines to surface clusters that have been configured but whose Alloy collector has not yet started reporting (pre-Alloy clusters appear with PENDING\_INSTRUMENTATION status). For each cluster, the declared configuration is fetched concurrently via GetK8SInstrumentation (up to 10 concurrent requests). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all clusters (table output) gcx instrumentation clusters list # List in wide format (shows all flag columns) gcx instrumentation clusters list -o wide # Output as JSON gcx instrumentation clusters list -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters remove` Remove K8s monitoring from a cluster. Calls SetK8SInstrumentation with Selection=SELECTION\_EXCLUDED. The backend interprets this as a request to delete the K8s monitoring pipeline for the cluster. IMPORTANT: After removing, the cluster’s status takes approximately 5 minutes to transition from INSTRUMENTED to NOT\_INSTRUMENTED. During this decay window, the cluster may still appear as INSTRUMENTED in status output. This is expected behaviour — the Alloy collector drains its in-flight telemetry before stopping. Requires –yes to confirm the destructive operation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters remove [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Remove K8s monitoring for cluster "prod-eu" gcx instrumentation clusters remove prod-eu --yes ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for remove --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --yes Confirm the remove operation (required) ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters wait` Poll until the specified cluster reaches INSTRUMENTED status. The command polls RunK8sMonitoring every 5 seconds. Before starting the polling loop, it performs a pre-flight check to verify the cluster has been declared (via gcx instrumentation setup) — if not configured, it returns an error immediately with a remediation hint. Exit codes: 0 Cluster reached INSTRUMENTED status (or a non-error terminal state) 1 Timeout reached before INSTRUMENTED status 1 INSTRUMENTATION\_ERROR status observed 1 Pre-flight check failed (cluster not declared) shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters wait [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Wait with default 5-minute timeout gcx instrumentation clusters wait prod-eu # Wait with a custom timeout gcx instrumentation clusters wait prod-eu --timeout 10m ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for wait --timeout duration Maximum time to wait for INSTRUMENTED status (default 5m0s) ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation explain` Show a markdown explanation document for an otel-checker finding. Each finding emitted by `gcx instrumentation check` may carry an explain ID (e.g. env.otel-service-name.unset). Passing that ID here prints the full explanation — what the finding means, why it matters, and how to fix it. To see every available ID, run `gcx instrumentation list-explanations`. Powered by github.com/grafana/otel-checker. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation explain [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for explain --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation list-explanations` List every registered otel-checker explain ID with its title and severity. Use one of the IDs with `gcx instrumentation explain ` to see the full explanation for a specific finding. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation list-explanations [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-explanations --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation services` Manage workload-level observed state and per-workload inclusion overrides across the fleet. Subcommands: list List all discovered workloads, with optional filtering. get Get a single workload by (cluster, namespace, service). include Include a workload for instrumentation (DWIM, idempotent). exclude Exclude a workload from instrumentation (DWIM, idempotent). clear Remove a per-workload override, inheriting namespace default. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for services ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation services clear` Remove any per-workload inclusion or exclusion override for a workload. After clearing, the workload inherits the namespace autoinstrument default. The operation is idempotent: if no override exists for the workload, the command exits 0 without making any backend calls. The write uses an optimistic-lock guard (rmw.Update) when a change is needed: if the namespace list changes between the initial read and the pre-write re-check, the command returns a conflict error and must be retried. Examples: shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation services clear prod-1 checkout frontend ``` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation services clear [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for clear --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation services exclude` Exclude a specific workload from instrumentation using DWIM semantics. DWIM logic: - Removes any existing INCLUDED override for the workload. - Adds an EXCLUDED override iff the namespace autoinstrument is explicitly true (i.e. the namespace default is on, so an explicit opt-out is needed). - If the namespace autoinstrument is false/nil, no override is added (the namespace default is already off — adding EXCLUDED would be redundant). The operation is idempotent: running it twice with the same args exits 0 and the second call is a no-op against the backend. The write uses an optimistic-lock guard (rmw.Update): if the namespace list changes between the initial read and the pre-write re-check, the command returns a conflict error and must be retried. Examples: shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation services exclude prod-1 checkout payment-svc ``` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation services exclude [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for exclude --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation services get` Get a single workload discovered by the Beyla survey collector. Calls RunK8sDiscovery() (fleet-wide RPC) and filters to the requested workload. Returns an error if the workload is not found. Examples: shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation services get prod-1 checkout frontend gcx instrumentation services get prod-1 checkout frontend -o json ``` Workload-level Selection / override state is not surfaced on this command. To inspect a workload’s override, run “gcx instrumentation clusters apps list –cluster= –namespace=”. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation services get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, wide, yaml (default "text") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation services include` Include a specific workload for instrumentation using DWIM semantics. DWIM logic: - Removes any existing EXCLUDED override for the workload. - Adds an INCLUDED override iff the namespace autoinstrument is NOT explicitly true (i.e. the namespace default is off, so an explicit opt-in is needed). - If the namespace autoinstrument is true, no override is added (namespace default is already on — adding INCLUDED would be redundant). The operation is idempotent: running it twice with the same args exits 0 and the second call is a no-op against the backend. The write uses an optimistic-lock guard (rmw.Update): if the namespace list changes between the initial read and the pre-write re-check, the command returns a conflict error and must be retried. Examples: shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation services include prod-1 checkout frontend ``` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation services include [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for include --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation services list` List all workloads discovered by the Beyla survey collector. Calls RunK8sDiscovery() (fleet-wide RPC) and applies client-side filters. Examples: shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all workloads gcx instrumentation services list ``` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Filter to a specific cluster gcx instrumentation services list --cluster prod-1 ``` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Filter to a specific namespace gcx instrumentation services list --namespace checkout ``` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Show only workloads in terminal error state gcx instrumentation services list --status=ERROR ``` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Wide output with extra columns gcx instrumentation services list -o wide ``` Workload-level Selection / override state is not surfaced on this command. To inspect a workload’s override, run “gcx instrumentation clusters apps list –cluster= –namespace=”. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation services list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -A, --all Show services from all namespaces (fleet-wide) --cluster string Filter by cluster name -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -n, --namespace string Filter by Kubernetes namespace -o, --output string Output format. One of: agents, json, text, wide, yaml (default "text") --status string Filter by instrumentation status (e.g. ERROR, INSTRUMENTED) ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation setup` Onboard a Kubernetes cluster end-to-end by configuring K8s monitoring and printing a runnable helm install command. Steps performed: 1. Calls SetupK8sDiscovery — idempotent, safe to re-run. 2. Reads the cluster’s current K8s monitoring configuration. 3. Resolves desired flag values: prompts interactively (when stdin is a TTY and –use-defaults is absent) or applies defaults under –use-defaults: costMetrics=true clusterEvents=true energyMetrics=false nodeLogs=false Per-flag overrides (–cost-metrics\[=true|false], –cluster-events\[=true|false], –energy-metrics\[=true|false], –node-logs\[=true|false]) take precedence over defaults. 4. Calls SetK8SInstrumentation only when at least one flag changed. 5. Emits a mutation summary to stderr. 6. Prints a parameterized helm command to stdout. Re-running with unchanged inputs is safe and idempotent. The helm command installs grafana-cloud-onboarding and connects the cluster to Grafana Cloud via Fleet Management. Replace <YOUR\_CLOUD\_ACCESS\_TOKEN> with a Cloud Access Policy token scoped to metrics:read and set:alloy-data-write. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation setup [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --cluster-events Set clusterEvents under --use-defaults. Pass --cluster-events=false to disable. Omit to use default (true). --cost-metrics Set costMetrics under --use-defaults. Pass --cost-metrics=false to disable. Omit to use default (true). --energy-metrics Set energyMetrics under --use-defaults. Pass --energy-metrics=false to disable. Omit to use default (false). -h, --help help for setup --node-logs Set nodeLogs under --use-defaults. Pass --node-logs=false to disable. Omit to use default (false). --print-helm-only Print the helm command and exit; no server calls are made --use-defaults Apply defaults without prompting (required when stdin is not a TTY) ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation status` Show observed instrumentation state across all clusters, or narrow to a specific cluster or namespace. Without flags, lists all clusters including pre-Alloy clusters that have been configured but whose Alloy collector has not yet started reporting (shown as PENDING\_INSTRUMENTATION). Use –cluster to filter to a single cluster. Add –namespace to drill down to workload-level status for a specific namespace, powered by RunK8sDiscovery. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation status [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --cluster string Filter output to a specific cluster -h, --help help for status --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --namespace string Filter to a specific namespace; switches to workload-level view -o, --output string Output format. One of: agents, json, yaml (default "table") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm` Manage Grafana IRM (OnCall + Incidents). Note: Grafana IRM is billed per monthly active user. Actions such as being on an OnCall schedule or escalation chain, changing alert group status, or creating and editing incidents count a user as active. See [https://grafana.com/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/irm-invoice.md](/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/irm-invoice.md). **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for irm ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents` Manage incidents. **Aliases:** `incident`, `inc` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for incidents ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents activity` Manage incident activity timeline. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for activity ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents activity add` Add a note to an incident’s activity timeline. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents activity add [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --body string Note body to add -h, --help help for add --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents close` Close (resolve) an incident. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents close [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for close --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents create` Create a new incident from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents create [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Create an incident from a YAML manifest: cat < [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents get-pir` Resolve the post-incident review (PIR) document URL for an incident. The URL is not carried in the incident payload. PIRs are optional and only the Google Workspace integration creates them, so the link exists only where that integration ran. It is recorded on the hook run that copied the PIR template, which this command reads and resolves. An incident can have more than one PIR document if the template was copied again; the most recently created one is reported. An incident without a PIR document prints nothing and exits 0. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents get-pir [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get-pir --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents list` List incidents, most recent first. –status and –severity are applied server-side. –labels and –from/–to are applied client-side, one page at a time, so a highly selective –labels filter can page through the full incident history before collecting –limit incidents. –query is a raw query-string escape hatch and cannot be combined with the structured –labels, –status, or –severity filters. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start of time range (RFC3339, unix timestamp, or relative e.g. now-7d) -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --labels strings Filter by label text or key:value, e.g. squad:mimir (may be repeated) --limit int Maximum number of incidents to return (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --query string Raw incident query string, e.g. "isdrill:true"; cannot be combined with --labels, --status, or --severity --severity string Filter by severity label, e.g. major (see: gcx irm incidents severities list) --status strings Filter by status (active|resolved; repeatable, comma-separated) --to string End of time range (RFC3339, unix timestamp, or relative e.g. now) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents list-activity` List activity items for an incident. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents list-activity [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-activity --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of activity items to return (default 50) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents list-contexts` List contexts attached to an incident. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents list-contexts [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --alert-group-id string Filter by linked alert group ID -h, --help help for list-contexts --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of contexts to return (0 = server default) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --status string Filter by context status --type string Filter by context type (e.g. genericURL, grafana.dashboard, code.github.pr). Note: alert-group links are encoded as genericURL contexts with alertGroupID set — use --alert-group-id to filter those. ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents open` Open an incident in the browser. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents open [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for open ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents severities` Manage incident severity levels. **Aliases:** `severity` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for severities ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents severities list` List severity levels for the organization. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents severities list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents update` Update the severity or the title of an incident. The severity is the display label, not the identifier. Run `gcx irm incidents severities list` for the labels of your organization. gcx reads the incident first, so a value that already matches causes no write. The command prints one line that names the fields it changed. Use -o json or -o yaml for a structured update result. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents update [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Raise the severity of an incident: gcx irm incidents update 4 --severity Critical # Correct the title: gcx irm incidents update 4 --title "Checkout latency above the objective" ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --severity string New severity label (run 'gcx irm incidents severities list' for the valid values) --title string New title ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall` Manage Grafana OnCall resources. **Aliases:** `oc` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for oncall ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups` Manage alert groups. **Aliases:** `alert-group`, `ag` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for alert-groups ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups acknowledge` Acknowledge alert groups. Two forms are supported: - Single-target: pass a positional . - Bulk-by-filter: omit the positional and pass one or more filter flags (–team, –state, –integration, –max-age, –mine, –all). Bulk-by-filter prompts for confirmation in TTY mode when the matched count exceeds 1; pass –force to skip the prompt. Agent mode requires –force explicitly when count > 1 (auto-confirm of destructive bulk operations is disabled by design). Idempotent: re-running on an already-acknowledged group reports changed:false (single-target) or summary.skipped++ (bulk) — not an error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups acknowledge [] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all Bypass the default status and is_root filters --force Skip the count-confirmation prompt and proceed without interactive confirmation -h, --help help for acknowledge --integration strings Filter: integration PK (repeatable) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-age string Filter: alert groups started within this duration (e.g. 1h, 24h, 7d) --mine Filter: limit to alert groups for the authenticated user -o, --output string Output format. One of: agents, json, text, yaml (default "text") --state strings Filter: state (firing|acknowledged|resolved|silenced; repeatable) --team strings Filter: team PK (repeatable) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups delete` Delete alert groups. Two forms are supported: - Single-target: pass a positional . - Bulk-by-filter: omit the positional and pass one or more filter flags (–team, –state, –integration, –max-age, –mine, –all). Bulk-by-filter prompts for confirmation in TTY mode when the matched count exceeds 1; pass –force to skip the prompt. Agent mode requires –force explicitly when count > 1 (auto-confirm of destructive bulk operations is disabled by design). Destructive: delete removes the alert group; there is no idempotent skip path. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups delete [] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all Bypass the default status and is_root filters --force Skip the count-confirmation prompt and proceed without interactive confirmation -h, --help help for delete --integration strings Filter: integration PK (repeatable) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-age string Filter: alert groups started within this duration (e.g. 1h, 24h, 7d) --mine Filter: limit to alert groups for the authenticated user -o, --output string Output format. One of: agents, json, text, yaml (default "text") --state strings Filter: state (firing|acknowledged|resolved|silenced; repeatable) --team strings Filter: team PK (repeatable) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups get` Get an alert group by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --include-raw Include the unprocessed Alertmanager-shape payload under status.raw (hidden by default; the curated status.{target,links,...} blocks are the promoted view of the same data) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups list` List alert groups. By default, lists root alert groups (excluding child groups merged into parents) in firing, acknowledged, or silenced state. Resolved groups are excluded. Use –all to bypass these defaults entirely (returns resolved and child groups too). Use –state to override the status filter (e.g. –state firing,acknowledged). Use –include-child-groups to keep the status default but include child groups. Alert group records carry no escalation chain field, so –escalation-chain is the only way to attribute alert load to the rotation that was actually paged. It is not interchangeable with –integration: one integration routes to several chains. –max-age anchors to now; use –from/–to for a historical started-at window, and –resolved-from/–resolved-to for a resolved-at window. They accept RFC3339, a unix timestamp, or a relative expression like now-30d. –max-age and –from/–to cannot be combined. –limit 0 returns every matching alert group, walking the endpoint’s pages until they are exhausted. Over a wide window on a busy stack that is many sequential requests, so narrow the window or the filters when a partial answer will do. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List firing, acknowledged, and silenced root groups gcx irm oncall alert-groups list # Narrow to one team, most recent day gcx irm oncall alert-groups list --team --max-age 24h # Attribute load to a rotation (chain IDs: gcx irm oncall escalation-chains list) gcx irm oncall alert-groups list --escalation-chain --all # Historical window, including resolved groups gcx irm oncall alert-groups list --from now-30d --to now-7d --all # Groups resolved last week by a given user gcx irm oncall alert-groups list --resolved-by --resolved-from now-7d --all ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --acknowledged-by strings Filter by acknowledging user ID (repeatable, comma-separated; see: gcx irm oncall users list) --all Bypass the default status and is_root filters (returns resolved groups and child groups too) --escalation-chain strings Filter by escalation chain ID (repeatable, comma-separated; see: gcx irm oncall escalation-chains list) --from string Start of the started-at window (RFC3339, unix timestamp, or relative e.g. now-30d); cannot be combined with --max-age --has-related-incident Limit to alert groups linked to an incident -h, --help help for list --include-child-groups Include child groups (drops the is_root filter while keeping the status default) --integration strings Filter by integration PK (repeatable, comma-separated) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of alert groups to return. 0 means all results are returned (default 50) --max-age string Exclude groups older than this duration (e.g. 1h, 24h, 7d) --mine Limit to alert groups for the authenticated user -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --resolved-by strings Filter by resolving user ID (repeatable, comma-separated; see: gcx irm oncall users list) --resolved-from string Start of the resolved-at window (RFC3339, unix timestamp, or relative e.g. now-30d) --resolved-to string End of the resolved-at window (RFC3339, unix timestamp, or relative e.g. now-7d); defaults to now --state strings Filter by state (firing|acknowledged|resolved|silenced; repeatable, comma-separated). Default: firing,acknowledged,silenced --team strings Filter by team PK (repeatable, comma-separated) --to string End of the started-at window (RFC3339, unix timestamp, or relative e.g. now-7d); defaults to now --with-resolution-note Limit to alert groups that have a resolution note ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups list-alerts` List individual alerts for an alert group. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups list-alerts [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-alerts --history Opt out of collapse: emit every stored Alert as its own row with status.occurrences=1 (default behaviour collapses re-fires by alert label set) --include-raw Include the unprocessed Alertmanager-shape payload under status.raw on each alert (hidden by default; status.{dimensions,links,...} are the promoted view of the same data) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Cap on number of alerts retrieved (0 = no cap) (default 100) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --slim Skip per-alert retrieval; emit only metadata + alert-group back-pointer ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups resolve` Resolve alert groups. Two forms are supported: - Single-target: pass a positional . - Bulk-by-filter: omit the positional and pass one or more filter flags (–team, –state, –integration, –max-age, –mine, –all). Bulk-by-filter prompts for confirmation in TTY mode when the matched count exceeds 1; pass –force to skip the prompt. Agent mode requires –force explicitly when count > 1 (auto-confirm of destructive bulk operations is disabled by design). Idempotent: re-running on an already-resolved group reports changed:false (single-target) or summary.skipped++ (bulk) — not an error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups resolve [] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all Bypass the default status and is_root filters --force Skip the count-confirmation prompt and proceed without interactive confirmation -h, --help help for resolve --integration strings Filter: integration PK (repeatable) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-age string Filter: alert groups started within this duration (e.g. 1h, 24h, 7d) --mine Filter: limit to alert groups for the authenticated user -o, --output string Output format. One of: agents, json, text, yaml (default "text") --state strings Filter: state (firing|acknowledged|resolved|silenced; repeatable) --team strings Filter: team PK (repeatable) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups silence` Silence alert groups. Two forms are supported: - Single-target: pass a positional . - Bulk-by-filter: omit the positional and pass one or more filter flags (–team, –state, –integration, –max-age, –mine, –all). Bulk-by-filter prompts for confirmation in TTY mode when the matched count exceeds 1; pass –force to skip the prompt. Agent mode requires –force explicitly when count > 1 (auto-confirm of destructive bulk operations is disabled by design). Idempotent: re-running on an already-silenced group reports changed:false (single-target) or summary.skipped++ (bulk) — not an error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups silence [] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all Bypass the default status and is_root filters --duration int Silence duration in seconds (default 3600) --force Skip the count-confirmation prompt and proceed without interactive confirmation -h, --help help for silence --integration strings Filter: integration PK (repeatable) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-age string Filter: alert groups started within this duration (e.g. 1h, 24h, 7d) --mine Filter: limit to alert groups for the authenticated user -o, --output string Output format. One of: agents, json, text, yaml (default "text") --state strings Filter: state (firing|acknowledged|resolved|silenced; repeatable) --team strings Filter: team PK (repeatable) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups unacknowledge` Unacknowledge alert groups. Two forms are supported: - Single-target: pass a positional . - Bulk-by-filter: omit the positional and pass one or more filter flags (–team, –state, –integration, –max-age, –mine, –all). Bulk-by-filter prompts for confirmation in TTY mode when the matched count exceeds 1; pass –force to skip the prompt. Agent mode requires –force explicitly when count > 1 (auto-confirm of destructive bulk operations is disabled by design). Idempotent: re-running on an already-unacknowledged group reports changed:false (single-target) or summary.skipped++ (bulk) — not an error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups unacknowledge [] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all Bypass the default status and is_root filters --force Skip the count-confirmation prompt and proceed without interactive confirmation -h, --help help for unacknowledge --integration strings Filter: integration PK (repeatable) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-age string Filter: alert groups started within this duration (e.g. 1h, 24h, 7d) --mine Filter: limit to alert groups for the authenticated user -o, --output string Output format. One of: agents, json, text, yaml (default "text") --state strings Filter: state (firing|acknowledged|resolved|silenced; repeatable) --team strings Filter: team PK (repeatable) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups unresolve` Unresolve alert groups. Two forms are supported: - Single-target: pass a positional . - Bulk-by-filter: omit the positional and pass one or more filter flags (–team, –state, –integration, –max-age, –mine, –all). Bulk-by-filter prompts for confirmation in TTY mode when the matched count exceeds 1; pass –force to skip the prompt. Agent mode requires –force explicitly when count > 1 (auto-confirm of destructive bulk operations is disabled by design). Idempotent: re-running on an already-unresolved group reports changed:false (single-target) or summary.skipped++ (bulk) — not an error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups unresolve [] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all Bypass the default status and is_root filters --force Skip the count-confirmation prompt and proceed without interactive confirmation -h, --help help for unresolve --integration strings Filter: integration PK (repeatable) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-age string Filter: alert groups started within this duration (e.g. 1h, 24h, 7d) --mine Filter: limit to alert groups for the authenticated user -o, --output string Output format. One of: agents, json, text, yaml (default "text") --state strings Filter: state (firing|acknowledged|resolved|silenced; repeatable) --team strings Filter: team PK (repeatable) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups unsilence` Unsilence alert groups. Two forms are supported: - Single-target: pass a positional . - Bulk-by-filter: omit the positional and pass one or more filter flags (–team, –state, –integration, –max-age, –mine, –all). Bulk-by-filter prompts for confirmation in TTY mode when the matched count exceeds 1; pass –force to skip the prompt. Agent mode requires –force explicitly when count > 1 (auto-confirm of destructive bulk operations is disabled by design). Idempotent: re-running on an already-unsilenced group reports changed:false (single-target) or summary.skipped++ (bulk) — not an error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups unsilence [] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all Bypass the default status and is_root filters --force Skip the count-confirmation prompt and proceed without interactive confirmation -h, --help help for unsilence --integration strings Filter: integration PK (repeatable) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-age string Filter: alert groups started within this duration (e.g. 1h, 24h, 7d) --mine Filter: limit to alert groups for the authenticated user -o, --output string Output format. One of: agents, json, text, yaml (default "text") --state strings Filter: state (firing|acknowledged|resolved|silenced; repeatable) --team strings Filter: team PK (repeatable) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalate` Create a direct escalation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalate [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for escalate --important Mark as important --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --message string Message for the escalation -o, --output string Output format. One of: agents, json, text, yaml (default "text") --team string Team ID --title string Title of the escalation (required) --user-ids strings User IDs (comma-separated) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-chains` Manage escalation chains. **Aliases:** `escalation-chain`, `ec` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for escalation-chains ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-chains create` Create an escalation chain. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-chains create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-chains delete` Delete an escalation chain by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-chains delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-chains get` Get an escalation chain by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-chains get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-chains list` List escalation chains. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-chains list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-chains update` Update an escalation chain by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-chains update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-policies` Manage escalation policies. **Aliases:** `escalation-policy`, `ep` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for escalation-policies ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-policies create` Create an escalation policy. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-policies create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-policies delete` Delete an escalation policy by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-policies delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-policies get` Get an escalation policy by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-policies get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-policies list` List escalation policies. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-policies list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-policies list-step-types` List the step types that an escalation policy accepts. The command reads the catalog from the Incident Response and Management backend, so the values match your stack. Put the numeric value in the step field of an escalation policy manifest. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-policies list-step-types [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List the step types that an escalation policy accepts gcx irm oncall escalation-policies list-step-types # Read the numeric value of one step type gcx irm oncall escalation-policies list-step-types -o json | jq -r '.[] | select(.display_name == "") | .value' # Put that value in the step field of policy.yaml, then create the policy gcx irm oncall escalation-policies create -f policy.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-step-types --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-policies steps` Discover allowed escalation policy step types. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for steps ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-policies steps list` List the step types that an escalation policy accepts. The command reads the catalog from the Incident Response and Management backend, so the values match your stack. Put the numeric value in the step field of an escalation policy manifest. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-policies steps list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List the step types that an escalation policy accepts gcx irm oncall escalation-policies list-step-types # Read the numeric value of one step type gcx irm oncall escalation-policies list-step-types -o json | jq -r '.[] | select(.display_name == "") | .value' # Put that value in the step field of policy.yaml, then create the policy gcx irm oncall escalation-policies create -f policy.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-policies update` Update an escalation policy by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-policies update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations` Manage OnCall integrations. **Aliases:** `integration` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for integrations ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations create` Create an integration. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall integrations create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations delete` Delete an integration by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall integrations delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations get` Get an integration by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall integrations get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations get-templates` Get the alert templates of an integration. The templates decide what a responder reads and hears: the alert title, the message, the grouping identifier, the resolve condition, and a separate rendering for each channel (web, phone call, Short Message Service, email, Slack, and Microsoft Teams). The command emits the whole template document. Edit that document, then pass it back through update-templates. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall integrations get-templates [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get-templates --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations list` List OnCall integrations. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall integrations list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations start-maintenance` Start maintenance on an integration. Maintenance suppresses escalation during planned work. Mode “maintenance” groups every alert of the integration into one alert group and pages nobody. Mode “debug” routes each alert to its author only. The backend accepts these durations only: 3600, 10800, 21600, 43200, 86400 seconds. These values are 1, 3, 6, 12, and 24 hours. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall integrations start-maintenance [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --duration int Maintenance duration in seconds (3600, 10800, 21600, 43200, 86400) (default 3600) -h, --help help for start-maintenance --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --mode string Maintenance mode (debug, maintenance) (default "maintenance") -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations stop-maintenance` Stop maintenance on an integration. Use this to end maintenance before its scheduled end. Escalation resumes at once. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall integrations stop-maintenance [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for stop-maintenance --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations update` Update an integration by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall integrations update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations update-templates` Replace the alert templates of an integration. The file holds the template document as get-templates emits it. Every field travels to the backend unchanged, so a field that this build does not know about still survives a get, an edit, and an update. The command emits the stored document. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall integrations update-templates [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update-templates --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall organizations` View organization info. **Aliases:** `organization`, `org` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for organizations ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall organizations get` Get organization info. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall organizations get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall resolution-notes` Manage resolution notes. **Aliases:** `resolution-note`, `rn` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for resolution-notes ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall resolution-notes create` Create a resolution note. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall resolution-notes create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall resolution-notes delete` Delete a resolution note by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall resolution-notes delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall resolution-notes get` Get a resolution note by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall resolution-notes get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall resolution-notes list` List resolution notes. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall resolution-notes list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall resolution-notes update` Update a resolution note by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall resolution-notes update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall routes` Manage OnCall routes. **Aliases:** `route` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for routes ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall routes create` Create a route. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall routes create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall routes delete` Delete a route by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall routes delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall routes filter-types` Discover route filtering term types. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for filter-types ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall routes filter-types list` List the filter types that a route accepts. The command reads the catalog from the Incident Response and Management backend, so the values match your stack. Put the numeric value in the filtering\_term\_type field of a route manifest. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall routes filter-types list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List the filter types that a route accepts gcx irm oncall routes list-filter-types # Read the numeric value of one filter type gcx irm oncall routes list-filter-types -o json | jq -r '.[] | select(.display_name == "") | .value' # Put that value in the filtering_term_type field of route.yaml, then create the route gcx irm oncall routes create -f route.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall routes get` Get a route by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall routes get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall routes list` List OnCall routes. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall routes list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall routes list-filter-types` List the filter types that a route accepts. The command reads the catalog from the Incident Response and Management backend, so the values match your stack. Put the numeric value in the filtering\_term\_type field of a route manifest. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall routes list-filter-types [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List the filter types that a route accepts gcx irm oncall routes list-filter-types # Read the numeric value of one filter type gcx irm oncall routes list-filter-types -o json | jq -r '.[] | select(.display_name == "") | .value' # Put that value in the filtering_term_type field of route.yaml, then create the route gcx irm oncall routes create -f route.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-filter-types --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall routes update` Update a route by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall routes update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall schedules` Manage OnCall schedules. **Aliases:** `schedule` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for schedules ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall schedules create` Create a schedule. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall schedules create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall schedules delete` Delete a schedule by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall schedules delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall schedules get` Get a schedule by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall schedules get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall schedules list` List OnCall schedules and their current assignees. JSON output includes current assignees in spec.on\_call\_now, with usernames available directly without a separate users lookup. Use –jq to filter the returned schedules by name and select only the fields you need. For coverage over a date range or handover times, use schedules list-final-shifts with the schedule ID from metadata.name; on\_call\_now describes only the current moment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall schedules list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List schedules and current assignees gcx irm oncall schedules list # Show only schedule names and current usernames gcx irm oncall schedules list --jq '[.[] | {name: .spec.name, on_call_now: [.spec.on_call_now[]? | .username]}]' # Find Payments schedules in a known context (name match, case-insensitive) gcx --context prod irm oncall schedules list --jq '[.[] | select(.spec.name | test("payments"; "i")) | {id: .metadata.name, name: .spec.name, on_call_now: [.spec.on_call_now[]? | .username]}]' ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall schedules list-final-shifts` List final shifts for a schedule. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall schedules list-final-shifts [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --end string End date (YYYY-MM-DD) (default "YYYY-MM-DD") -h, --help help for list-final-shifts --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --start string Start date (YYYY-MM-DD) (default "YYYY-MM-DD") --timezone string IANA timezone for the shift boundaries (default: the timezone of the schedule, else UTC) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall schedules update` Update a schedule by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall schedules update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shift-swaps` Manage shift swaps. **Aliases:** `shift-swap`, `ss` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for shift-swaps ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shift-swaps create` Create a shift swap. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shift-swaps create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shift-swaps delete` Delete a shift swap by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shift-swaps delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shift-swaps get` Get a shift swap by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shift-swaps get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shift-swaps list` List shift swaps. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shift-swaps list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shift-swaps update` Update a shift swap by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shift-swaps update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shifts` Manage OnCall shifts. **Aliases:** `shift` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for shifts ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shifts create` Create a shift. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shifts create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shifts delete` Delete a shift by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shifts delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shifts get` Get a shift by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shifts get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shifts list` List OnCall shifts. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shifts list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shifts update` Update a shift by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shifts update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall slack-channels` List Slack channels. **Aliases:** `slack-channel` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for slack-channels ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall slack-channels list` List Slack channels. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall slack-channels list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall teams` Manage OnCall teams. **Aliases:** `team` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for teams ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall teams get` Get a team by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall teams get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall teams list` List OnCall teams. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall teams list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall user-groups` List user groups. **Aliases:** `user-group` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for user-groups ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall user-groups list` List user groups. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall user-groups list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall users` Manage OnCall users. **Aliases:** `user` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for users ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall users current` Get the current user. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall users current [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for current --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall users get` Get a user by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall users get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall users list` List OnCall users. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall users list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks` Manage outgoing webhooks. **Aliases:** `webhook` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for webhooks ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks create` Create an outgoing webhook. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall webhooks create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks delete` Delete an outgoing webhook by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall webhooks delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks get` Get an outgoing webhook by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall webhooks get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks list` List outgoing webhooks. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall webhooks list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks list-presets` List the presets that an outgoing webhook accepts. A preset fills a group of webhook fields, and it limits the trigger types of the webhook. Put the preset ID in the preset field of a webhook manifest. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall webhooks list-presets [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List the webhook presets gcx irm oncall webhooks list-presets # Read the trigger types that one preset allows gcx irm oncall webhooks list-presets -o json | jq -r '.[] | select(.id == "grafana_assistant") | .trigger_types' # Put the preset ID in the preset field of webhook.yaml, then create the webhook gcx irm oncall webhooks create -f webhook.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-presets --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks list-triggers` List the trigger types that an outgoing webhook accepts. The command reads the catalog from the Incident Response and Management backend, so the values match your stack. Put the numeric value in the trigger\_type field of a webhook manifest. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall webhooks list-triggers [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List the trigger types that a webhook accepts gcx irm oncall webhooks list-triggers # Read the numeric value of one trigger type gcx irm oncall webhooks list-triggers -o json | jq -r '.[] | select(.display_name == "") | .value' # Put that value in the trigger_type field of webhook.yaml, then create the webhook gcx irm oncall webhooks create -f webhook.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-triggers --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks presets` Discover webhook configuration presets. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for presets ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks presets list` List the presets that an outgoing webhook accepts. A preset fills a group of webhook fields, and it limits the trigger types of the webhook. Put the preset ID in the preset field of a webhook manifest. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall webhooks presets list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List the webhook presets gcx irm oncall webhooks list-presets # Read the trigger types that one preset allows gcx irm oncall webhooks list-presets -o json | jq -r '.[] | select(.id == "grafana_assistant") | .trigger_types' # Put the preset ID in the preset field of webhook.yaml, then create the webhook gcx irm oncall webhooks create -f webhook.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks triggers` Discover allowed webhook trigger types. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for triggers ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks triggers list` List the trigger types that an outgoing webhook accepts. The command reads the catalog from the Incident Response and Management backend, so the values match your stack. Put the numeric value in the trigger\_type field of a webhook manifest. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall webhooks triggers list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List the trigger types that a webhook accepts gcx irm oncall webhooks list-triggers # Read the numeric value of one trigger type gcx irm oncall webhooks list-triggers -o json | jq -r '.[] | select(.display_name == "") | .value' # Put that value in the trigger_type field of webhook.yaml, then create the webhook gcx irm oncall webhooks create -f webhook.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks update` Update an outgoing webhook by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall webhooks update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6` Manage Grafana k6 Cloud projects, load tests, and schedules **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for k6 ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 auth` k6 authentication commands. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for auth ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 auth token` Print the authenticated k6 API token. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 auth token [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for token ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 env-vars` Manage k6 Cloud environment variables. **Aliases:** `envvars`, `envvar`, `env` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for env-vars ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 env-vars create` Create a k6 environment variable from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 env-vars create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the env var JSON (use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 env-vars delete` Delete a k6 environment variable. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 env-vars delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 env-vars list` List k6 environment variables. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 env-vars list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 env-vars update` Update a k6 environment variable. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 env-vars update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the env var JSON (use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-tests` Manage k6 Cloud load tests. **Aliases:** `tests`, `test` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for load-tests ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-tests create` Create a new k6 load test. Note: running the created test in Grafana Cloud consumes billable Virtual User Hours (VUh). See [https://grafana.com/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/performance-testing-invoice.md](/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/performance-testing-invoice.md). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-tests create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the test definition (JSON/YAML) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Test name (required when --filename not used) -o, --output string Output format. One of: agents, json, yaml (default "yaml") --project-id int Project ID (required when --filename not used) --script string Path to k6 script file (required when --filename not used) ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-tests delete` Delete a k6 load test. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-tests delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-tests delete-schedule` Delete the schedule for a k6 load test. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-tests delete-schedule [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for delete-schedule --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-tests get` Get a single k6 load test by ID or name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-tests get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") --project-id int Project ID (required when looking up by name) ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-tests list` List load tests from k6 Cloud. With –project-id, the server returns tests from that project only. Without it, the command lists tests across projects. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-tests list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --project-id int Filter by project ID ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-tests update` Update a k6 load test from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-tests update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the test definition (JSON/YAML) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-tests update-script` Update the script of a k6 load test from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-tests update-script [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string k6 script file to upload -h, --help help for update-script --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-zones` Manage k6 private load zones. **Aliases:** `load-zone`, `lz` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for load-zones ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-zones create` Register a Private Load Zone. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-zones create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --cpu string CPU limit for load zone pods (default "2") -h, --help help for create --image string k6 runner image (default "grafana/k6:latest") --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --memory string Memory limit for load zone pods (default "1Gi") --name string Load zone name (must be unique in your org) -o, --output string Output format. One of: agents, json, text, yaml (default "text") --provider-id string Provider ID for the load zone ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-zones delete` Deregister a Private Load Zone. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-zones delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-zones list` List all k6 load zones. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-zones list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-zones list-allowed-projects` List projects allowed to use a load zone. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-zones list-allowed-projects [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-allowed-projects --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-zones update-allowed-projects` Replace the set of projects allowed to use a load zone. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-zones update-allowed-projects [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the complete replacement set of project IDs (JSON array) -h, --help help for update-allowed-projects --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 projects` Manage k6 Cloud projects. **Aliases:** `project`, `proj` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for projects ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 projects create` Create a new k6 project from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 projects create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the project manifest (use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 projects delete` Delete a k6 project. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 projects delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 projects get` Get a single k6 project by ID or name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 projects get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 projects list` List k6 Cloud projects. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 projects list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 projects list-allowed-load-zones` List load zones allowed for a project. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 projects list-allowed-load-zones [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-allowed-load-zones --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 projects update` Update a k6 project. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 projects update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the project manifest (use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 projects update-allowed-load-zones` Replace the set of load zones allowed for a project. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 projects update-allowed-load-zones [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the complete replacement set of load zone IDs (JSON array) -h, --help help for update-allowed-load-zones --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 runs` Manage k6 test runs. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for runs ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 runs list` List test runs for a load test. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 runs list [id-or-name] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --id int Load test ID (skip name lookup) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --project-id int Project ID (required when looking up by name) ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 schedules` Manage k6 Cloud schedules. **Aliases:** `schedule` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for schedules ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 schedules create` Create a k6 schedule from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 schedules create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the schedule request (JSON/YAML) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --load-test-id int Load test ID (required) -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 schedules get` Get a single k6 schedule by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 schedules get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 schedules list` List all k6 schedules. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 schedules list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 schedules update` Update a k6 schedule from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 schedules update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the schedule request (JSON/YAML) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 test-run` Manage k6 TestRun CRD manifests. **Aliases:** `testrun` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for test-run ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 test-run emit` Fetch a k6 Cloud test and emit Kubernetes TestRun CRD manifests. Note: applying the manifests (–apply) starts a test run that consumes billable Virtual User Hours (VUh). See [https://grafana.com/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/performance-testing-invoice.md](/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/performance-testing-invoice.md). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 test-run emit [test-name] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --apply Apply ConfigMap and TestRun manifests via kubectl --emit-secret Include Secret manifest stub in output -h, --help help for emit --id int Load test ID (skip name lookup) --namespace string Kubernetes namespace for emitted manifests (default "k6-tests") --parallelism int Number of parallel k6 runner pods (default 1) --project-id int k6 Cloud project ID --token-secret string Secret name for the Grafana Cloud token (default "grafana-k6-token") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 test-run runs` Query k6 Cloud test run history. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for runs ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 test-run runs list` List all test runs for a k6 load test. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 test-run runs list [test-name] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --id int Load test ID (skip name lookup) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --project-id int k6 Cloud project ID (required when using name lookup) ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 test-run status` Show the most recent test run status for a k6 load test. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 test-run status [test-name] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for status --id int Load test ID (skip name lookup) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --project-id int k6 Cloud project ID (required when using name lookup) ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg` Manage Grafana Knowledge Graph rules, entities, and insights **Aliases:** `knowledge-graph` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for kg ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg diagnose` Run diagnostic checks to verify the Knowledge Graph is healthy. Checks stack status, sanity results, entity counts, scope values, telemetry drilldown configuration, and recording rule metrics in Mimir. Use –env to scope checks to a specific environment. Metric checks require a Prometheus datasource. The datasource UID is resolved from –datasource, the datasources.prometheus config key, or auto-discovery. If unavailable, metric checks are skipped. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg diagnose [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg diagnose gcx kg diagnose --env production gcx kg diagnose --env staging --output json gcx kg diagnose --datasource grafanacloud-prom ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Prometheus datasource UID (auto-discovered if omitted) --env string Environment scope -h, --help help for diagnose --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --namespace string Namespace scope -o, --output string Output format. One of: agents, json, table, yaml (default "table") --site string Site scope ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg diagnose labels` Check that deployment\_environment values in raw metrics are correctly mapped to asserts\_env in recording rule outputs. Identifies unmapped environments (services that won’t appear in Entity Graph) and orphaned asserts\_env values with no deployment\_environment source. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg diagnose labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg diagnose labels gcx kg diagnose labels --datasource grafanacloud-prom gcx kg diagnose labels -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Prometheus datasource UID (auto-discovered if omitted) -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg diagnose service` Deep diagnosis for a specific service: entity lookup, relationship analysis, per-service recording rule checks, and interpreted diagnosis with suggested next steps. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg diagnose service NAME [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg diagnose service api-gateway gcx kg diagnose service payment-service --env production gcx kg diagnose service checkout --env production --namespace default -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Prometheus datasource UID (auto-discovered if omitted) --env string Environment scope -h, --help help for service --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --namespace string Namespace scope -o, --output string Output format. One of: agents, json, table, yaml (default "table") --site string Site scope ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg entities` Manage Knowledge Graph entities. Prefer ’list’ for listing and for basic lookups (an entity’s identity and properties — the labels used to build PromQL/Loki queries); it is cheap and is the right choice even when you already know the exact entity. Use ‘inspect’ only for root-cause analysis — it is heavy and can return large output, so don’t reach for it just to read properties. Pick the read verb by what you start with: list Default for listing and basic lookups: an entity’s identity, scope, and properties. Filter to one known entity with ‘–property name=’. Cheap — use this for plain lookups. correlate You have a firing alert (its labels) but not the entity → find which entity the alert hangs off. The “I have an alert, which entity is it?” entry point. inspect Root-cause analysis only — heavy: insight timeline + related entities. Don’t use it just to read an entity’s properties (use ’list’); reach for it only when you need the RCA view. query Arbitrary Cypher over the graph. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for entities ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg entities correlate` Resolve the affected Knowledge Graph entities for one or more firing alerts. Give it an alert’s labels and a time window; it returns the entities the alert hangs off, using the same correlation the product uses to attach alerts to entities. This is the “I have an alert, which entity is it?” entry point — no entity type/name or Cypher required. Provide alerts as inline label sets, from an Alertmanager webhook file, or both: –alert-labels ‘k=v,k=v’ one firing alert per flag (repeatable) -f/–file / stdin Alertmanager JSON — an envelope {“alerts”:\[…]} or a bare array \[{“labels”:{…}}], auto-detected At least one of –alert-labels or -f is required. When nothing correlates the command prints a notice and exits 0 (an empty result is not an error). Note: correlation from a PromQL alert expression (–query) is not yet supported here — the backend fallback is unreliable today; use alert labels instead. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities correlate [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities correlate --alert-labels 'alertname=ErrorRatioBreach,job=cart' --since 1h gcx kg entities correlate -f am-webhook.json --since 1h cat am-webhook.json | gcx kg entities correlate -f - --since 6h ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --alert-labels stringArray Firing alert label set as comma-separated key=value pairs; one flag per alert (repeatable) -f, --file string Alertmanager webhook JSON file, or '-' for stdin (envelope {"alerts":[...]} or bare array [{"labels":...}]) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for correlate --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to (or now); mutually exclusive with --from/--to (default 1h; e.g. 1h, 30m, 7d) --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg entities delete` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Delete an API-origin entity. Scope is part of the entity’s identity, so it must match the value used at upsert — omitting it targets the scope-less entity, and a mismatch returns 404 (not found). This command uses the Knowledge Graph write API, which is gated server-side. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities delete [Type--Name] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --domain string Writable domain slug — a specific application domain such as 'irm' (required) --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Entity name (or use positional Type--Name) -o, --output string Output format. One of: agents, json, text, yaml (default "text") --scope stringToString Scope as key=value (repeatable or comma-separated; must match upsert-time scope) (default []) --type string Entity type (or use positional Type--Name) ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg entities inspect` Show detailed root-cause-analysis context for a single entity, including a link to the RCA Workbench. Use this only when you need the detail: the entity’s insight/assertion timeline and the related entities to investigate next. It calls a heavier endpoint and can return large output. Do not use ‘inspect’ just to read an entity’s identity or properties — for that, use ‘gcx kg entities list’ (optionally with ‘–property name=’ to narrow to one entity), which is cheaper and returns those fields directly. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities inspect [Type--Name] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --domain string Restrict scope auto-discovery to a single KG domain (only applies when scope is auto-discovered; no effect when --env/--namespace/--site is given) --env string Environment scope (run 'gcx kg meta scopes' to see valid values) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for inspect --insight-categories strings Filter insights by category (comma-separated, e.g. saturation,anomaly,failure,error,amend); empty = all categories --insight-hide-chronic-above int Hide insights present more than this percent of the window (0-100); overrides --insight-hide-noise on this axis --insight-hide-noise Apply RCA Workbench noise filter: hide insights older than 48h or present >90% of the window --insight-hide-older-than duration Hide insights older than a whole number of hours (e.g. 24h); overrides --insight-hide-noise on this axis --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Entity name --namespace string Namespace scope (run 'gcx kg meta scopes' to see valid values) --open Open the entity in the RCA Workbench in your browser -o, --output string Output format. One of: agents, json, yaml (default "json") --share-link Print the RCA Workbench URL for this entity to stderr --since string Duration before --to (or now); mutually exclusive with --from/--to (e.g. 1h, 30m, 7d) --site string Site scope (run 'gcx kg meta scopes' to see valid values) --to string End time (RFC3339, Unix timestamp, or relative like 'now') --type string Entity type (run 'gcx kg meta schema' to see available types) ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg entities list` List Knowledge Graph entities for a given type, env, site, namespace. The cheap default for listing entities or looking up basic information about one: its identity (name, type, scope), properties (the labels used to build PromQL/Loki queries — job, namespace, container, image, etc.), and a small snapshot of its current insights. Filter to a single entity with ‘–property name=’. For an entity’s full insight timeline or related entities for root-cause analysis, use ‘gcx kg entities inspect’ instead. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities list --type Service --env --namespace --property name= gcx kg entities list --type Service --env --insight any gcx kg entities list --type Service --env --insight name=Saturation --insight severity=critical gcx kg entities list --type Service --env --property name=~api --insight severity=critical gcx kg entities list --type Service --env --insight severity=critical --json name,scope ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --env string Environment scope (run 'gcx kg meta scopes' to see valid values) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for list --insight stringArray Filter to entities with an active insight: 'any' (has any insight) or key=value (key=~value for substring; name only); valid keys: name, severity (critical|warning|info); repeatable — multiple predicates must match the same assertion --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all; the backend may still page results — use --page to paginate) (default 50) --namespace string Namespace scope (run 'gcx kg meta scopes' to see valid values) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --page int Page number (0-based) --property stringArray Filter by property: name=value (exact) or name=~value (contains); repeatable (run 'gcx kg meta schema' to list property names) --since string Duration before --to (or now); mutually exclusive with --from/--to (e.g. 1h, 30m, 7d) --site string Site scope (run 'gcx kg meta scopes' to see valid values) --to string End time (RFC3339, Unix timestamp, or relative like 'now') --type string Entity type to list (run 'gcx kg meta schema' to see available types) ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg entities query` Query entities by running a read-only Cypher query against the Knowledge Graph. Run ‘gcx kg meta schema’ to discover valid entity types, property names, and relationship names. Response shape (not raw Cypher rows — results are aggregated into this envelope): { “entities”: \[ { “type”, “name”, “scope”, “properties”, “insights” }, … ], “edges”: \[ { “type”, “sourceName”, “sourceType”, “sourceScope”, “destinationName”, “destinationType”, “destinationScope” }, … ], “pageNum”: , “lastPage”: } Tips: - Prefer whole-entity projections like ‘RETURN s, d’ over scalar projections like ‘RETURN d.name’. Whole entities populate the ’entities’ array with full type/name/scope/properties; scalar projections do not round-trip through this envelope. - The –json flag selects keys from the envelope above (entities, edges, pageNum, lastPage) — it does NOT filter properties inside each entity. Use ‘–json list’ to see the envelope keys, then ‘–json entities’ and pipe to jq/python for per-entity field shaping. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities query [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities query "MATCH (s:Service) RETURN s LIMIT 10" gcx kg entities query "MATCH (s:Service)-[:CALLS]->(d:Service) RETURN s, d" --since 1h gcx kg entities query "MATCH (s:Service {namespace: 'prod'}) RETURN s" --since 1h ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --insights-only Return only entities with active insights --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --page int Page number (0-based) --since string Duration before --to (or now); mutually exclusive with --from/--to (e.g. 1h, 30m, 7d) --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg entities upsert` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Create or update an API-origin entity in a writable domain. This command uses the Knowledge Graph write API, which is gated server-side. If the write API is not enabled on your stack, the server returns an error explaining how to request access. Identity is (type, name, scope) + domain; re-running with the same identity updates the entity. Scope is optional but identity-significant. With -f, the input may be a single object or a YAML/JSON array. Array entries are processed in order as independent upserts: the operation is not atomic, and entries already written stay written if a later entry fails. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities upsert [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities upsert --domain myapp --type Service --name checkout --scope env=prod --ttl 1h gcx kg entities upsert -f entity.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --domain string Writable domain slug — a specific application domain such as 'irm' (required; 'kg' is reserved) -f, --file string Input file (YAML/JSON), or '-' for stdin; mutually exclusive with flags -h, --help help for upsert --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Entity name (required) -o, --output string Output format. One of: agents, json, table, yaml (default "json") --property stringToString Property as key=value (repeatable or comma-separated) (default []) --scope stringToString Scope as key=value (repeatable or comma-separated; identity-significant) (default []) --ttl string Time-to-live duration (e.g. 1h, 7d); omitted = never expire --type string Entity type (identifier; required) ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg insights` Fetch chart data and source metrics for an active insight. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for insights ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg insights chart` Get chart data (series + thresholds) for a specific insight on an entity. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg insights chart [Type--Name] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --env string Environment scope -f, --file string Input file (YAML) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for chart --insight string Insight name (e.g. LatencyAverageBreach, ResourceRateAnomaly) — sets the 'alertname' label --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --label stringArray Extra assertion label as key=value (repeatable; e.g. asserts_resource_type=jvm:live_threads to narrow ResourceRateAnomaly to a specific resource) --name string Entity name --namespace string Namespace scope -o, --output string Output format. One of: agents, json, yaml (default "json") --since string Duration before --to (or now); mutually exclusive with --from/--to (e.g. 1h, 30m, 7d) --site string Site scope --to string End time (RFC3339, Unix timestamp, or relative like 'now') --type string Entity type ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg insights sources` List the underlying metrics (name + label matchers) that source a specific insight. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg insights sources [Type--Name] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --env string Environment scope -f, --file string Input file (YAML) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for sources --insight string Insight name (e.g. LatencyAverageBreach, ResourceRateAnomaly) — sets the 'alertname' label --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --label stringArray Assertion label as key=value (repeatable; typically copied from 'kg entities inspect' timeLines[].labels) --name string Entity name --namespace string Namespace scope -o, --output string Output format. One of: agents, json, yaml (default "json") --since string Duration before --to (or now); mutually exclusive with --from/--to (e.g. 1h, 30m, 7d) --site string Site scope --to string End time (RFC3339, Unix timestamp, or relative like 'now') --type string Entity type ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg meta` Show Knowledge Graph metadata: entity types, valid env/namespace/site values, and telemetry query configs. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for meta ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg meta all` Load all sections: schema, scopes, logs, traces, profiles, and metrics. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg meta all [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for all --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --since string Duration before --to (or now); mutually exclusive with --from/--to (e.g. 1h, 30m, 7d) --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg meta logs` Show Loki label mappings for log drilldown. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg meta logs [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for logs --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg meta metrics` Show the asserts:* KPI metrics (Knowledge Graph recording rules) and the entity-property → Prometheus label mapping for querying them. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg meta metrics [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg meta profiles` Show Pyroscope label mappings for profile drilldown. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg meta profiles [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for profiles --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg meta schema` Show entity types, properties, and relationships. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg meta schema [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for schema --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --since string Duration before --to (or now); mutually exclusive with --from/--to (e.g. 1h, 30m, 7d) --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg meta scopes` Show all valid env/namespace/site filter values. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg meta scopes [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for scopes --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --since string Duration before --to (or now); mutually exclusive with --from/--to (e.g. 1h, 30m, 7d) --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg meta traces` Show Tempo label mappings for trace drilldown. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg meta traces [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for traces --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg model-rules` Manage model rules in the Knowledge Graph. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for model-rules ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg model-rules delete` Delete a custom model rules configuration by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg model-rules delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg model-rules get` Get a custom model rules configuration by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg model-rules get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg model-rules list` List all custom model rules configurations. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg model-rules list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg model-rules schema` Fetches the JSON Schema (Draft 2020-12) that describes the ModelRules configuration shape, derived from the backend DTO tree. Pipe to a file and point your editor at it for autocomplete and deep validation when authoring model rules manifests. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg model-rules schema [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for schema --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg model-rules upsert` Upload model rules from a YAML file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg model-rules upsert [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg model-rules upsert -f model-rules.yaml # Validate against the backend and preview the diff without uploading: gcx kg model-rules upsert -f model-rules.yaml --dry-run ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dry-run Validate against the backend and show a diff without uploading. -f, --file string Input file (YAML), or '-' for stdin. -h, --help help for upsert --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg notifications` Manage alert notification configs (AlertConfig) in the Knowledge Graph. These govern how matched alerts notify — the labels an alert must match, extra alert labels and annotations to attach, the “for” duration, and the silenced flag. Distinct from “gcx kg suppressions”, which manages disabled-alert configs. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for notifications ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg notifications delete` Delete an alert notification config by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg notifications delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg notifications get` Get an alert notification config by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg notifications get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg notifications list` List alert notification configs, optionally filtered by category. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg notifications list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --category string Filter by category: request, resource, health, or slo. -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg notifications upsert` Upsert (create or update) one or more alert notification configs from a YAML file or stdin. Applies the entries in the input file, creating each config when absent or updating it when present. Remote configs absent from the file are never deleted. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg notifications upsert [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg notifications upsert -f notifications.yaml echo 'alertConfigs: - name: api-server-latency matchLabels: asserts_slo_name: api-server-latency for: 5m silenced: false' | gcx kg notifications upsert ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --file string Input file (YAML), or '-' for stdin. Reads from stdin if omitted. -h, --help help for upsert --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg open` Open the Knowledge Graph app in the browser. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg open [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for open --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg prom-rules` Manage Knowledge Graph Custom Prometheus rules. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for prom-rules ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg prom-rules delete` Delete a Knowledge Graph Custom Prometheus rule by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg prom-rules delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg prom-rules get` Get a Knowledge Graph Custom Prometheus rule by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg prom-rules get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg prom-rules list` List Knowledge Graph Custom Prometheus rules. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg prom-rules list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg prom-rules schema` Fetches the JSON Schema (Draft 2020-12) that describes the Custom Prometheus rules configuration shape, derived from the backend DTO tree. Pipe to a file and point your editor at it for autocomplete and deep validation when authoring prom-rules manifests. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg prom-rules schema [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for schema --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg prom-rules upsert` Upload Knowledge Graph Custom Prometheus rules from a YAML file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg prom-rules upsert [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg prom-rules upsert -f rules.yaml # Validate against the backend and preview the diff without uploading: gcx kg prom-rules upsert -f rules.yaml --dry-run ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dry-run Validate against the backend and show a diff without uploading. -f, --file string Input file (YAML), or '-' for stdin. -h, --help help for upsert --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg quality` Inspect Knowledge Graph entity quality reports. Quality reports grade how well an entity is instrumented — each report is a set of checks (request metrics, service-map data, deployment environment, span cardinality, logs, profiles, …) with an overall quality percentage. Use ’list’ to rank entities by quality, and ‘get’ to see the failing checks and remediation links for one entity. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for quality ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg quality get` Get the full quality report for a single entity. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg quality get [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg quality get my-service --env gcx kg quality get my-service --env --namespace gcx kg quality get my-service --env --yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --env string Environment scope (required) -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --namespace string Namespace scope -o, --output string Output format. One of: agents, json, table, yaml (default "table") --site string Site scope --type string Entity type (default "Service") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg quality list` List entity quality reports, ranked by quality percent. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg quality list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg quality list --env gcx kg quality list --env --namespace --sort asc gcx kg quality list --env --failed-check span-metrics --failed-check service-graph-metrics gcx kg quality list --env --json entityName,qualityPercent,failedCheckIds ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --entity string Filter by entity name --env string Environment scope --failed-check stringArray Only report entities with these failed check IDs; repeatable -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --namespace string Namespace scope -o, --output string Output format. One of: agents, json, table, yaml (default "table") --page int Page number (0-based) --page-size int Page size (1-100) (default 25) --site string Site scope --sort string Sort by quality percent: asc (worst first) or desc (best first) (default "asc") --type string Entity type to filter by (default "Service") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg relabel-rules` Inspect Mimir relabel rules used by the Knowledge Graph. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for relabel-rules ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg relabel-rules get` Fetch a relabel rule group (prologue, epilogue, or generated). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg relabel-rules get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --type string Rule group to fetch: prologue, epilogue, or generated (default "generated") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg relationships` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Create, update, and delete API-origin edges between Knowledge Graph entities. **Aliases:** `relationship`, `rels` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for relationships ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg relationships delete` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Delete an API-origin edge of the given type between the from/to entities. The endpoint refs (incl. scope) must match the values used at upsert. This command uses the Knowledge Graph write API, which is gated server-side. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg relationships delete [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg relationships delete --type CALLS \ --from myapp/Service/checkout --to myapp/Service/cart --force ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt --from string Source entity ref as domain/Type/name (required) --from-scope stringToString Scope for --from as key=value (repeatable or comma-separated) (default []) -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --to string Target entity ref as domain/Type/name (required) --to-scope stringToString Scope for --to as key=value (repeatable or comma-separated) (default []) --type string Relationship type (identifier; required) ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg relationships upsert` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Create or update an API-origin edge between two existing entities. Both endpoints must already exist. This command uses the Knowledge Graph write API, which is gated server-side. With -f, the input may be a single object or a YAML/JSON array. Array entries are processed in order as independent upserts: the operation is not atomic, and entries already written stay written if a later entry fails. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg relationships upsert [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg relationships upsert --type CALLS --domain myapp \ --from myapp/Service/checkout --to myapp/Service/cart --to-scope env=prod --ttl 1h gcx kg relationships upsert -f rel.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --domain string Writable domain slug for the edge — a specific application domain such as 'irm' (required) -f, --file string Input file (YAML/JSON), or '-' for stdin; mutually exclusive with flags --from string Source entity ref as domain/Type/name (required) --from-scope stringToString Scope for --from as key=value (repeatable or comma-separated) (default []) -h, --help help for upsert --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "json") --property stringToString Property as key=value (repeatable or comma-separated) (default []) --to string Target entity ref as domain/Type/name (required) --to-scope stringToString Scope for --to as key=value (repeatable or comma-separated) (default []) --ttl string Time-to-live duration (e.g. 1h, 7d); omitted = never expire --type string Relationship type (identifier; required) ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg stats` Show entity and active-insight counts, broken down by type, severity, and insight name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg stats [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --env string Environment scope --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for stats --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --namespace string Namespace scope -o, --output string Output format. One of: agents, json, yaml (default "json") --since string Duration before --to (or now); mutually exclusive with --from/--to (e.g. 1h, 30m, 7d) --site string Site scope --to string End time (RFC3339, Unix timestamp, or relative like 'now') --type string Limit to a specific entity type ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg status` Show Knowledge Graph stack status. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg status [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for status --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg suppressions` Manage alert suppressions in the Knowledge Graph. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for suppressions ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg suppressions delete` Delete a suppression by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg suppressions delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg suppressions list` List all alert suppressions. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg suppressions list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg suppressions upsert` Upsert (create or update) one or more suppressions from a YAML file or stdin. Applies the entries in the input file, creating each suppression when absent or updating it when present. Remote suppressions absent from the file are never deleted. Use –dry-run to validate against the backend and preview the diff, scoped to the entries in the input file, without uploading. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg suppressions upsert [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg suppressions upsert -f suppressions.yaml # Validate against the backend and preview the diff without uploading: gcx kg suppressions upsert -f suppressions.yaml --dry-run echo 'disabledAlertConfigs: - name: my-suppression matchLabels: alertname: ErrorRatioBreach job: my-service' | gcx kg suppressions upsert ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dry-run Validate against the backend and show a diff without uploading. -f, --file string Input file (YAML), or '-' for stdin. Reads from stdin if omitted. -h, --help help for upsert --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx login` Authenticate to a Grafana instance (Cloud or on-premises) and save the credentials to the selected config context. Pass CONTEXT\_NAME to target a specific context: - If the context exists, re-authenticate it (server and other fields preserved). - If it does not exist, create a new context with that name. Without CONTEXT\_NAME, re-authenticates the current context, or starts a first-time setup if no current context is configured. First-time setup asks for the Grafana server URL. Leave it empty to sign in to Grafana Cloud in the browser and choose a stack. When no server is known, –cloud –oauth starts that browser sign-in without prompting. To create a Grafana Cloud account, run gcx signup. Auth sources (for non-interactive use): –oauth Browser-based OAuth (recommended for Grafana Cloud). Opens a browser for the user to approve; works in agent mode. –basic-auth Grafana username/password. Use –user or GRAFANA\_USER, and GRAFANA\_PASSWORD. –token Grafana service-account token (created inside the Grafana instance). See: [https://grafana.com/docs/grafana/latest/administration/service-accounts.md](/docs/grafana/latest/administration/service-accounts.md) –cloud-token Grafana Cloud access-policy token (created at grafana.com). See: [https://grafana.com/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-policies/create-access-policies.md](/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-policies/create-access-policies.md) shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx login [CONTEXT_NAME] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx login gcx login --cloud --oauth gcx login prod gcx login prod --server https://prod.grafana.net gcx login prod --server https://prod.grafana.net --oauth gcx login local --server https://grafana.example.com --basic-auth --user admin gcx login --yes prod --token glsa_xxx gcx login --yes --server https://localhost:3000 --token glsa_xxx ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --allow-server-override Allow re-pointing an existing context at a different server URL --basic-auth Authenticate with a Grafana username and password (GRAFANA_USER / GRAFANA_PASSWORD, or interactive prompts) --cloud Force Grafana Cloud target (skip auto-detection). With --oauth and no known server (no --server, GRAFANA_SERVER, or server in the target context), sign in to Grafana Cloud in the browser and choose a stack. To create an account, run gcx signup --cloud-api-url string Override Grafana Cloud API URL --cloud-token string Grafana Cloud API token (enables Cloud management features) --config string Path to the configuration file to use --context string Name of the context to use -h, --help help for login --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --oauth Authenticate via browser-based OAuth (recommended for Grafana Cloud). Works non-interactively and in agent mode: opens a browser for the user to approve. --oauth-callback-port int Fixed local port for the OAuth callback server (default: auto-pick from 54321-54399). Useful when only specific ports are forwarded between a remote host and your browser --oauth-manual Complete browser OAuth without a local callback server: gcx prints the URL, then reads the redirect URL that you copy from the browser address bar. Use this when gcx runs on a remote host and the browser runs on your own computer. Implies --oauth --org-id int Grafana organization ID (defaults to 1 for on-prem) -o, --output string Output format. One of: agents, json, text, yaml (default "text") --server string Grafana server URL (e.g. https://my-stack.grafana.net) --token string Grafana service account token --user string Grafana username for --basic-auth (defaults to GRAFANA_USER) --yes Non-interactive: skip optional prompts and use defaults ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs` Query Loki datasources and manage Adaptive Logs **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for logs ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive` Manage Adaptive Logs resources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for adaptive ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive drop-rules` Manage adaptive log drop rules. Use `list` or `get` to read rules. `list` applies the **global** segment filter (same scope as create/update/delete). `gcx resources get droprules` lists all tenant rules without that filter when the resources command is available. Create and update load a rule from a file (`--filename` / `-f`). The file’s top-level “version” is the rule schema version (only 1); omit or set it to 1 — not the revision field in API JSON. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for drop-rules ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive drop-rules create` Create an adaptive log drop rule from a file. The file’s top-level “version” is the rule schema version (only 1 is supported). Omit it or set it to 1; do not confuse it with the rule revision in API responses. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive drop-rules create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the drop rule definition (use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive drop-rules delete` Delete an adaptive log drop rule. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive drop-rules delete ID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive drop-rules get` Fetch one adaptive log drop rule by ID. For the **global** segment scope, use `list` to enumerate rules first. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive drop-rules get ID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive drop-rules list` List adaptive log drop rules. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive drop-rules list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --expiration-filter string Filter by expiration: all, active, or expired (default "all") -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of drop rules to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive drop-rules update` Update an adaptive log drop rule by ID. The file’s top-level “version” is the rule schema version (only 1 is supported). Omit it or set it to 1; do not confuse it with the rule revision in API responses. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive drop-rules update ID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the drop rule definition (use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive exemptions` Manage adaptive log exemptions. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for exemptions ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive exemptions create` Create an adaptive log exemption. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive exemptions create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") --reason string Reason for the exemption --stream-selector string Log stream selector (required) ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive exemptions delete` Delete an adaptive log exemption. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive exemptions delete ID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive exemptions list` List adaptive log exemptions. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive exemptions list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of exemptions to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive exemptions update` Update an adaptive log exemption. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive exemptions update ID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") --reason string Reason for the exemption --stream-selector string Log stream selector ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive patterns` Manage adaptive log patterns. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for patterns ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive patterns list` List adaptive log pattern recommendations. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive patterns list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --segment string Only include patterns for this segment (ID column from patterns stats, or API map key / selector) --top int Table only: show top N patterns by volume; 0 shows all rows with no rollup (default 10) ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive patterns stats` Summarize pattern volume aggregated by segment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive patterns stats [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for stats --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive segments` Manage adaptive log segments. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for segments ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive segments create` Create an adaptive log segment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive segments create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --fallback-to-default Fall back to default segment -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Segment name (required) -o, --output string Output format. One of: agents, json, yaml (default "json") --selector string Log stream selector (required) ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive segments delete` Delete an adaptive log segment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive segments delete ID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive segments list` List adaptive log segments. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive segments list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of segments to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive segments update` Update an adaptive log segment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive segments update ID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --fallback-to-default Fall back to default segment -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Segment name -o, --output string Output format. One of: agents, json, yaml (default "json") --selector string Log stream selector ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs labels` List all labels or get values for a specific label from a Loki datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all labels (use datasource UID, not name) gcx logs labels -d UID # Get values for a specific label gcx logs labels -d UID --label job # Filter labels with a query gcx logs labels -d UID --query '{app="foo"}' # Filter label values with a query gcx logs labels -d UID --label job --query '{app="foo"}' # Output as JSON gcx logs labels -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.loki is configured) -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label string Get values for this label (omit to list all labels) -o, --output string Output format. One of: agents, json, table, yaml (default "table") -q, --query string LogQL stream selector to scope labels, e.g. '{app="foo"}' (pipeline stages are not supported) ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs metrics` Execute a metric LogQL query and return time-series results. EXPR is a metric LogQL expression (e.g., rate, count\_over\_time, sum). Datasource is resolved from -d flag or datasources.loki in your context. Unlike ’logs query’ which returns log lines, ’logs metrics’ returns time-series data with proper table, graph, and JSON formatters. Instant vs range is deduced from time flags: no time flags = instant query, –since or –from/–to = range query. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs metrics [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Run a metric query over logs gcx logs metrics -d UID 'rate({job="grafana"}[5m])' --since 1h # Print a Grafana Explore share link for the query gcx logs metrics 'rate({job="grafana"}[5m])' --share-link # Output as JSON gcx logs metrics -d UID 'rate({job="grafana"}[5m])' --since 1h -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.loki is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs query` Execute a LogQL query against a Loki datasource. EXPR is the LogQL expression to evaluate. Datasource is resolved from -d flag or datasources.loki in your context. Default table output is optimized for humans. Use -o raw for original line bodies or -o json for the full structured response. Default –limit is 50; use –limit 0 for no cap. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Query logs using configured default datasource gcx logs query '{job="varlogs"}' # Query with explicit datasource UID gcx logs query -d abc123 '{job="varlogs"} |= "error"' # Print a Grafana Explore share link for the query gcx logs query '{job="varlogs"}' --share-link # Raw line bodies only gcx logs query -d abc123 '{job="varlogs"}' -o raw # Output as JSON gcx logs query -d abc123 '{job="varlogs"}' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.loki is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of log lines to return (0 means no limit) (default 50) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, raw, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs series` List log streams (series) from a Loki datasource using LogQL stream selectors. At least one –match selector is required. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs series [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List series matching a selector (use datasource UID, not name) gcx logs series -d UID --match '{job="varlogs"}' # Multiple matchers (OR logic) gcx logs series -d UID --match '{job="varlogs"}' --match '{namespace="default"}' # Output as JSON gcx logs series -d UID --match '{job="varlogs"}' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.loki is configured) -h, --help help for series --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -M, --match stringArray LogQL stream selector (required, e.g., '{job="varlogs"}') -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics` Query Prometheus datasources and manage Adaptive Metrics **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for metrics ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive` Manage Adaptive Metrics resources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for adaptive ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive exemptions` Manage Adaptive Metrics recommendation exemptions. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for exemptions ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive exemptions create` Create a recommendation exemption. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive exemptions create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --active-interval string Active interval (e.g. 30d, 1h) (default "30d") --disable-recommendations Disable all recommendations for matched metrics -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --keep-labels strings Labels to keep (comma-separated) --managed-by string Manager identifier --match-type string Match type: exact, prefix, or suffix (default "exact") --metric string Metric name or pattern -o, --output string Output format. One of: agents, json, yaml (default "json") --reason string Reason for the exemption --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive exemptions delete` Delete a recommendation exemption. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive exemptions delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive exemptions get` Get a recommendation exemption by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive exemptions get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "json") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive exemptions list` List Adaptive Metrics recommendation exemptions. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive exemptions list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all-segments List exemptions across all segments -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of exemptions to return (0 for no limit) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive exemptions update` Update a recommendation exemption. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive exemptions update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --active-interval string Active interval (e.g. 30d, 1h) --disable-recommendations Disable all recommendations for matched metrics -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --keep-labels strings Labels to keep (comma-separated) --managed-by string Manager identifier --match-type string Match type: exact, prefix, or suffix --metric string Metric name or pattern -o, --output string Output format. One of: agents, json, yaml (default "json") --reason string Reason for the exemption --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive recommendations` Manage metric recommendations. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for recommendations ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive recommendations apply` Apply specific or all recommendations as rules. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive recommendations apply [...|--all] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all Apply all recommendations (bulk) --dry-run Preview without applying --force Skip confirmation prompt -h, --help help for apply --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive recommendations diff` Show what applying recommendation(s) would change. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive recommendations diff ... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for diff --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive recommendations list` List metric recommendations. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive recommendations list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --action stringArray Filter by action: add, update, remove, keep (repeatable) -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --reverse Reverse the default sort order --segment string Segment ID --sort string Sort by: metric, savings, series-before, series-after, action (default "metric") --top int Limit to top N results (0 = all) ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive rules` Manage aggregation rules. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for rules ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive rules create` Create an aggregation rule. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive rules create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --aggregation-delay string Aggregation delay (e.g. 5m) --aggregation-interval string Aggregation interval (e.g. 1m) --aggregations strings Aggregation types: sum, count, min, max, sum:counter (comma-separated) --drop Drop the metric entirely --drop-labels strings Labels to drop (comma-separated) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --keep-labels strings Labels to keep (comma-separated) --match-type string Match type: exact, prefix, or suffix (default "exact") --metric string Metric name (required) -o, --output string Output format. One of: agents, json, yaml (default "json") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive rules delete` Delete an aggregation rule. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive rules delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive rules get` Get an aggregation rule by metric name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive rules get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive rules list` List aggregation rules. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive rules list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of rules to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive rules update` Update an aggregation rule. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive rules update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --aggregation-delay string Aggregation delay (e.g. 5m) --aggregation-interval string Aggregation interval (e.g. 1m) --aggregations strings Aggregation types: sum, count, min, max, sum:counter (comma-separated) --drop Drop the metric entirely --drop-labels strings Labels to drop (comma-separated) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --keep-labels strings Labels to keep (comma-separated) --match-type string Match type: exact, prefix, or suffix -o, --output string Output format. One of: agents, json, yaml (default "json") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive segments` Manage Adaptive Metrics segments. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for segments ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive segments create` Create an Adaptive Metrics segment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive segments create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --auto-apply Automatically apply recommendations --fallback-to-default Fall back to default segment when no rules match -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Segment name (required) -o, --output string Output format. One of: agents, json, yaml (default "json") --selector string PromQL label selector (required) ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive segments delete` Delete an Adaptive Metrics segment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive segments delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive segments get` Get an Adaptive Metrics segment by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive segments get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "json") ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive segments list` List Adaptive Metrics segments. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive segments list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of segments to return (0 for no limit) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive segments update` Update an Adaptive Metrics segment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive segments update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --auto-apply Automatically apply recommendations --fallback-to-default Fall back to default segment when no rules match -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Segment name -o, --output string Output format. One of: agents, json, yaml (default "json") --selector string PromQL label selector ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics billing` Query Grafana Cloud billing metrics via the grafanacloud-usage datasource that ships pre-provisioned on every Grafana Cloud stack. These commands are thin conveniences over the generic metrics subcommands; the –datasource flag defaults to “grafanacloud-usage” but can be overridden. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for billing ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics billing labels` List all labels or get values for a specific label from a Prometheus datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics billing labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # All billing label names gcx metrics billing labels # Values for a single label gcx metrics billing labels --label product # Output as JSON gcx metrics billing labels -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label string Get values for this label (omit to list all labels) --match stringArray Series selector(s) to scope results; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) --metric string Only results from series of this metric (narrows every --match selector) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics billing query` Execute a PromQL query against a Prometheus datasource. EXPR is the PromQL expression to evaluate, passed as a positional argument or via –expr (familiar to promtool users). Datasource is resolved from -d flag or datasources.prometheus in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics billing query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Active series right now gcx metrics billing query 'grafanacloud_instance_active_series' # Active series over the last hour gcx metrics billing query 'grafanacloud_instance_active_series' --since 1h --step 1m # Print a Grafana Explore share link for the executed query gcx metrics billing query 'grafanacloud_instance_active_series' --share-link # Output as JSON gcx metrics billing query 'grafanacloud_instance_active_series' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --time string Evaluation time for an instant query (RFC3339, Unix timestamp, or relative like 'now-5m'). Mutually exclusive with --from/--to/--since --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics billing series` List time series matching one or more selectors via the Prometheus /api/v1/series endpoint. A selector can be passed as a positional argument and/or via –match (repeatable). Time range defaults to unbounded; pass –since, or –from/–to, to scope. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics billing series [SELECTOR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # All billing series gcx metrics billing series '{__name__=~"grafanacloud_.*"}' --since 1h # Filter to a specific product gcx metrics billing series '{__name__=~"grafanacloud_.*",product="metrics"}' --since 1h # Output as JSON gcx metrics billing series '{__name__=~"grafanacloud_.*"}' --since 1h -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for series --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --match stringArray Additional series selector(s); repeatable -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics cardinality` Analyze series cardinality by label names and values via the Mimir cardinality analysis API. These endpoints are available on Grafana Mimir (OSS) and Grafana Cloud; on self-hosted Mimir they require -querier.cardinality-analysis-enabled. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for cardinality ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics cardinality label-names` Show, for each label name, how many distinct values it has, via the Mimir cardinality analysis API. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics cardinality label-names [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Top label names by distinct value count (configured default datasource) gcx metrics cardinality label-names # Scope to a metric family and use active-series counting gcx metrics cardinality label-names -d UID --selector '{__name__=~"grafanacloud_.*"}' --count-method active # Output as JSON gcx metrics cardinality label-names -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --count-method string Series counting method: "inmemory" or "active" (default "inmemory") -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) -h, --help help for label-names --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0-500) (default 20) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --selector string PromQL series selector scoping the analysis ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics cardinality label-values` Show, for each requested label name, its distinct values and the number of series per value, via the Mimir cardinality analysis API. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics cardinality label-values [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Per-value series counts for one label gcx metrics cardinality label-values -d UID --label job # Multiple labels, capped and as JSON gcx metrics cardinality label-values -d UID --label job --label instance --limit 50 -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --count-method string Series counting method: "inmemory" or "active" (default "inmemory") -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) -h, --help help for label-values --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label stringArray Label name to analyze; repeatable (required) --limit int Maximum number of items to return per label (0-500) (default 20) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --selector string PromQL series selector scoping the analysis ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics labels` List all labels or get values for a specific label from a Prometheus datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all labels (use datasource UID, not name) gcx metrics labels -d UID # Get values for a specific label gcx metrics labels -d UID --label job # List labels present on a metric gcx metrics labels -d UID --metric http_requests_total # Get values a label takes on a metric gcx metrics labels -d UID --metric http_requests_total --label job # Scope with an arbitrary series selector gcx metrics labels -d UID --match '{job="api"}' # Output as JSON gcx metrics labels -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label string Get values for this label (omit to list all labels) --match stringArray Series selector(s) to scope results; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) --metric string Only results from series of this metric (narrows every --match selector) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics list-names` List metric names from a Prometheus datasource via the label values endpoint for `__name__`. Scope the server-side lookup with –match selectors; filter names client-side with –prefix, –suffix, and –contains, which combine with AND. Output is capped at 100 names by default; pass –limit 0 for the full list. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics list-names [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List metric names (first 100 by default; use datasource UID, not name) gcx metrics list-names -d UID # Find cart-related metrics gcx metrics list-names -d UID --contains cart # Counters only gcx metrics list-names -d UID --suffix _total # Metrics present on a job gcx metrics list-names -d UID --match '{job="api"}' # Output as JSON gcx metrics list-names -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --contains string Only include names containing this string (case-sensitive) -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) -h, --help help for list-names --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of metric names to return. 0 means all results are returned (default 100) --match stringArray Series selector(s) to scope results; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --prefix string Only include names starting with this string (case-sensitive) --suffix string Only include names ending with this string (case-sensitive) ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics metadata` Get metadata (type, help text) for metrics from a Prometheus datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics metadata [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Get all metric metadata (use datasource UID, not name) gcx metrics metadata -d UID # Get metadata for a specific metric gcx metrics metadata -d UID --metric http_requests_total # Output as JSON gcx metrics metadata -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) -h, --help help for metadata --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -m, --metric string Filter by metric name -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics query` Execute a PromQL query against a Prometheus datasource. EXPR is the PromQL expression to evaluate, passed as a positional argument or via –expr (familiar to promtool users). Datasource is resolved from -d flag or datasources.prometheus in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Instant query using configured default datasource gcx metrics query 'up{job="grafana"}' # Instant query at a specific time gcx metrics query 'rate(http_requests_total[5m])' --time 2026-01-15T10:30:00Z # Range query with explicit datasource UID gcx metrics query -d abc123 'rate(http_requests_total[5m])' --from now-1h --to now --step 1m # Query the last hour gcx metrics query 'up' --since 1h # Print a Grafana Explore share link for the executed query gcx metrics query 'up' --share-link # Output as JSON gcx metrics query -d abc123 'up' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --time string Evaluation time for an instant query (RFC3339, Unix timestamp, or relative like 'now-5m'). Mutually exclusive with --from/--to/--since --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics search` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Search for metric names, label names or label values via the experimental search API. This API is experimental and disabled by default on both self-hosted Prometheus (requires –enable-feature=search-api) and self-hosted Mimir (requires -querier.experimental-search-api-enabled). **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for search ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics search label-names` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Search label names from a Prometheus/Mimir datasource. Requires TERM (performs a fuzzy search; multiple TERM values combine as OR), or a scope instead: –metric, –metric-regex or –match. sort\_by=score (the default) requires a search term — omitting TERM in favor of a scope falls back to sort\_by=alpha, and an explicit –sort-by=score without TERM is rejected. –metric-regex is used exactly as given — PromQL anchors =~ at ^…$, so “kube” matches only a metric literally named “kube”, not one containing it. Write “.*kube.*” for a contains search. Without –from/–to or –since, the server searches only the last hour; use –since (for example –since 7d) to look further back. This API is experimental and disabled by default on both self-hosted Prometheus (requires –enable-feature=search-api) and self-hosted Mimir (requires -querier.experimental-search-api-enabled). See also the sibling metric-name search and label-value search commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics search label-names [TERM...] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Fuzzy search label names (configured default datasource) gcx metrics search label-names job # Show label names available on a given metric gcx metrics search label-names --metric http_requests_total # Show label names on series matching a selector gcx metrics search label-names --match '{job="api"}' # Search for label names on a given metric gcx metrics search label-names namespace --metric http_requests_total # Search for label names across a range of metrics gcx metrics search label-names namespace --metric-regex '.*kube.*' # Search label names seen in the last 7 days (default: the last hour) gcx metrics search label-names job --since 7d # Output as JSON gcx metrics search label-names job -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --case-sensitive Case-sensitive search term matching (case-insensitive by default) -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --fuzz-alg string Fuzzy match algorithm: jarowinkler or subsequence (default "jarowinkler") --fuzz-threshold int Minimum fuzzy match score as a percentage, 0-100; scores are reported from 0 to 1. With jarowinkler the threshold applies only to fuzzy matches: substring matches are always kept, and 0 turns fuzzy matching off (default 70) -h, --help help for label-names --include-score Include each result's relevance score (0 to 1; higher is a closer match) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum results to return (0: unlimited on Mimir, subject to server-side caps; Prometheus requires a positive value) (default 50) --match stringArray PromQL series selector(s) restricting candidates; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) --metric string Only results from series of this metric name; mutually exclusive with --metric-regex --metric-regex string Only results from series whose metric name matches this regex. Used exactly as given. To match all metric names which contain "kube" use ".*kube.*". Mutually exclusive with --metric. -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --sort-by string Sort by: score (requires a search term) or alpha (default "score") --sort-dir string Sort direction for --sort-by alpha: asc (default) or dsc --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics search label-values` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Search the values of a single label from a Prometheus/Mimir datasource. LABEL is always required; TERM (multiple values combine as OR), –metric, –metric-regex and –match are all optional and may be combined or omitted — LABEL alone lists that label’s values. sort\_by=score (the default) requires a search term — omitting TERM falls back to sort\_by=alpha, and an explicit –sort-by=score without TERM is rejected. –metric-regex is used exactly as given — PromQL anchors =~ at ^…$, so “kube” matches only a metric literally named “kube”, not one containing it. Write “.*kube.*” for a contains search. Without –from/–to or –since, the server searches only the last hour; use –since (for example –since 7d) to look further back. This API is experimental and disabled by default on both self-hosted Prometheus (requires –enable-feature=search-api) and self-hosted Mimir (requires -querier.experimental-search-api-enabled). See also the sibling metric-name search and label-name search commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics search label-values LABEL [TERM...] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List values of the "job" label (configured default datasource) gcx metrics search label-values job # Fuzzy search values of the "job" label gcx metrics search label-values job pro # List "job" label values present on a specific metric gcx metrics search label-values job --metric http_requests_total # List "job" label values present on a range of metrics gcx metrics search label-values job --metric-regex '.*kube.*' # List "job" label values seen in the last 7 days (default: the last hour) gcx metrics search label-values job --since 7d # Output as JSON gcx metrics search label-values job pro -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --case-sensitive Case-sensitive search term matching (case-insensitive by default) -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --fuzz-alg string Fuzzy match algorithm: jarowinkler or subsequence (default "jarowinkler") --fuzz-threshold int Minimum fuzzy match score as a percentage, 0-100; scores are reported from 0 to 1. With jarowinkler the threshold applies only to fuzzy matches: substring matches are always kept, and 0 turns fuzzy matching off (default 70) -h, --help help for label-values --include-score Include each result's relevance score (0 to 1; higher is a closer match) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum results to return (0: unlimited on Mimir, subject to server-side caps; Prometheus requires a positive value) (default 50) --match stringArray PromQL series selector(s) restricting candidates; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) --metric string Only results from series of this metric name; mutually exclusive with --metric-regex --metric-regex string Only results from series whose metric name matches this regex. Used exactly as given. To match all metric names which contain "kube" use ".*kube.*". Mutually exclusive with --metric. -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --sort-by string Sort by: score (requires a search term) or alpha (default "score") --sort-dir string Sort direction for --sort-by alpha: asc (default) or dsc --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics search metric-names` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Search metric names from a Prometheus/Mimir datasource. At least one TERM is required. This API allows for metric names to be discovered via a configurable fuzzy search. Multiple TERM values combine as OR. Search terms can be augmented with matchers for additional filtering of considered series. Without –from/–to or –since, the server searches only the last hour; use –since (for example –since 7d) to look further back. This API is experimental and disabled by default on both self-hosted Prometheus (requires –enable-feature=search-api) and self-hosted Mimir (requires -querier.experimental-search-api-enabled). See also the sibling label-name search and label-value search commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics search metric-names TERM... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Fuzzy search metric names (configured default datasource) gcx metrics search metric-names http # Search metric names seen in the last 7 days (default: the last hour) gcx metrics search metric-names http --since 7d # Refine fuzzy search algorithm gcx metrics search metric-names http --fuzz-alg=subsequence --fuzz-threshold=85 # Limit result sets and control ordering gcx metrics search metric-names http --limit=10 --sort-by=alpha # Include relevance score and metric metadata gcx metrics search metric-names http --include-score --include-metadata # Output as JSON gcx metrics search metric-names http -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --case-sensitive Case-sensitive search term matching (case-insensitive by default) -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --fuzz-alg string Fuzzy match algorithm: jarowinkler or subsequence (default "jarowinkler") --fuzz-threshold int Minimum fuzzy match score as a percentage, 0-100; scores are reported from 0 to 1. With jarowinkler the threshold applies only to fuzzy matches: substring matches are always kept, and 0 turns fuzzy matching off (default 70) -h, --help help for metric-names --include-metadata Include each result's metric type, help text, and unit (when available) --include-score Include each result's relevance score (0 to 1; higher is a closer match) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum results to return (0: unlimited on Mimir, subject to server-side caps; Prometheus requires a positive value) (default 50) --match stringArray PromQL series selector(s) restricting candidates; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --sort-by string Sort by: score (requires a search term) or alpha (default "score") --sort-dir string Sort direction for --sort-by alpha: asc (default) or dsc --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics series` List time series matching one or more selectors via the Prometheus /api/v1/series endpoint. A selector can be passed as a positional argument and/or via –match (repeatable). Time range defaults to unbounded; pass –since, or –from/–to, to scope. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics series [SELECTOR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Match a single metric family gcx metrics series -d '{__name__="up"}' # Match multiple selectors scoped to the last hour gcx metrics series -d --match '{job="grafana"}' --match '{job="loki"}' --since 1h # Output as JSON gcx metrics series -d '{__name__=~"grafanacloud_.*"}' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for series --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --match stringArray Additional series selector(s); repeatable -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles` Query Pyroscope datasources and manage continuous profiling **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for profiles ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles adaptive` Manage Adaptive Profiles (not yet available) shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles adaptive [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for adaptive ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles data-range` Show the range of profiling data a Pyroscope datasource holds: whether any data was ever ingested, and the oldest and newest profile times. The range covers everything behind the datasource (the whole tenant), not any particular service or label selector. Use this to disambiguate empty query results: if no data was ever ingested, fix ingestion before adjusting selectors; otherwise the oldest/newest bounds show the currently queryable window. Note that data-ingested is a lifetime flag: it stays true even after all data has aged out of the retention period (31 days by default, tenant-configurable), in which case the bounds render as ‘-’ (0 in JSON). Older backends may also report an unknown oldest bound the same way. If gcx auto-discovers the datasource from your Grafana Cloud stack, the discovered datasource UID may be saved to your gcx configuration for future commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles data-range [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Check whether the datasource holds profiling data, and for what range gcx profiles data-range -d UID # Output as JSON (times are milliseconds since epoch) gcx profiles data-range -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) -h, --help help for data-range --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles exemplars` Query profile or span exemplars from a Pyroscope datasource. Exemplars link profile data to concrete samples or trace spans, enabling a pivot from “which service was slow” to “which exact profile” (profile exemplars) or “which trace span” (span exemplars). **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Top individual profile exemplars (Profile ID + Span ID if span-aware) gcx profiles exemplars profile '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # Top span exemplars (profiles linked to trace spans; needs otelpyroscope) gcx profiles exemplars span '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # Output as JSON for scripting gcx profiles exemplars profile '{}' --since 30m -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for exemplars ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles exemplars profile` List individual profile exemplars by calling SelectSeries with EXEMPLAR\_TYPE\_INDIVIDUAL. Each row is a concrete profile sample identified by Profile ID. When profiles are span-aware (e.g. via otelpyroscope), a Span ID column is included linking to the associated trace span. EXPR is the label selector (e.g. ‘{service\_name=“frontend”}’). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles exemplars profile [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Top profile exemplars in the last hour gcx datasources pyroscope exemplars profile '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # JSON output gcx datasources pyroscope exemplars profile '{}' --since 30m -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --expr string Label selector (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for profile --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-label-columns int Max label columns in table output (0 hides label columns) (default 3) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --profile-type string Profile type ID (default "process_cpu:cpu:nanoseconds:cpu:nanoseconds") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') --top-n int Maximum number of exemplars to return (default 100) ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles exemplars span` List span exemplars by calling SelectHeatmap with HEATMAP\_QUERY\_TYPE\_SPAN. Each row is a span-linked profile sample identified by Span ID. When supplied by the server, Trace ID is also included for direct correlation with Tempo. Requires span-aware instrumentation upstream (e.g. otelpyroscope); without it the query returns an empty list. EXPR is the label selector (e.g. ‘{service\_name=“frontend”}’). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles exemplars span [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Top span exemplars in the last hour gcx datasources pyroscope exemplars span '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # JSON output, more label context gcx datasources pyroscope exemplars span '{}' --since 30m --max-label-columns 5 -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --expr string Label selector (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for span --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-label-columns int Max label columns in table output (0 hides label columns) (default 3) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --profile-type string Profile type ID (default "process_cpu:cpu:nanoseconds:cpu:nanoseconds") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') --top-n int Maximum number of exemplars to return (default 100) ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles labels` List all labels or get values for a specific label from a Pyroscope datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all labels (use datasource UID, not name) gcx profiles labels -d UID # Get values for a specific label gcx profiles labels -d UID --label service_name # Output as JSON gcx profiles labels -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label string Get values for this label (omit to list all labels) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles list-profile-types` List available profile types from a Pyroscope datasource. If gcx auto-discovers the datasource from your Grafana Cloud stack, the discovered datasource UID may be saved to your gcx configuration for future commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles list-profile-types [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List profile types (use datasource UID, not name) gcx profiles list-profile-types -d UID # Output as JSON gcx profiles list-profile-types -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for list-profile-types --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles metrics` Query profile time-series data via SelectSeries from a Pyroscope datasource. Shows how a profile metric (e.g., CPU, memory) changes over time. Useful for identifying performance regressions and trends before diving into flamegraphs. Use –top to aggregate the time range into a ranked leaderboard of the heaviest consumers (equivalent to profilecli query top). Without –top, returns raw time-series data points for trend analysis. EXPR is the label selector (e.g., ‘{service\_name=“frontend”}’). Datasource is resolved from -d flag or datasources.pyroscope in your context. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles metrics [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Top services by CPU usage (ranked leaderboard) gcx profiles metrics '{}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h --top # CPU usage over the last hour with 1-minute resolution gcx profiles metrics -d pyro-001 '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h --step 1m # Output as JSON gcx profiles metrics -d abc123 '{}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h --top -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --aggregation string Aggregation type: 'sum' or 'average' -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --group-by strings Group series by label (repeatable, defaults to service_name) -h, --help help for metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of series to return (default 10) -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --profile-type string Profile type ID (e.g., 'process_cpu:cpu:nanoseconds:cpu:nanoseconds') (required) --since string Duration before --to (or now if omitted); mutually exclusive with --from --step string Query step (e.g., '15s', '1m'); defaults to the Pyroscope datasource minStep (or 15s) when omitted --to string End time (RFC3339, Unix timestamp, or relative like 'now') --top Aggregate into a ranked leaderboard (equivalent to profilecli query top) ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles query` Execute a profiling query against a Pyroscope datasource. EXPR is the label selector (e.g., ‘{service\_name=“frontend”}’). Datasource is resolved from -d flag or datasources.pyroscope in your context. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Profile query with explicit datasource UID gcx profiles query -d abc123 '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # Using configured default datasource gcx profiles query '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # Output as JSON gcx profiles query -d abc123 '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds -o json # Drill into one or more specific profiles found via 'gcx profiles exemplars' # (--profile-id is repeatable; pass it once per UUID) gcx profiles query '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h \ --profile-id 550e8400-e29b-41d4-a716-446655440000 \ --profile-id 7c9e6679-7425-40de-944b-e07fc1f90ae7 # Restrict the query to one or more trace spans gcx profiles query '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h \ --span-id 00f067aa0ba902b7 # Restrict the query to samples from one or more traces gcx profiles query '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h \ --trace-id 4bf92f3577b34da6a3ce929d0e0e4736 # Restrict the flamegraph to stacks rooted at a specific call site # (--stacktrace-selector is repeatable; pass it once per frame, root first) gcx profiles query '{service_name="my-go-service"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h \ --stacktrace-selector 'github.com/prometheus/client_golang/prometheus.(*Registry).Gather.func1' # Caller-callee call graph as Graphviz DOT text — the most readable format # for LLM analysis (requires a pure-v2 backend; others fall back to table). # Dotted edges mean frames were elided by the 100-node default; raise # --max-nodes for fuller call chains gcx profiles query '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h -o dot ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-nodes int Maximum nodes in the result (defaults: pprof 0/unlimited, dot 100-node call graph rendered server-side, 50000 for all other formats) -o, --output string Output format. One of: agents, dot, graph, json, pprof, table, wide, yaml (default "table") --pprof-overwrite Overwrite the output file if it already exists (only with -o pprof) --pprof-path string Destination path for pprof binary output (only with -o pprof; default: profile-YYYY-MM-DD-HHMMSS.pb.gz) --profile-id strings Drill down to specific profile UUIDs from exemplar queries (repeatable) --profile-type string Profile type ID (e.g., 'process_cpu:cpu:nanoseconds:cpu:nanoseconds'); use 'gcx profiles list-profile-types' to list available (required) --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --span-id strings Only query profiles with these 16-character hex span IDs (repeatable; unavailable with -o pprof and -o dot) --stacktrace-selector strings Only query locations with these function names, starting from the root (repeatable) --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') --trace-id strings Only query samples with these 32-character hex trace IDs (repeatable) ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles query-anomalies` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Query profiles flagged as anomalies by an external anomaly source and confirmed present in ingested data for the given label selector and time range. Requires the datasource’s query-frontend to have an anomaly source configured (query-frontend.anomaly-api.url); returns FAILED\_PRECONDITION otherwise. EXPR is the label selector (e.g. ‘{service\_name=“frontend”}’). It may resolve to more than one service\_name; anomalies from every matching service are queried and confirmed in one call. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles query-anomalies [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Anomalies for a service in the last hour gcx profiles query-anomalies -d abc123 '{service_name="frontend"}' --since 1h # Every service in a namespace (selector may resolve to multiple services) gcx profiles query-anomalies -d abc123 '{namespace="prod"}' --since 1h # Output as JSON gcx profiles query-anomalies -d abc123 '{service_name="frontend"}' --since 1h -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --anomaly-type strings Anomaly source(s) to query. Only 'stacktrace' is supported today. Repeatable (default [stacktrace]) -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --expr string Label selector (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query-anomalies --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-label-columns int Max label columns in table output (0 hides label columns) (default 3) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --profile-type string Profile type ID (default "process_cpu:cpu:nanoseconds:cpu:nanoseconds") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') --top-n int Maximum number of anomalies to return (default 100) ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles series` List unique profile label sets from a Pyroscope datasource. The command uses Pyroscope’s Series endpoint and does not require a profile type. SELECTOR is optional; use –match for repeatable selectors. Multiple selectors are combined as a union. By default, the response includes every label. Use –label-name to request only the labels needed for discovery. This reduces the response size and can significantly speed up queries with high-cardinality labels. For example, use –label-name service\_name –label-name namespace to discover services and namespaces without fetching pod, instance, or custom labels. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles series [SELECTOR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List unique profile label sets without a profile type gcx profiles series -d UID --since 1h # Scope to a service and return selected labels gcx profiles series -d UID '{service_name="frontend"}' \ --label-name service_name --label-name namespace --label-name pod --since 24h ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for series --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --label-name strings Label name to return (repeatable; limit labels to reduce response size and speed up discovery) --match stringArray Profile label selector (repeatable; selectors are combined as a union) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx providers` Manage registered providers **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for providers ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx providers list` List registered providers shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx providers list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx resources` Manipulate Grafana resources. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for resources ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx resources delete` Delete resources from Grafana by selector or from local files. Use –dry-run to preview changes. Named selectors delete without confirmation. Use –force to delete all resources of a given type (–yes also enables –force). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources delete [RESOURCE_SELECTOR]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Delete a single dashboard gcx resources delete dashboards/some-dashboard # Delete multiple dashboards gcx resources delete dashboards/some-dashboard,other-dashboard # Delete a dashboard and a folder gcx resources delete dashboards/some-dashboard folders/some-folder # Delete every dashboard gcx resources delete dashboards --force # Delete every resource defined in the given directory gcx resources delete -p ./unwanted-resources/ # Delete every dashboard defined in the given directory gcx resources delete -p ./unwanted-resources/ dashboard # Delete all dashboards with auto-approval gcx resources delete dashboards --yes # Delete all dashboards using environment variable GCX_AUTO_APPROVE=1 gcx resources delete dashboards # Provider-backed resources (SLO and Synthetic Monitoring): gcx resources delete slo/my-slo-uuid gcx resources delete checks.syntheticmonitoring/my-check-uuid # Native Grafana alert rules: gcx resources delete alertrules/my-rule-uid ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --assume-server-dry-run strings Assert that the given resources honor server-side dry-run, augmenting the built-in allowlist. Repeatable or comma-separated, each value a GroupResource string (.), e.g. alertrules.rules.alerting.grafana.app --dry-run If set, the delete operation will be simulated --force Delete all resources of the specified resource types -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-concurrent int Maximum number of concurrent operations (default 10) --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 4 (partial failure) if any failed (default) abort — stop on the first error and exit non-zero (default "fail") -o, --output string Output format. One of: agents, json, text, yaml (default "text") -p, --path strings Path on disk containing the resources to delete -y, --yes Auto-approve destructive operations (automatically enables --force) ``` Inherits `--config`, `--context` from [`gcx resources`](#gcx-resources-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx resources edit` Edit resources from Grafana using the default editor. This command allows the edition of any resource that can be accessed by this CLI tool. It will open the default editor as configured by the EDITOR environment variable, or fall back to ‘vi’ for Linux or ’notepad’ for Windows. The editor will be started in the shell set by the SHELL environment variable. If undefined, ‘/bin/bash’ is used for Linux or ‘cmd’ for Windows. The edition will be cancelled if no changes are written to the file or if the file after edition is empty. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources edit RESOURCE_SELECTOR [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Edit a dashboard gcx resources edit dashboard/foo # Edit a dashboard in JSON gcx resources edit -o json dashboard/foo # Using an alternative editor EDITOR=nvim gcx resources edit dashboard/foo ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for edit -o, --output string Output format. One of: json, yaml (default "json") ``` Inherits `--config`, `--context` from [`gcx resources`](#gcx-resources-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx resources get` Get resources from Grafana using a specific format. See examples below for more details. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources get [RESOURCE_SELECTOR]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Everything: gcx resources get dashboards/foo # All instances for a given kind(s): gcx resources get dashboards gcx resources get dashboards folders # Single resource kind, one or more resource instances: gcx resources get dashboards/foo gcx resources get dashboards/foo,bar # Single resource kind, full API group: gcx resources get dashboards.dashboard.grafana.app/foo gcx resources get dashboards.dashboard.grafana.app/foo,bar # Single resource kind, long kind format with version: gcx resources get dashboards.v1alpha1.dashboard.grafana.app/foo gcx resources get dashboards.v1alpha1.dashboard.grafana.app/foo,bar # Multiple resource kinds, one or more resource instances: gcx resources get dashboards/foo folders/qux gcx resources get dashboards/foo,bar folders/qux,quux # Multiple resource kinds, full API groups: gcx resources get dashboards.dashboard.grafana.app/foo folders.folder.grafana.app/qux gcx resources get dashboards.dashboard.grafana.app/foo,bar folders.folder.grafana.app/qux,quux # Multiple resource kinds, long kind format with version: gcx resources get dashboards.v1alpha1.dashboard.grafana.app/foo folders.v1alpha1.folder.grafana.app/qux # Provider-backed resources (SLO and Synthetic Monitoring): gcx resources get slo gcx resources get slo/my-slo-uuid gcx resources get checks.syntheticmonitoring # Native Grafana alert rules: gcx resources get alertrules # Discover available JSON fields for a resource type: gcx resources get dashboards --json list # Select specific fields (no external parsing needed): gcx resources get dashboards --json metadata.name,spec.title ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to fetch per resource type (0 for all) (default 50) --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 4 (partial failure) if any failed (default) abort — stop on the first error and exit non-zero (default "fail") --open Open the resource in the default browser -o, --output string Output format. One of: agents, json, text, wide, yaml (default "text") ``` Inherits `--config`, `--context` from [`gcx resources`](#gcx-resources-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx resources list-examples` List example manifests for provider-backed resource types. Without arguments, lists all resources that have examples. With a selector, shows examples for matching resources. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources list-examples [RESOURCE_SELECTOR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources list-examples gcx resources list-examples -o wide gcx resources list-examples -o json gcx resources list-examples -o yaml gcx resources list-examples incidents gcx resources list-examples incidents -o json gcx resources list-examples slo -o yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-examples --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, wide, yaml (default "text") ``` Inherits `--config`, `--context` from [`gcx resources`](#gcx-resources-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx resources list-types` List available Grafana API resource types and their schemas by querying a live Grafana instance. Requires a connection to Grafana. Use –no-schema to skip OpenAPI spec fetching for faster results. Optionally filter by a resource selector. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources list-types [RESOURCE_SELECTOR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources list-types gcx resources list-types -o wide gcx resources list-types -o json gcx resources list-types -o yaml gcx resources list-types -o json --no-schema gcx resources list-types incidents gcx resources list-types incidents.v1alpha1.incident.ext.grafana.app -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-types --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --no-schema Skip fetching OpenAPI spec schemas (faster, omits schema info and unlistable resource types) -o, --output string Output format. One of: agents, json, text, wide, yaml (default "text") ``` Inherits `--config`, `--context` from [`gcx resources`](#gcx-resources-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx resources pull` Pull resources from Grafana using a specific format. See examples below for more details. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources pull [RESOURCE_SELECTOR]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Everything: gcx resources pull # All instances for a given kind(s): gcx resources pull dashboards gcx resources pull dashboards folders # Single resource kind, one or more resource instances: gcx resources pull dashboards/foo gcx resources pull dashboards/foo,bar # Single resource kind, full API group: gcx resources pull dashboards.dashboard.grafana.app/foo gcx resources pull dashboards.dashboard.grafana.app/foo,bar # Single resource kind, long kind format with version: gcx resources pull dashboards.v1alpha1.dashboard.grafana.app/foo gcx resources pull dashboards.v1alpha1.dashboard.grafana.app/foo,bar # Multiple resource kinds, one or more resource instances: gcx resources pull dashboards/foo folders/qux gcx resources pull dashboards/foo,bar folders/qux,quux # Multiple resource kinds, full API groups: gcx resources pull dashboards.dashboard.grafana.app/foo folders.folder.grafana.app/qux gcx resources pull dashboards.dashboard.grafana.app/foo,bar folders.folder.grafana.app/qux,quux # Multiple resource kinds, long kind format with version: gcx resources pull dashboards.v1alpha1.dashboard.grafana.app/foo folders.v1alpha1.folder.grafana.app/qux # Provider-backed resources (SLO and Synthetic Monitoring): gcx resources pull slo -p ./slo-defs/ gcx resources pull checks.syntheticmonitoring -p ./checks/ # Native Grafana alert rules: gcx resources pull alertrules -p ./alertrules/ ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for pull --include-managed Include resources managed by tools other than gcx --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 4 (partial failure) if any failed (default) abort — stop on the first error and exit non-zero (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") ``` Inherits `--config`, `--context` from [`gcx resources`](#gcx-resources-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx resources push` Push resources to Grafana using a specific format. See examples below for more details. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources push [RESOURCE_SELECTOR]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Everything: gcx resources push # All instances for a given kind(s): gcx resources push dashboards gcx resources push dashboards folders # Single resource kind, one or more resource instances: gcx resources push dashboards/foo gcx resources push dashboards/foo,bar # Single resource kind, full API group: gcx resources push dashboards.dashboard.grafana.app/foo gcx resources push dashboards.dashboard.grafana.app/foo,bar # Single resource kind, long kind format with version: gcx resources push dashboards.v1alpha1.dashboard.grafana.app/foo gcx resources push dashboards.v1alpha1.dashboard.grafana.app/foo,bar # Multiple resource kinds, one or more resource instances: gcx resources push dashboards/foo folders/qux gcx resources push dashboards/foo,bar folders/qux,quux # Multiple resource kinds, full API groups: gcx resources push dashboards.dashboard.grafana.app/foo folders.folder.grafana.app/qux gcx resources push dashboards.dashboard.grafana.app/foo,bar folders.folder.grafana.app/qux,quux # Multiple resource kinds, long kind format with version: gcx resources push dashboards.v1alpha1.dashboard.grafana.app/foo folders.v1alpha1.folder.grafana.app/qux # Provider-backed resources (SLO and Synthetic Monitoring): gcx resources push slo -p ./slo-defs/ gcx resources push checks.syntheticmonitoring -p ./checks/ # Native Grafana alert rules: gcx resources push alertrules -p ./alertrules/ # Mixed push: native and provider resources from the same directory # (types auto-detected from apiVersion/kind in YAML files): gcx resources push -p ./resources/ ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --assume-server-dry-run strings Assert that the given resources honor server-side dry-run, augmenting the built-in allowlist. Repeatable or comma-separated, each value a GroupResource string (.), e.g. alertrules.rules.alerting.grafana.app --dry-run If set, the push operation will be simulated, without actually creating or updating any resources -h, --help help for push --include-managed If set, resources managed by other tools will be included in the push operation --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-concurrent int Maximum number of concurrent operations (default 10) --omit-manager-fields If set, the manager fields will not be appended to the resources --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 4 (partial failure) if any failed (default) abort — stop on the first error and exit non-zero (default "fail") -o, --output string Output format. One of: agents, json, text, yaml (default "text") -p, --path strings Paths on disk from which to read the resources to push (default [./resources]) ``` Inherits `--config`, `--context` from [`gcx resources`](#gcx-resources-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx resources validate` Validate local resource files against a remote Grafana instance. Requires a live connection to Grafana for server-side validation. Reads resources from disk and reports validation errors per resource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources validate [RESOURCE_SELECTOR]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Validate all resources in the default directory gcx resources validate # Validate a single resource kind gcx resources validate dashboards # Validate a multiple resource kinds gcx resources validate dashboards folders # Displaying validation results as YAML gcx resources validate -o yaml # Displaying validation results as JSON gcx resources validate -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --assume-server-dry-run strings Assert that the given resources honor server-side dry-run, augmenting the built-in allowlist. Repeatable or comma-separated, each value a GroupResource string (.), e.g. alertrules.rules.alerting.grafana.app -h, --help help for validate --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-concurrent int Maximum number of concurrent operations (default 10) --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 4 (partial failure) if any failed (default) abort — stop on the first error and exit non-zero (default "fail") -o, --output string Output format. One of: agents, json, text, yaml (default "text") -p, --path strings Paths on disk from which to read the resources. (default [./resources]) ``` Inherits `--config`, `--context` from [`gcx resources`](#gcx-resources-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx setup` Onboard and configure Grafana Cloud products. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for setup ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx setup status` Show aggregated setup status across all products. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx setup status [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for status --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx setup`](#gcx-setup-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx signup` Create a free Grafana Cloud account in the browser and connect gcx to the account’s first stack. gcx opens the Grafana Cloud sign-up page and waits. In the browser, create the account, verify your email (the emailed link may open a new tab), create your first stack, and approve “Connect gcx”. The browser then returns to gcx, which saves the connection. No stack URL or token is needed. If the browser asks you to choose a stack instead of creating an account, it is already signed in to Grafana Cloud: choose one and approve “Connect gcx”. If the browser loses the page, press Enter in a local terminal to open it again, or open the printed URL. The connection is saved to CONTEXT\_NAME. Without it, gcx uses the current context, or a context named “default” when none is set. signup only ever saves a new connection: it refuses, before the browser opens, a context that already has a stack or Grafana Cloud entry, or a name that an existing stack entry uses. Pass an unused CONTEXT\_NAME instead. For an account you already have, run gcx login. A person completes the browser steps. In agent mode gcx prints the URL instead of opening the browser, and asks no questions. signup does not save Grafana Cloud management credentials. To manage Grafana Cloud products (SLOs, Synthetic Monitoring, k6 and more), save a Cloud Access Policy token afterwards with gcx cloud login –cloud-token . If signup fails once the browser step has started, the error shows the gcx login command that finishes the connection; do not run signup again, which could start a second account. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx signup [CONTEXT_NAME] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx signup gcx signup my-stack gcx signup --oauth-manual ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use -h, --help help for signup --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --oauth-callback-port int Fixed local port for the OAuth callback server (default: auto-pick from 54321-54399). Useful when only specific ports are forwarded between a remote host and your browser --oauth-manual Complete browser OAuth without a local callback server: gcx prints the URL, then reads the redirect URL that you copy from the browser address bar. Use this when gcx runs on a remote host and the browser runs on your own computer -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo` Manage Grafana SLO definitions and reports **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for slo ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo definitions` Manage SLO definitions. Freeform queries must use $\_\_rate\_interval in every rate() and increase() range. Literal ranges such as \[5m] are rejected by the SLO API. **Aliases:** `def`, `defs` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for definitions ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo definitions delete` Delete SLO definitions. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo definitions delete UUID... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo definitions get` Get a single SLO definition. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo definitions get UUID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo definitions list` List SLO definitions. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo definitions list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return after fetch (0 for all; use a positive value to trim output only) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo definitions pull` Pull SLO definitions to disk. Deprecated: use gcx resources pull slos.v1alpha1.slo.ext.grafana.app -p PATH -o yaml instead. This compatibility command retains its Kind/name.yaml layout. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo definitions pull [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for pull -d, --output-dir string Directory to write SLO definitions to (default ".") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo definitions push` Push SLO from files. Deprecated: use gcx resources push slos.v1alpha1.slo.ext.grafana.app -p PATH instead. Writes update only an existing metadata.name UUID; an absent or unknown UUID creates a new resource. Manifests may omit apiVersion and kind; this command supplies its resource type. This compatibility command retains its file-at-a-time results and local-only –dry-run preview. The preview shows manifest identities only; it does not resolve the remote UUID or determine create versus update. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo definitions push FILE... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dry-run Preview changes without making them -h, --help help for push --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo definitions status` Show SLO definitions status by combining the SLO API with Prometheus metrics. Displays current SLI, error budget, and health status for each SLO definition. Requires that the SLO destination datasource has recording rules generating grafana\_slo\_* metrics. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo definitions status [UUID] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Show status of all SLO definitions. gcx slo definitions status # Show status of a specific SLO by UUID. gcx slo definitions status abc123def # Show extended status with 1h/1d SLI columns. gcx slo definitions status -o wide # Output status as JSON for scripting. gcx slo definitions status -o json # Render a compliance summary bar chart. gcx slo definitions status -o graph ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for status --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo definitions timeline` Render SLI values over time as a line chart by executing a range query against the Prometheus datasource associated with each SLO. Requires that the SLO destination datasource has recording rules generating grafana\_slo\_sli\_window metrics. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo definitions timeline [UUID] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Render SLI trend for all SLOs over the past 7 days. gcx slo definitions timeline # Render SLI trend for a specific SLO. gcx slo definitions timeline abc123def # Custom time range with explicit step. gcx slo definitions timeline --from now-24h --to now --step 5m # Use duration shorthand for the past 24 hours. gcx slo definitions timeline --since 24h # Output timeline data as a table. gcx slo definitions timeline -o table ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start of the time range (e.g. now-7d, now-24h, RFC3339, Unix timestamp) (default "now-7d") -h, --help help for timeline --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, graph, json, table, yaml (default "graph") --since string Duration before now (e.g. 1h, 7d). Equivalent to --from now- --to now. --step string Query step (e.g. 5m, 1h). Defaults to auto-computed value. --to string End of the time range (e.g. now, RFC3339, Unix timestamp) (default "now") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo reports` Manage SLO reports. **Aliases:** `report` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for reports ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo reports delete` Delete SLO reports. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo reports delete UUID... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo reports get` Get a single SLO report. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo reports get UUID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo reports list` List SLO reports. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo reports list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo reports pull` Pull SLO reports to disk. Deprecated: use gcx resources pull reports.v1alpha1.slo.ext.grafana.app -p PATH -o yaml instead. This compatibility command retains its Kind/name.yaml layout. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo reports pull [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for pull -d, --output-dir string Directory to write SLO reports to (default ".") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo reports push` Push report from files. Deprecated: use gcx resources push reports.v1alpha1.slo.ext.grafana.app -p PATH instead. Writes update only an existing metadata.name UUID; an absent or unknown UUID creates a new resource. Manifests may omit apiVersion and kind; this command supplies its resource type. This compatibility command retains its file-at-a-time results and local-only –dry-run preview. The preview shows manifest identities only; it does not resolve the remote UUID or determine create versus update. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo reports push FILE... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dry-run Preview changes without making them -h, --help help for push --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo reports status` Show SLO report status by aggregating health data across all SLOs in each report. Fetches report definitions, resolves referenced SLO UUIDs, queries Prometheus metrics, and computes combined SLI and error budget per report. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo reports status [UUID] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Show status of all SLO reports. gcx slo reports status # Show status of a specific report by UUID. gcx slo reports status abc123def # Show extended status with per-SLO breakdown. gcx slo reports status -o wide # Output status as JSON for scripting. gcx slo reports status -o json # Render a combined SLI bar chart. gcx slo reports status -o graph ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for status --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo reports timeline` Render SLI values over time as line charts for each SLO report by executing range queries against the Prometheus datasource associated with each constituent SLO. Requires that SLO destination datasources have recording rules generating grafana\_slo\_sli\_window metrics. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo reports timeline [UUID] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Render SLI trend for all SLO reports over the past 7 days. gcx slo reports timeline # Render SLI trend for a specific report. gcx slo reports timeline abc123def # Custom time range with explicit step. gcx slo reports timeline --from now-24h --to now --step 5m # Use duration shorthand for the past 24 hours. gcx slo reports timeline --since 24h # Output timeline data as a table. gcx slo reports timeline -o table ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start of the time range (e.g. now-7d, now-24h, RFC3339, Unix timestamp) (default "now-7d") -h, --help help for timeline --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, graph, json, table, yaml (default "graph") --since string Duration before now (e.g. 1h, 7d). Equivalent to --from now- --to now. --step string Query step (e.g. 5m, 1h). Defaults to auto-computed value. --to string End of the time range (e.g. now, RFC3339, Unix timestamp) (default "now") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring` Manage Grafana Synthetic Monitoring checks and probes **Aliases:** `sm`, `synth` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for synthetic-monitoring ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring checks` Manage Synthetic Monitoring checks. **Aliases:** `check` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for checks ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring checks create` Create a Synthetic Monitoring check from a file. Note: checks incur Grafana Cloud usage — each test execution is billed, and check results are stored as metrics and logs, which count toward your metrics and logs usage. See [https://grafana.com/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/synthetic-monitoring-invoice.md](/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/synthetic-monitoring-invoice.md). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring checks create [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Create a check from a YAML file. gcx synthetic-monitoring checks create -f check.yaml # Create and show resulting status. gcx synthetic-monitoring checks create -f check.yaml --show-status # Validate HTTP target before creating. gcx synthetic-monitoring checks create -f check.yaml --validate-targets # Validate with the Synthetic Monitoring API without creating anything. gcx synthetic-monitoring checks create -f check.yaml --dry-run ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dry-run Validate the check with the Synthetic Monitoring API without creating it -f, --filename string File containing the check manifest (YAML) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --show-status Query and display check status after creation --validate-targets Pre-flight HTTP HEAD request for HTTP check targets (warning only) ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring checks delete` Delete Synthetic Monitoring checks. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring checks delete NAME... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring checks get` Get a single Synthetic Monitoring check. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring checks get NAME [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Get check by resource name (from 'gcx synthetic-monitoring checks list'). gcx synthetic-monitoring checks get grafana-instance-health-5594 # Get check by numeric ID. gcx synthetic-monitoring checks get 5594 # Get check with current execution status. gcx synthetic-monitoring checks get grafana-instance-health-5594 --show-status # Get a scripted/browser check with a readable script, ready to edit and 'checks update'. gcx synthetic-monitoring checks get grafana-instance-health-5594 --decode-script -o yaml > check.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --decode-script Decode a scripted/browser check's base64 script to plaintext (yaml/json output only, for editing and 'checks update') -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --show-status Query and display the check's current execution status from Prometheus ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring checks list` List Synthetic Monitoring checks. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring checks list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all checks. gcx synthetic-monitoring checks list # Filter by job glob. gcx synthetic-monitoring checks list --job 'shopk8s-*' # Filter by label. gcx synthetic-monitoring checks list --label env=prod ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --job string Filter by job name glob pattern (e.g. --job 'shopk8s-*') --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --label stringArray Filter by label key=value (repeatable, e.g. --label env=prod) --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring checks status` Show pass/fail status by combining the SM API with Prometheus metrics. Displays current success rate, latency (from probe\_duration\_seconds), number of probes reporting, and health status for each check. Requires a Prometheus datasource containing SM metrics. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring checks status [ID] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Show status of all checks. gcx synthetic-monitoring checks status # Show status of a specific check by ID. gcx synthetic-monitoring checks status 42 # Filter by job name glob. gcx synthetic-monitoring checks status --job 'shopk8s-*' # Filter by label and status. gcx synthetic-monitoring checks status --label env=prod --status FAILING # Specify the Prometheus datasource to query. gcx synthetic-monitoring checks status --datasource-uid my-prometheus # Output as JSON for scripting. gcx synthetic-monitoring checks status -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --datasource-uid string UID of the Prometheus datasource to query -h, --help help for status --job string Filter by job name glob pattern (e.g. --job 'shopk8s-*') --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --label stringArray Filter by label key=value (repeatable, e.g. --label env=prod) -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --status string Filter results by status: OK, FAILING, or NODATA ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring checks test` Run a Synthetic Monitoring check once against its probes without persisting it — the check is never saved, and no schedule is created. Results are recovered by polling Loki for the log lines the probes emit for this execution (tagged type=“adhoc”), the same mechanism the Synthetic Monitoring app’s “Test” button uses. Requires a Loki datasource containing SM ad-hoc logs, and read access to it. Note: ad-hoc test executions are billed the same as scheduled check executions. See [https://grafana.com/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/synthetic-monitoring-invoice.md](/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/synthetic-monitoring-invoice.md). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring checks test [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Run a check once from a YAML file. gcx synthetic-monitoring checks test -f check.yaml # Specify the Loki datasource to poll for results. gcx synthetic-monitoring checks test -f check.yaml --logs-datasource-uid my-loki ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the check manifest (YAML) -h, --help help for test --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --logs-datasource-uid string UID of the Loki datasource to poll for ad-hoc results -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring checks timeline` Render probe\_success values over time as a line chart by executing a range query against the Prometheus datasource. Each probe reporting for the check is rendered as a separate series. Requires a Prometheus datasource containing SM metrics. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring checks timeline ID [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Render timeline for a check over the past 6 hours (default). gcx synthetic-monitoring checks timeline 42 # Custom duration. gcx synthetic-monitoring checks timeline 42 --since 24h # Explicit time range. gcx synthetic-monitoring checks timeline 42 --from now-24h --to now # Output timeline data as a table. gcx synthetic-monitoring checks timeline 42 -o table # Specify the Prometheus datasource. gcx synthetic-monitoring checks timeline 42 --datasource-uid my-prometheus ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --datasource-uid string UID of the Prometheus datasource to query --from string Start of the time range (e.g. now-6h, now-24h, RFC3339, Unix timestamp) -h, --help help for timeline --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, graph, json, table, yaml (default "graph") --since string Duration before now to display (e.g. 1h, 6h, 24h, 7d) (default "6h") --to string End of the time range (e.g. now, RFC3339, Unix timestamp) ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring checks update` Update a Synthetic Monitoring check from a file. Note: frequency and probe changes affect billable usage — each test execution is billed, and check results are stored as metrics and logs, which count toward your metrics and logs usage. See [https://grafana.com/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/synthetic-monitoring-invoice.md](/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/synthetic-monitoring-invoice.md). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring checks update [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Update a check using its resource name. gcx synthetic-monitoring checks update web-check-1234 -f check.yaml # Update and show previous status. gcx synthetic-monitoring checks update web-check-1234 -f check.yaml --show-status # Validate the update with the Synthetic Monitoring API without applying it. gcx synthetic-monitoring checks update web-check-1234 -f check.yaml --dry-run ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dry-run Validate the check with the Synthetic Monitoring API without updating it -f, --filename string File containing the check manifest (YAML) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --show-status Query and display the previous check status after update --validate-targets Pre-flight HTTP HEAD request for HTTP check targets (warning only) ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring probes` Manage Synthetic Monitoring probes. **Aliases:** `probe` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for probes ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring probes create` Create a Synthetic Monitoring probe. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring probes create [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Create a probe with a name and region. gcx synthetic-monitoring probes create --name my-probe --region eu # Create a probe with labels and coordinates. gcx synthetic-monitoring probes create --name my-probe --region us --labels env=prod,team=sre --latitude 37.7749 --longitude -122.4194 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --labels strings Labels in key=value format --latitude float Probe latitude --longitude float Probe longitude --name string Probe name (required) -o, --output string Output format. One of: agents, json, text, yaml (default "text") --region string Probe region ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring probes delete` Delete Synthetic Monitoring probes. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring probes delete ID... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring probes deploy` Generate a Namespace, Secret, and Deployment for a private Synthetic Monitoring probe. The Deployment reads the probe token from the Secret and sends it to the agent through a protected environment variable. The output contains the Secret, so store saved output securely. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring probes deploy [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Read the probe token from a file. gcx synthetic-monitoring probes deploy --probe-name my-probe --token-file ./probe-token --api-server-url synthetic-monitoring-grpc.grafana.net:443 # Read the probe token from an environment variable and apply the manifests. gcx synthetic-monitoring probes deploy --probe-name my-probe --token-env PROBE_TOKEN --api-server-url synthetic-monitoring-grpc.grafana.net:443 | kubectl apply -f - # Read the probe token from standard input. printf '%s' "$PROBE_TOKEN" | gcx synthetic-monitoring probes deploy --probe-name my-probe --token-file - --api-server-url synthetic-monitoring-grpc.grafana.net:443 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --api-server-url string SM API gRPC address in host:port format (required) -h, --help help for deploy --image string SM agent container image (default "grafana/synthetic-monitoring-agent:latest") --namespace string Kubernetes namespace (default "synthetic-monitoring") --probe-name string Name for the Kubernetes resources (required) --token-env string Read the probe auth token from this environment variable --token-file string Read the probe auth token from a file (- for standard input) ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring probes list` List Synthetic Monitoring probes. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring probes list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring probes reset-token` Reset the auth token of a Synthetic Monitoring probe. The command returns the new token once. Save the new token and update the probe deployment before you restart the agent. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring probes reset-token ID [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Reset a probe token and show it in the default text output. gcx synthetic-monitoring probes reset-token 123 # Reset a probe token and return a structured result. gcx synthetic-monitoring probes reset-token 123 -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for reset-token --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring queries` Discover Synthetic Monitoring named queries. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for queries ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring queries get` Show one named query’s description and full parameter schema, plus a ready-to-run ‘gcx synthetic-monitoring query’ invocation. Requires Synthetic Monitoring app v1.62.0 or later. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring queries get NAME [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring queries get checks_uptime ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring queries list` List the named queries this tenant’s Synthetic Monitoring datasource publishes. Each entry can be run with ‘gcx synthetic-monitoring query NAME’; use ‘gcx synthetic-monitoring queries get NAME’ for its full parameter schema. Requires Synthetic Monitoring app v1.62.0 or later – named-query discovery is not available on older deployments. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring queries list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring queries list ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring query` Run a query the Synthetic Monitoring backend knows by name. The backend owns the expression and picks the datasource that holds the data, so no PromQL or LogQL is sent or required. Parameters are passed with -p and are validated by the backend, which reports the expression it ran. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring query NAME [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Uptime for a check, as the app computes it gcx synthetic-monitoring query checks_uptime \ -p job=my-check -p instance=https://example.com -p frequency=60000 # Execution rate per probe over the last day gcx synthetic-monitoring query probe_execution_rate \ -p job=my-check -p instance=https://example.com --from now-1d ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start of the time range (default "now-3h") -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") -p, --param stringArray Query parameter as key=value (repeatable), e.g. -p job=my-check --to string End of the time range (default "now") ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces` Query Tempo datasources and manage Adaptive Traces **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for traces ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive` Manage Adaptive Traces resources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for adaptive ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive policies` Manage Adaptive Traces sampling policies. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for policies ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive policies create` Create an Adaptive Traces sampling policy from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces adaptive policies create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the policy definition (use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive policies delete` Delete one or more Adaptive Traces sampling policies. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces adaptive policies delete ... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive policies get` Get an Adaptive Traces sampling policy by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces adaptive policies get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive policies list` List Adaptive Traces sampling policies. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces adaptive policies list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of policies to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive policies update` Update an Adaptive Traces sampling policy by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces adaptive policies update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the policy definition (use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive recommendations` Manage Adaptive Traces recommendations. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for recommendations ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive recommendations apply` Apply an Adaptive Traces recommendation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces adaptive recommendations apply [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dry-run Preview what would be applied without making changes --force Skip confirmation prompt -h, --help help for apply --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive recommendations dismiss` Dismiss an Adaptive Traces recommendation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces adaptive recommendations dismiss [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dry-run Preview what would be dismissed without making changes --force Skip confirmation prompt -h, --help help for dismiss --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive recommendations list` List Adaptive Traces recommendations. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces adaptive recommendations list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces baseline` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Find unranked candidates when you have a seed trace (TRACE\_ID) but need a useful comparison; if you already have both trace IDs, use ‘gcx traces diff’ directly. Retrieval fetches the seed, matches its root service/operation, requires root status != error (including unset), retains downstream errors, and pins up to three busiest downstream services; these heuristics do not prove health or comparable work. Apply verified environment, tenant, or operation constraints with –filter from the first request, then fetch a small batch of plausible candidates with ‘gcx traces get –llm’ when their summaries lack enough context. Use candidate bodies and exploratory diffs to accept or reject controls for the actual symptom, rather than requiring exact workload filters before the first diff or treating the first result as healthy. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces baseline TRACE_ID [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Find a small shortlist; COHORT is an already-verified TraceQL spanset gcx traces baseline --context prod -d UID --filter "$COHORT" --limit 5 # With no additional known scope, use the seed-derived defaults gcx traces baseline --context prod -d UID --limit 5 # Inspect selected candidates; repeat for a small batch, not every result gcx traces get --context prod -d UID --llm -o agents # Assess a candidate with an exploratory diff (seed minus candidate) gcx traces diff --context prod -d UID # Set the candidate window; this does not bound the seed trace lookup gcx traces baseline --context prod -d UID --filter "$COHORT" --limit 5 \ --from 2026-01-15T08:00:00Z --to 2026-01-15T09:00:00Z ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --filter stringArray Raw TraceQL spanset expression to constrain candidates (repeatable; ANDed server-side with the generated query) --from string Absolute start time override (RFC3339, Unix timestamp, or relative like 'now-1h'); requires --to -h, --help help for baseline --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of candidates to return; must be at least 1 (default 20) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --to string Absolute end time override (RFC3339, Unix timestamp, or relative like 'now'); requires --from --window string Search window padding applied before and after the seed trace's time range, so candidates from before or after the seed are eligible (e.g., 30m, 6h, 7d). Ignored when --from/--to are set (default "30m") ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces diff` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Compare two known trace IDs using the Grafana Cloud-only trace-diff API; use ‘gcx traces baseline’ first only when you need candidate IDs. TRACE\_A is the prospective baseline and TRACE\_B is the comparison, with deltas B - A: positive duration means B is slower and negative means faster, not automatically a regression or improvement (a request can fail early). Use candidate bodies and exploratory diffs to assess comparability, rejecting obvious context mismatches first and interpreting timing at the affected request boundary; a diff localizes execution changes but does not establish their cause. Keep the same context/datasource and make –from/–to (or –since) cover both executions; without time bounds the lookup uses the full lookback, and if the endpoint is unavailable, use ‘gcx traces get –llm’ to compare both bodies manually instead. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces diff TRACE_A TRACE_B [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Compare an already-known pair directly; baseline search is not required gcx traces diff --context prod -d UID # Inspect a plausible candidate before using a diff to assess it gcx traces get --context prod -d UID --llm -o agents # Assess selected candidates against the seed; repeat only as useful gcx traces diff --context prod -d UID # Bound BOTH trace lookups, including an older candidate, and allow spilling gcx traces diff --context prod -d UID \ --from 2026-01-15T08:00:00Z --to 2026-01-15T10:00:00Z -o agents ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for diff --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces get` Retrieve a single trace by its trace ID from a Tempo datasource. TRACE\_ID is the hex-encoded trace identifier to retrieve. Datasource is resolved from -d flag or datasources.tempo in your context. Pass –since or –from/–to (e.g. the search’s time range) to make the lookup much faster. Omit them when the time range is unknown; a range that misses the trace returns not found. Use –share-link to print a Grafana Explore URL for the trace, or –open to open it in your browser after retrieval succeeds. Share links require an explicit time range via –since or –from/–to. Experimental: –llm requests the trace in a new LLM-friendly JSON format by sending the “Accept: application/vnd.grafana.llm” header. Datasources that do not support this format return the standard response. Experimental: for large traces, –filter narrows the response to spans matching a TraceQL spanset filter (V2 only). –keep-hierarchy, –match-depth, and –ancestor-depth shape how much context around each match is kept, and are ignored without –filter. Experimental: –prune collapses repeated sibling spans (for example, a fan-out of identical DB calls) into a single aggregated span. Off unless set. –prune-group-by, –prune-min-spans, and –prune-max-parent-depth tune the pruning behavior and apply only when –prune enables pruning. If the trace is too large for -o agents, the response is spilled to a file with a hint to read it directly or re-run narrower (e.g. with –filter or –prune). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces get TRACE_ID [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Fetch a trace by ID for agent analysis gcx traces get -d UID --llm -o json # Print a Grafana Explore share link for the trace gcx traces get -d UID --share-link # Output raw OTLP-shaped JSON when explicitly needed gcx traces get -d UID -o json # Narrow a large trace to error spans and their ancestor path gcx traces get -d UID --filter '{ status = error }' --keep-hierarchy # Collapse repeated sibling spans to shrink a huge trace before analysis gcx traces get -d UID --prune --llm -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --ancestor-depth int [experimental] Levels of ancestors to keep above each matched span: -1 = all (default), 0 = none, n = n levels (ignored without --filter or --keep-hierarchy) (default -1) -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --filter string [experimental] TraceQL spanset filter; only matching spans are returned (V2 only) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --keep-hierarchy [experimental] Include each matched span's ancestor path to the root (ignored without --filter) --llm [experimental] Request LLM-friendly trace format by sending the 'Accept: application/vnd.grafana.llm' header. Falls back to default JSON --match-depth int [experimental] Levels of descendants to keep below each matched span: -1 = all, 0 = matched spans only, n = n levels (ignored without --filter) --open Open the retrieved trace in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --prune [experimental] Collapse repeated sibling spans (e.g. a fan-out of identical DB calls) into a single aggregated span to shrink large traces. Off unless set --prune-group-by string [experimental] Comma-separated attribute glob patterns siblings must match to be grouped for pruning, e.g. 'db.*,http.method'. Applies only when --prune enables pruning --prune-max-parent-depth int [experimental] Ancestor levels above pruned leaves that may also be pruned; Tempo defaults to 1. Applies only when --prune enables pruning --prune-min-spans int [experimental] Minimum sibling span count required before a group is pruned; Tempo defaults to 5. Applies only when --prune enables pruning --share-link Print the Grafana Explore URL for the retrieved trace to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces labels` List all trace labels or get values for a specific label from a Tempo datasource. When -l/–label is provided, returns values for that label. When -l is omitted, returns all label names. Datasource is resolved from -d flag or datasources.tempo in your context. Experimental: –llm requests label values in a new LLM-friendly JSON format by sending the “Accept: application/vnd.grafana.llm” header. Datasources that do not support this format return the standard response. **Aliases:** `tags` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all labels gcx traces labels -d UID # Get LLM-friendly values for a label gcx traces tags -d UID -l resource.service.name --llm -o json # Output as JSON gcx traces labels -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label string Get values for this label (omit to list all labels) --llm [experimental] Request LLM-friendly label values format by sending the 'Accept: application/vnd.grafana.llm' header. Falls back to default JSON (requires --label) -o, --output string Output format. One of: agents, json, table, yaml (default "table") -q, --query string TraceQL query to filter labels --scope string Tag scope filter (resource, span, event, link, instrumentation) ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces metrics` Execute a TraceQL metrics query against a Tempo datasource. TRACEQL is the TraceQL metrics expression to evaluate. Datasource is resolved from -d flag or datasources.tempo in your context. Metrics queries support arithmetic (+, -, \*, /) with other queries or numeric scalars on supported Tempo backends. Wrap each metrics subquery in parentheses. Instant vs range is deduced from time flags: no time flags = instant query, –since or –from/–to = range query. Use –instant to force an instant query even when a time range is provided. If no time flags are set, gcx queries the last hour by default. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces metrics [TRACEQL] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Run a TraceQL metrics query gcx traces metrics -d UID '{ } | rate()' --since 1h # Print a Grafana Explore share link for the query gcx traces metrics '{ } | rate()' --share-link # Error percentage among observed server spans (not unsampled traffic) gcx traces metrics '100 * ({ kind = server && status = error } | rate()) / ({ kind = server } | rate())' --since 1h -o json # Each service's share of observed server-span throughput gcx traces metrics '({ kind = server } | rate() by (resource.service.name)) / ({ kind = server } | rate())' --since 1h ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for metrics --instant Run an instant query over the selected time range instead of a range query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces query` Search for traces using a TraceQL query against a Tempo datasource. TRACEQL is the TraceQL expression to evaluate. Datasource is resolved from -d flag or datasources.tempo in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. Share links require an explicit time range via –since or –from/–to. **Aliases:** `search` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces query [TRACEQL] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Run a TraceQL query gcx traces query -d UID '{ span.http.status_code >= 500 }' # Print a Grafana Explore share link for the query gcx traces query '{ span.http.status_code >= 500 }' --share-link # Output as JSON gcx traces query -d UID '{ span.http.status_code >= 500 }' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of traces to return (0 means no limit) (default 20) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx version` Print version, commit, build date, Go version, OS, and architecture. Supports structured output via –output json/yaml. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx version [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Human-readable version gcx version # JSON output for automation gcx version -o json # Select specific fields gcx version --json version,commit ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for version --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ## Environment variables Environment variables override matching configuration values in the selected context for the current invocation; they do not implicitly update the configuration file. `--context` selects the context before these overrides are applied. Precedence depends on the setting (highest priority first): - **Configuration file selection:** `--config` > `GCX_CONFIG` > automatic discovery. An explicit file bypasses layering; otherwise, repository configuration takes precedence over user configuration, then system configuration. - **Agent mode:** explicit `--agent` or `--agent=false` > `GCX_AGENT_MODE` > agent detection variables. - **Telemetry:** non-empty `GCX_TELEMETRY` > `DO_NOT_TRACK=1` or `true` > `diagnostics.telemetry` in configuration > the built-in default. Blank `GRAFANA_TOKEN`, `GRAFANA_PASSWORD`, and `GRAFANA_CLOUD_TOKEN` values are ignored. Environment overrides still follow the [configuration source and credential restrictions](/docs/grafana-cloud/ai-tools/gcx/configuration/#understand-the-gcx-configuration-file-in-use). ### `AGENT` GooseIdentity detects Goose when AGENT is goose. Other values are ignored. ### `AI_AGENT` AIIdentity follows the AI\_AGENT convention. A supported name or name@version enables agent mode. Unknown names and versions are not sent. ### `DO_NOT_TRACK` DoNotTrack disables anonymous usage telemetry when set to “1” or “true” (cross-tool DO\_NOT\_TRACK convention). Overridden by GCX\_TELEMETRY. ### `GCX_AGENT_MODE` Mode enables agent mode with 1, true, or yes. The values 0, false, and no disable it. The –agent flag takes precedence. ### `GCX_AGENT_NAME` Name identifies the calling agent and enables agent mode unless disabled explicitly. Use a supported name from the agent detection reference. Unknown names are ignored and are never sent in usage telemetry. ### `GCX_AUTO_APPROVE` AutoApprove automatically enables the –force flag on delete operations, enabling non-interactive operation in CI/CD pipelines. ### `GCX_KEYCHAIN` Keychain overrides trusted credentials.keychain configuration. “off” is the only value that disables the OS keychain and persists credentials in the mode-0600 config file. “on” is the default; an unrecognized value warns and resolves to “on”, so a typo cannot silently write plaintext. ### `GCX_NO_UPDATE_NOTIFIER` DisableUpdateNotifier disables the periodic notifier that reminds users when their installed gcx skills can be updated. Any non-empty value disables the notifier (NO\_COLOR convention). ### `GCX_TELEMETRY` Telemetry controls anonymous usage telemetry for this invocation: “enabled”, “disabled”, or “log” (print the event to stderr and send nothing). Telemetry is enabled by default. Any other non-empty value disables telemetry. Takes precedence over the `diagnostics.telemetry` config field. ### `GCX_TELEMETRY_ENDPOINT` Endpoint overrides the URL usage telemetry is sent to. ### `GRAFANA_CLOUD_API_URL` APIUrl is the base URL for all Grafana Cloud API (GCOM) resource calls (stacks, regions, access policies, etc.). Every client talking to GCOM uses it. It is materialized together with OAuthUrl so authentication and later API calls stay in the same Cloud environment. ### `GRAFANA_CLOUD_OAUTH_URL` OAuthUrl is the base URL for the OAuth login flow run by `gcx cloud login`. It is used only during login. Credential-bearing entries are materialized as a coherent OAuth/API pair: one explicit endpoint fills its missing peer; with neither set, gcx derives one unique referenced-stack Cloud environment or falls back to “[https://grafana.com](/)”. Incompatible referenced environments are rejected and require separate entries. ### `GRAFANA_CLOUD_TOKEN` Token is a Grafana Cloud access policy token used to authenticate against GCOM. ### `GRAFANA_ORG_ID` OrgID specifies the organization targeted by this config. Note: required when targeting an on-prem Grafana instance. See StackID for Grafana Cloud instances. ### `GRAFANA_PASSWORD` Password to use when using with basic authentication. Optional. ### `GRAFANA_PROXY_ENDPOINT` ProxyEndpoint is the assistant backend URL used as a reverse proxy for OAuth-authenticated requests. Set automatically by `gcx login`. This may differ from Server when cloud routing directs CLI traffic through a separate endpoint (e.g. the assistant app backend). ### `GRAFANA_SERVER` Server is the address of the Grafana server (https://hostname:port/path). Required. ### `GRAFANA_STACK_ID` StackID specifies the Grafana Cloud stack targeted by this config. Note: required when targeting a Grafana Cloud instance. See OrgID for on-prem Grafana instances. ### `GRAFANA_TLS_CA_FILE` CAFile is the path to a PEM-encoded CA certificate bundle file. When set, this CA is used to verify the server’s certificate. ### `GRAFANA_TLS_CERT_FILE` CertFile is the path to a PEM-encoded client certificate file. This enables mutual TLS (mTLS) authentication with the server. ### `GRAFANA_TLS_KEY_FILE` KeyFile is the path to a PEM-encoded client certificate key file. ### `GRAFANA_TOKEN` APIToken is a service account token. See [https://grafana.com/docs/grafana/latest/administration/service-accounts/#add-a-token-to-a-service-account-in-grafana](/docs/grafana/latest/administration/service-accounts/#add-a-token-to-a-service-account-in-grafana) Note: if defined, the API Token takes precedence over basic auth credentials. Optional. ### `GRAFANA_USER` User to authenticate as with basic authentication. Optional. ### `GRAFANA_CLOUD_STACK` Selected stack’s Grafana Cloud slug ### `GCX_CONFIG` Config file path override ### `NO_COLOR` Disable color output (no-color.org) ### `GRAFANA_PROVIDER_SLO_TOKEN` Overrides the slo provider’s token configuration. ### `GRAFANA_PROVIDER_SLO_ORG_ID` Overrides the slo provider’s org-id configuration. ### `GRAFANA_PROVIDER_SM_TOKEN` Overrides the sm provider’s token configuration. ### `GRAFANA_PROVIDER_SM_URL` Overrides the sm provider’s url configuration. ### `GCX_AGENT_SPILL_BYTES` Spill threshold in bytes for the `agents` codec (default `102400` = 100 KiB). `0` disables spilling. Invalid values use the default. See output.md. ### `CLAUDECODE`, `CLAUDE_CODE` Boolean identity signal ### `CURSOR_AGENT` Boolean identity signal ### `GITHUB_COPILOT`, `COPILOT_CLI` Boolean identity signal ### `COPILOT_AGENT_SESSION_ID` Non-empty session marker ### `AMAZON_Q` Boolean identity signal ### `KILO` Boolean identity signal; takes precedence over `OPENCODE` ### `QWEN_CODE` Boolean identity signal; takes precedence over `GEMINI_CLI` ### `GEMINI_CLI` Boolean identity signal ### `CODEX_SHELL` Boolean identity signal ### `CODEX_THREAD_ID`, `CODEX_SESSION_ID` Non-empty session marker ### `CLINE_ACTIVE` Boolean identity signal in VS Code agent terminals ### `GOOSE_TERMINAL` Boolean identity signal on supported shell paths ### `OPENCODE` Boolean identity signal ### `PI_CODING_AGENT` Boolean identity signal