gcx CLI on Grafana Labs

Introduction to gcx

Wed, 14 Oct 2026 09:22:12 +0000

Overview of the `gcx` CLI

gcx is a single CLI that allows you and your AI coding agent structured access to both Grafana (dashboards, folders, alert rules, data sources) and Grafana Cloud products such as Synthetic Monitoring, K6, Fleet Management, Incidents, or Adaptive Telemetry.

gcx ships with a suite of agent skills for common workflows like alert investigation, root-cause analysis, dashboard creation and GitOps, SLO management, and observability setup. It natively supports agentic workflows and it’s integrated with Grafana Assistant, combining the previously fragmented user experience into one single tool.

gcx is under continuous development. Contact Grafana for support or to report any issues you encounter and help us improve this feature.

Benefits of `gcx`

Among others, gcx provides the following benefits:

Manage Grafana OSS/Enterprise and Grafana Cloud: Use a single tool for dashboards, alerting, SLOs, on-call, synthetic checks, load testing, and more.
GitOps: Pull resources to files, version in Git, or push back with full round-trip fidelity.
SRE: Ensure system performance by monitoring telemetry and root-causing incidents.
Observability as code: gcx can scaffold Go projects, import existing dashboards, lint with Rego rules, or live-reload development servers.
Automation: gcx uses JSON/YAML output, structured errors, and predictable exit codes.
Multi-environment: Use named contexts to switch between development, staging, and production environments.
AI agent friendly: Agent mode auto-detected for Claude Code, Copilot, Cursor, and other.

Costs

Note
gcx itself is free, but some commands operate Grafana Cloud products that are billed based on usage.

For example:

Grafana Assistant is charged per token consumed, including requests made through gcx.
Synthetic Monitoring is billed per test execution.
Performance Testing (k6) is charged per Virtual User Hour.
IRM is billed per monthly active user.

For details, refer to the Cost Management and Billing documentation and Grafana Cloud pricing.

Compatibility

The following applies:

gcx is available for Grafana Cloud and Grafana OSS/Enterprise v12 or later. Older Grafana versions are not supported.
gcx is compatible with any agentic coding tool.
gcx works across a wide range of Grafana product offerings. Feature availability depends on your Grafana deployment. For more information, refer to the Compatibility matrix.

CLI command reference

You can find the up-to-date command reference guide in the CLI command reference for the latest stable release.

Configure `gcx`

Refer to Configuration commands for an overview of useful commands to check your configuration.

Experimental commands

Commands are stable within a major version, with the exception of those labelled experimental.

However, some commands are labelled [experimental] in their help text and carry a stability field of experimental in gcx commands output. Commands are labelled experimental when they are not yet stable, or when they operate a Grafana Cloud feature that is not yet Generally Available. For more information, refer to Release life cycle for Grafana Labs. An experimental command may be removed, or its subcommands, flags, and responses may change, without following the normal semantic versioning conventions.

Manage your resources

You can manage your resources using the gcx resources set of commands. Refer to the Resource Model guide for more information on the architecture and resource model used by gcx.

Work with resources from other tools

If you want to work with resources managed by other tools, such as Terraform or Git Sync, use the flag --include-managed with commands such as gcx resources pull or gcx resources push.

Extract dashboards

At the moment, if you extract a dashboard as a JSON (gcx resources pull dashboards -o json), gcx only returns the original JSON, and can’t convert it to a different version.

Migrate from `grafanactl`

If you want to migrate from grafanctl to gcx, search-and-replace grafanactl with gcx. For grafanactl resources serve, use gcx dev serve instead.

Learn more

Refer to the gcx repository in GitHub for the full set of gcx documents, including more information on:

Installation and configuration
How to manage resources, including dashboards-as-code
Architecture
User guides

Install gcx

Tue, 13 Oct 2026 15:26:25 +0000

Install `gcx`

Quick install using the script

The fastest way to install gcx on Linux or macOS is with the script:

curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | sh

The script:

Detects your operating system and architecture.
Downloads the latest release from GitHub
Verifies the SHA-256 checksum.
Installs the binary to ~/.local/bin.

Upgrade

To upgrade, run the same command again. The script always installs the latest release.

Check the result:

gcx --version

If the version does not change, refer to The version does not change after an upgrade.

Installer configuration options

Use these environment variables to customize the install script:

Environment variable	Default	Description
`GCX_INSTALL_DIR`	`$HOME/.local/bin`	Directory to install the binary into
`GCX_VERSION`	latest	Specific version to install (e.g., `0.2.4`)
`GITHUB_TOKEN`	unset	GitHub token for API requests (avoids rate limits)

The script also accepts INSTALL_DIR and VERSION. The GCX_ names take precedence. Prefer the GCX_ names, because INSTALL_DIR and VERSION are common names, and curl | sh inherits every variable that your shell exports.

Examples

Install a specific version:

curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | GCX_VERSION=0.2.4 sh

Install to /usr/local/bin:

curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | GCX_INSTALL_DIR=/usr/local/bin sh

Uninstall

To remove gcx, delete the binary:

rm ~/.local/bin/gcx

Install `gcx` with Homebrew (macOS and Linux)

To install gcx with Homebrew run:

brew install gcx

This command installs the gcx formula from homebrew-core. Homebrew has a prebuilt bottle for macOS and Linux, so the install takes seconds. You do not need to add a tap.

To upgrade an existing installation:

brew upgrade gcx

Install from the Grafana tap

The Grafana tap also carries gcx. Use the tap if you want Homebrew to compile the binary on your machine:

brew install grafana/grafana/gcx

Homebrew installs go as a build dependency for this formula. The first install usually takes 30 to 60 seconds, and later upgrades reuse the Homebrew download cache.

Install gcx from one source only. Two Homebrew formulas with the same name conflict with each other.

Homebrew and macOS Gatekeeper

Both Homebrew methods avoid the macOS Gatekeeper problem. Homebrew does not set the quarantine attribute on the files that it installs, so you do not need to work around notarisation.

Install a prebuilt binary

Prebuilt binaries are available for a variety of systems and architectures. Refer to the release versions on GitHub for more details.

To install a prebuilt binary:

Download the archive for the operating system and architecture you need.
Extract the archive.
Move the executable to the directory where you want to keep it.
Make sure that directory is in your PATH.
Make sure the file has execute permission.

If you use macOS, a manually downloaded binary might be blocked by Gatekeeper. For more information, refer to macOS Gatekeeper and killed: 9.

Run `gcx` in a container

Each release publishes a multi-arch (linux/amd64, linux/arm64) image to ghcr.io/grafana/gcx. The entrypoint is gcx:

docker run --rm ghcr.io/grafana/gcx:latest --version

Pass credentials through GRAFANA_* environment variables, or mount a config file and point GCX_CONFIG at it, for example -v "$HOME/.config/gcx:/gcx:ro" -e GCX_CONFIG=/gcx/config.yaml. To pin a release in CI, use an exact tag such as v1.5.0. The v1.5 and v1 tags follow the latest patch and minor release of that line. Prereleases only get their exact tag.

The image is based on distroless and has no shell, so run gcx directly, not through sh -c.

Install `gcx` from source

To install gcx with Go, you need:

git.
go 1.24 or later.

To install, run:

go install github.com/grafana/gcx/cmd/gcx@latest

The version does not change after an upgrade

This page lists several install methods, and they write gcx to different directories. If you use two methods, you get two copies. Your shell runs the copy in the directory that comes first in PATH, and an upgrade of the other copy changes nothing that you can see.

List every copy:

which -a gcx

The first line is the copy that your shell runs. Remove the copies that you do not want:

Path	Install method	Command that removes it
`~/.local/bin/gcx`	Install script	`rm ~/.local/bin/gcx`
`/usr/local/bin/gcx`	Prebuilt binary, or the script with `GCX_INSTALL_DIR`	`sudo rm /usr/local/bin/gcx`
`/opt/homebrew/bin/gcx`, `/home/linuxbrew/.../gcx`	Homebrew	`brew uninstall gcx`
`~/go/bin/gcx`	`go install`	`rm ~/go/bin/gcx`

After you remove a copy, your shell can still hold the old path in its command hash table. Open a new terminal, or run:

hash -r

The install script reports this problem for you. It names both paths and both versions, and it gives the removal command.

macOS Gatekeeper and killed 9

macOS quarantines any downloaded binary by default. Since gcx release binaries are not yet Apple-notarised, macOS may block it the first time you run it. If this happens, you’ll see one of these two symptoms:

Intel macOS: A dialog says, “Apple could not verify ‘gcx’ is free of malware…”, and the binary doesn’t run.
Apple Silicon (M-series) macOS: The binary exits immediately with killed: 9 and no visible dialog.

Homebrew users are not affected. Homebrew does not set the xattr on the files that it installs.

Bypass the macOS gatekeeper

In manual downloads, bypass this by clearing the xattr and ad-hoc sign the binary so Apple Silicon accepts it:

xattr -d com.apple.quarantine "$(command -v gcx)" 2>/dev/null || true
codesign --sign - --force "$(command -v gcx)"   # required on Apple Silicon

Next, run gcx --version again; subsequent invocations should succeed without the block.

Note that these steps will no longer be necessary once gcx release binaries are Apple-notarised.

Configure gcx

Wed, 14 Oct 2026 13:20:26 +0000

Configure `gcx`

You can configure gcx with a configuration file or using environment variables.

A configuration file stores named stacks, named Grafana Cloud credentials, and contexts that bind them. gcx can layer system, user, and repository files. Refer to the configuration file reference documentation for all options.
- If you have a file from an older gcx version, refer to Migrate your gcx configuration.
Environment variables override the selected context in memory, so they work best in CI environments and are never persisted implicitly. Refer to Configure gcx with environment variables for more information.

Choose an authentication method

gcx supports four ways to authenticate to a Grafana instance:

OAuth (Grafana Cloud only): Browser-based sign-in with gcx login. Recommended for interactive use. The tokens are user-scoped: every request runs with your own identity and RBAC permissions, so you can’t access anything through gcx that you can’t already access in the Grafana UI. Refer to Required role for OAuth sign-in for the permission this flow needs.
Service account token: Works for Grafana Cloud and on-premises instances, and is the recommended method for CI and other non-interactive environments. Refer to Grafana service accounts for how to create one.
Basic authentication: Username and password. Use this only when service accounts aren’t available.
mTLS: A client certificate and key for instances behind an identity-aware proxy. Configure the grafana.tls fields or corresponding TLS environment variables.

Grafana Cloud platform APIs use a separate credential stored in a named Cloud entry. A Cloud Access Policy token has full command compatibility and is recommended for automation. Direct Cloud OAuth is available through gcx cloud login or the interactive Cloud step of gcx login, but remains experimental and is not yet accepted by every Cloud product command. OAuth entries retain expiry, granted scopes, and a coherent OAuth/API endpoint pair.

To authorize a gcx CLI connection with OAuth, your Grafana user needs the grafana-assistant-app.tokens.gcx:access permission. The gcx User role, registered by the Grafana Assistant application, grants this permission and is assigned automatically to users with the basic role Viewer or higher.

Note
If your default role is None, or you’re using a custom role that doesn’t grant the default plugins.app:access action, you’ll also need to explicitly grant access to grafana-assistant-app:
JSON
{
  "action": "plugins.app:access",
  "scope": "plugins:id:grafana-assistant-app"
}

The grafana-assistant-app.tokens.gcx:access permission only lets you create gcx tokens for your own user. It doesn’t grant access to other users’ tokens and it doesn’t extend your existing Grafana permissions.

Note
If gcx login fails with a Permission Required error naming the gcx User role, ask your Grafana administrator to assign you the gcx User role, or a custom role that includes the grafana-assistant-app.tokens.gcx:access permission. If the role doesn’t exist on your instance, the Grafana Assistant application needs to be updated to a version that includes it.

Understand the `gcx` configuration file in use

Run gcx config path to display the configuration files currently in use.

gcx stores configuration in YAML. --config <path> or GCX_CONFIG=<path> selects one explicit file and bypasses layering. Otherwise, gcx loads every existing source in this order, with later sources taking precedence:

System: the platform system config directory (for example, $XDG_CONFIG_DIRS/gcx/config.yaml).
User: $HOME/.config/gcx/config.yaml, falling back to the platform user config directory such as $XDG_CONFIG_HOME/gcx/config.yaml.
Repository: .gcx.yaml in the current working directory.

Named stacks and cloud entries are atomic across sources: a higher-priority same-named entry replaces the lower entry completely. This keeps a credential and its server or Cloud endpoint in the same trust source. Context references and datasource defaults may merge field-by-field.

Credentials in the OS credential store (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux) are tied to the canonical config file, exact owner kind and name, exact secret field, and normalized destination. Copying a config file does not make its stored credentials portable; authenticate the copied file separately. See Keychain credential storage for storage rules and keychain error procedures.

An automatically discovered repository .gcx.yaml cannot attach tokens, passwords, or client-certificate files from your environment, login flags, or prompts to destinations the file supplies. It also cannot implicitly combine a Cloud credential with a direct provider endpoint or write derived provider credentials and caches. A provider endpoint supplied at runtime is accepted only with its matching runtime credential, and neither value authorizes TLS or proxy settings from an auto-discovered repository stack. To trust the repository config for those operations, select it explicitly:

gcx login --config .gcx.yaml
# or
GCX_CONFIG=.gcx.yaml gcx login

Credentials already owned by that exact file remain usable while their bound destination is unchanged.

Literal edits to a named stack or Cloud entry affect every context that references it. If an edit changes a credential destination - such as a Grafana server, Synthetic Monitoring URL, or Cloud API/OAuth endpoint - gcx clears the old credential in the same write. Supply a fresh credential before using the new destination. Normalization-equivalent endpoint edits preserve it.

Define contexts

gcx supports multiple contexts so you can switch between instances. A context references a named stack entry, which holds the Grafana connection details. By default, gcx uses the default context.

A stack entry holds one credential alongside its server. To use two identities against the same stack - for example a personal token and a CI token, or read-only and admin - define two stack entries and a context for each.

To configure the default context:

gcx config set stacks.default.grafana.server http://localhost:3000
gcx config set contexts.default.stack default

# Set org-id when using OSS/Enterprise - skip when targeting Grafana Cloud
gcx config set stacks.default.grafana.org-id 1

# Authenticate with a service account token
gcx config set stacks.default.grafana.token service-account-token

# Or alternatively, use basic authentication
gcx config set stacks.default.grafana.user admin
gcx config set stacks.default.grafana.password admin

To create another context, use the same pattern:

gcx config set stacks.staging.grafana.server https://staging.grafana.example
gcx config set stacks.staging.grafana.org-id 1
gcx config set contexts.staging.stack staging

Note that in these examples, default and staging are the context and stack names.

Useful commands

Use these commands to check the configuration:

gcx config check

Without --context, the check covers every configured context before returning. It exits non-zero when the current context is invalid or any checked context fails configuration, authentication setup, connectivity, or Grafana version checks, so it is safe to use as a deployment gate.

To check only one context without validating unrelated entries, pass --context:

gcx config check --context staging

List existing contexts:

gcx config list-contexts

Switch to a different context:

gcx config use-context staging

See the entire configuration:

gcx config view

Configure `gcx` with environment variables

Every supported environment variable is listed in our reference documentation.

Since gcx connects to Grafana through the REST API, you must configure authentication credentials. At minimum, set the Grafana URL and organization ID:

GRAFANA_SERVER='http://localhost:3000' GRAFANA_ORG_ID='1' gcx config check

Depending on your authentication method, also set one of the following:

If you use a Grafana service account (recommended), set a token.
If you use basic authentication, set a username and a password.

After you configure authentication, you can start using gcx.

If you want to persist this configuration, create a context.

Configuration reference

This schema describes configuration fields and their types in gcx v1.6.0.

# Config holds the information needed to connect to remote Grafana instances.
# Version is the config format version. Version 1 is the only declared
# version accepted by this release; unsupported versions are rejected before
# migration or credential access. The field is absent on legacy configs,
# which the loader migrates to the current format after a safety preflight.
version: int
# Stacks is a map of Grafana stack configurations (connection, providers,
# per-stack resource settings), indexed by name. Contexts reference stacks
# by name via Context.Stack.
stacks:
  ${string}:
    # StackConfig holds the connection and provider configuration for a single
    # Grafana stack. Contexts reference stacks by name via Context.Stack.
    # Slug is the Grafana Cloud stack slug (e.g. "mystack").
    # Optional: if not set, the slug may be derived from Grafana.Server.
    slug: string
    grafana:
      # Server is the address of the Grafana server (https://hostname:port/path).
      # Required.
      server: string
      # User to authenticate as with basic authentication.
      # Optional.
      user: string
      # Password to use when using with basic authentication.
      # Optional.
      password: string
      # 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
      # Note: if defined, the API Token takes precedence over basic auth credentials.
      # Optional.
      token: string
      # 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).
      proxy-endpoint: string
      # OAuthToken is the OAuth access token (gat_) obtained via `gcx login`.
      oauth-token: string
      # OAuthRefreshToken is the refresh token (gar_) for renewing OAuthToken.
      oauth-refresh-token: string
      # OAuthTokenExpiresAt is the OAuthToken expiration time in RFC3339 format.
      oauth-token-expires-at: string
      # OAuthRefreshExpiresAt is the OAuthRefreshToken expiration time in RFC3339 format.
      oauth-refresh-expires-at: string
      # AuthMethod selects "oauth", "token", "basic", or "mtls" when no complete
      # runtime credential override supersedes it. Empty is valid for legacy configs
      # and uses compatibility inference; consumers should use
      # Context.EffectiveGrafanaAuthMethod instead of inspecting fields.
      auth-method: string
      # OrgID specifies the organization targeted by this config.
      # Note: required when targeting an on-prem Grafana instance.
      # See StackID for Grafana Cloud instances.
      org-id: int
      # 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.
      stack-id: int
      # TLS contains TLS-related configuration settings.
      tls:
        # TLS contains settings to enable transport layer security.
        # InsecureSkipTLSVerify disables the validation of the server's SSL certificate.
        # Enabling this will make your HTTPS connections insecure.
        insecure-skip-verify: bool
        # ServerName is passed to the server for SNI and is used in the client to check server
        # certificates against. If ServerName is empty, the hostname used to contact the
        # server is used.
        server-name: string
        # CertFile is the path to a PEM-encoded client certificate file.
        # This enables mutual TLS (mTLS) authentication with the server.
        cert-file: string
        # KeyFile is the path to a PEM-encoded client certificate key file.
        key-file: string
        # CAFile is the path to a PEM-encoded CA certificate bundle file.
        # When set, this CA is used to verify the server's certificate.
        ca-file: string
        # CertData holds PEM-encoded bytes (typically read from a client certificate file).
        # Note: this value is base64-encoded in the config file and will be
        # automatically decoded.
        cert-data:
          - int
          - ...
        # KeyData holds PEM-encoded bytes (typically read from a client certificate key file).
        # Note: this value is base64-encoded in the config file and will be
        # automatically decoded.
        key-data:
          - int
          - ...
        # CAData holds PEM-encoded bytes (typically read from a root certificates bundle).
        # Note: this value is base64-encoded in the config file and will be
        # automatically decoded.
        ca-data:
          - int
          - ...
        # NextProtos is a list of supported application level protocols, in order of preference.
        # Used to populate tls.Config.NextProtos.
        # To indicate to the server http/1.1 is preferred over http/2, set to ["http/1.1", "h2"] (though the server is free to ignore that preference).
        # To use only http/1.1, set to ["http/1.1"].
        next-protos:
          - string
          - ...
      # PathfinderInstalled caches that the Pathfinder plugin was detected as
      # installed and enabled on this server during `gcx login`. Once true, later
      # logins skip the detection probe and the one-time guide hint. In practice
      # the plugin is not uninstalled, so the flag is sticky and never cleared
      # automatically. Set automatically by `gcx login`.
      pathfinder-installed: bool
    # Providers holds per-provider configuration, indexed by provider name.
    # Each provider has a map of string key-value pairs.
    # Secret fields are selectively redacted by providers.RedactSecrets using
    # each provider's ConfigKey metadata.
    providers:
      ${string}:
        ${string}:
          string
    # Resources holds per-stack settings for the `gcx resources` commands,
    # merged (union) with the global Config.Resources.
    resources:
      # ResourcesConfig holds settings for the `gcx resources` commands.
      # AssumeServerDryRun lists resources ("<resource>.<group>", e.g.
      # "alertrules.rules.alerting.grafana.app") the user asserts honor server-side dry-run on
      # this stack, added to the built-in allowlist so --dry-run sends them to the server.
      assume-server-dry-run:
        - string
        - ...
# Cloud is a map of named Grafana Cloud (GCOM) auth entries. Contexts
# reference entries by name via Context.Cloud.
cloud:
  ${string}:
    # CloudEntry holds Grafana Cloud (GCOM) platform credentials and environment
    # configuration. Entries are named and referenced by contexts via
    # Context.Cloud; several contexts typically share one entry.
    # Token is a Grafana Cloud access policy token used to authenticate
    # against GCOM.
    token: string
    # OAuthToken is a grafana.com OAuth access token obtained via
    # `gcx cloud login`. The grafana.com OAuth flow issues no refresh token;
    # on expiry the user re-runs `gcx cloud login`.
    oauth-token: string
    # OAuthTokenExpiresAt is the OAuthToken expiration time in RFC3339 format.
    oauth-token-expires-at: string
    # OAuthScopes is the scope set granted by the OAuth token endpoint. It may
    # differ from the requested set and is retained so re-auth/keep operations do
    # not discard capability metadata.
    oauth-scopes:
      - string
      - ...
    # 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.
    oauth-url: string
    # 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.
    api-url: string
# Resources holds global settings for the `gcx resources` commands,
# applying to all stacks. Merged (union) with each stack's Resources.
resources:
  # ResourcesConfig holds settings for the `gcx resources` commands.
  # AssumeServerDryRun lists resources ("<resource>.<group>", e.g.
  # "alertrules.rules.alerting.grafana.app") the user asserts honor server-side dry-run on
  # this stack, added to the built-in allowlist so --dry-run sends them to the server.
  assume-server-dry-run:
    - string
    - ...
# Contexts is a map of context configurations, indexed by name.
contexts:
  ${string}:
    # Context binds a stack and (optionally) a cloud auth entry together with
    # per-context defaults such as datasource UIDs.
    # Stack names the entry in Config.Stacks this context targets.
    stack: string
    # Cloud names the entry in Config.Cloud providing GCOM auth for this
    # context. Optional: without it, cloud-dependent operations fail at
    # runtime with a hint, not at validation time.
    cloud: string
    # Datasources holds per-kind default datasource UIDs, indexed by
    # datasource kind (e.g. "prometheus", "loki").
    datasources:
      ${string}:
        string
# CurrentContext is the name of the context currently in use.
current-context: string
# Diagnostics holds optional local diagnostic settings. All features are off by default.
diagnostics:
  # DiagnosticsConfig controls optional local diagnostic features.
  # AgentInvocationLog enables logging of failed agent-mode invocations to disk.
  # Off by default. When enabled, errors from agent-driven gcx calls are written
  # to LogDir (JSONL format) for capability-gap analysis.
  agent-invocation-log: bool
  # LogDir overrides the output directory for agent invocation log files.
  # Default: $XDG_STATE_HOME/gcx/ (platform-specific).
  log-dir: string
  # Telemetry controls anonymous usage telemetry: "enabled", "disabled",
  # or "log" (prints to stderr). Enabled by default. Overridden by the
  # GCX_TELEMETRY environment variable.
  telemetry: string
# Credentials controls how gcx persists credentials. It contains policy
# only; credential values remain on their owning stack and cloud entries.
credentials:
  # CredentialsConfig controls credential persistence without owning secrets.
  # Keychain selects whether credentials use the OS credential store. Valid
  # values are "on" and "off". The default is "on".
  keychain: string

Migrate your gcx configuration

Fri, 14 Aug 2026 15:24:45 +0000

Migrate your `gcx` configuration files to v1 format

gcx is adjusting its configuration file format to make it easier to reuse credentials across contexts. This applies for gcx versions v0.6.0 and later. The v1 format splits the file into three sections: stacks for Grafana connections, cloud for Grafana Cloud credentials that multiple contexts can reference, and contexts that reference both by name.

How migration works

gcx attempts to migrate any legacy configuration file automatically the first time it loads it. If gcx prints a warning or error that linked here, your migration paused or stopped for one of a small set of reasons. Find the message you saw in Why a migration paused or stopped and follow the steps.

Refer to the table of field mappings at the end of this document to see how to convert a config file manually.

Migration doesn’t delete any information

Whatever state your migration is in, nothing has been lost:

A paused or stopped migration changes nothing: no file, no backup, no credential store entry. gcx keeps working from an in-memory conversion where it safely can.
A completed migration replaces the file only after checking the converted result means the same as the original, and keeps the original next to it as <file>.legacy.bak. gcx never overwrites or deletes that backup.
Credentials in the OS credential store (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux) are copied into new entries; the old entries stay, so the backup remains fully usable.

Roll back a completed migration

To roll back a completed migration, copy the backup over the configuration file:

cp ~/.config/gcx/config.yaml.legacy.bak ~/.config/gcx/config.yaml

Caution
If your legacy file contained plaintext credentials, they remain in <file>.legacy.bak even after migration moves them into the OS credential store. Remove the backup yourself once you’re sure you won’t roll back.

Why a migration paused or stopped

Here are the reasons the config migration might have aborted, with an explanation of how to fix it:

“layered configuration migration is incomplete”: your configuration is spread across several files (system, user, or a repository .gcx.yaml). gcx converts them in memory so commands keep working, but never rewrites several files for you, to avoid a state where some config files were migrated, but others were not. To remedy this, follow How to migrate layered files.

“cannot safely auto-migrate layered legacy configuration” or “the overlapping entries require manual consolidation”: two of your files define overlapping pieces of the same entry, which the v1 merge rules would combine differently than the legacy rules did. To remedy this, follow How to consolidate overlapping layers.

“running with in-memory config migration … reason: a legacy credential could not be read from the credential store”: the credential store was locked, an unlock prompt was dismissed, or gcx ran in a session without credential store access (SSH, CI). Persisting the migration then could strand references to credentials it couldn’t re-store, so gcx waits. Unlock your credential store (or run from a desktop session) and run any gcx command; the migration completes on its own.

“running with in-memory config migration” with a permission-related reason: the configuration file or its directory isn’t writable. Read-only config commands keep working from the in-memory config, but anything that writes configuration or credentials fails until the file is writable or replaced with a v1 file. To remedy this, either fix the permissions and run any gcx command, or for CI type environments, update the config file to use the v1 format. (see the field mapping).

“existing legacy config backup does not match the current source”: a previous migration left a .legacy.bak and the file has since been rewritten in the legacy format (for example by an older gcx version). gcx won’t overwrite the earlier backup. To fix this, compare the two files, keep the one you trust and run any gcx command.

“unsupported config version”: the file isn’t in the legacy format, and gcx doesn’t recognize it. Upgrade gcx to support a more modern format (this is more for futureproofing - there is only v1 at the moment).

“config migration self-check failed”: gcx converted the file, checked the result against the original, and found a difference, so it left the file untouched. This indicates a bug, report it with the error text, and migrate by hand in the meantime.

How to migrate layered files

The migration warning lists each remaining legacy file that needs migrating. Migrate the config files one at a time - each command rewrites just that file in the v1 format and leaves a .legacy.bak backup next to it. For example:

gcx config set --file user version 1
gcx config set --file local version 1

After each step, gcx re-prints the commands for whatever legacy files still need migrating, and refuses any per-file conversion that could replace a complete entry with a partial one. When it can’t offer a safe command it tells you to edit the file instead. To inspect any file without loading it, run gcx config edit <system|user|local>.

Be aware that editing the system config file edits the config for all users on your system.

When all files are migrated, the warning will disappear. To confirm everything is ok, refer to Verify the result.

How to consolidate overlapping layers

Legacy gcx merged contexts with the same name, but from different files, field by field. v1 doesn’t: a stack or Cloud entry in a higher-priority file completely replaces a same-named entry in a lower one. This is so one file can never mix its server with another file’s credentials. Files that relied on partial overrides need consolidating once, manually:

The error will name the entries that overlap. Open each file with gcx config edit <system|user|local>.
Move the overriding fields into the file that owns the complete entry, or rename the overriding entry (for example, give a repository-specific context its own stack name) so nothing overlaps.
Run any gcx command. The preflight re-checks; once nothing overlaps you are directed to Migrate layered files.

Map a legacy configuration to version 1

To convert a file by hand: copy the original somewhere safe, move each field to its new home using the table, add version: 1 at the top, and verify. Here is a map from the old field locations to the new ones:

Legacy (per context)	Version 1
`contexts.<name>.grafana.*`	`stacks.<name>.grafana.*`, plus `contexts.<name>.stack: <name>`
`contexts.<name>.cloud.token`	`cloud.<entry>.token`, plus `contexts.<name>.cloud: <entry>`
`contexts.<name>.cloud.api-url`	`cloud.<entry>.api-url`
`contexts.<name>.cloud.oauth-url`	`cloud.<entry>.oauth-url`
`contexts.<name>.cloud.stack`	`stacks.<name>.slug`
`contexts.<name>.providers.*`	`stacks.<name>.providers.*`
`contexts.<name>.resources.*`	`stacks.<name>.resources.*`, or top-level `resources:` to apply to all stacks
`contexts.<name>.default-prometheus-datasource`	`contexts.<name>.datasources.prometheus`
`contexts.<name>.default-loki-datasource`	`contexts.<name>.datasources.loki`
`contexts.<name>.default-tempo-datasource`	`contexts.<name>.datasources.tempo`
`contexts.<name>.default-pyroscope-datasource`	`contexts.<name>.datasources.pyroscope`
`contexts.<name>.datasources.*`	unchanged
`current-context`, `diagnostics`	unchanged

You can name the cloud entries whatever you like, since contexts refer to them by name. You can reuse cloud configs in multiple contexts.

If your legacy cloud.token came from the experimental OAuth sign-in rather than an access policy, it still migrates into token - the legacy format can’t tell the two apart. The next gcx cloud login stores it in the entry’s oauth-token field.

Example of a legacy configuration update

A legacy configuration:

contexts:
  prod:
    grafana:
      server: https://myorg.grafana.net
      token: "<service account token>"
    cloud:
      token: "<cloud access policy token>"
      stack: myorg
    default-prometheus-datasource: my-prom
  dev:
    grafana:
      server: https://myorg-dev.grafana.net
      token: "<service account token>"
    cloud:
      token: "<cloud access policy token>"   # same token as prod
current-context: prod

becomes:

version: 1
stacks:
  prod:
    slug: myorg
    grafana:
      server: https://myorg.grafana.net
      token: "<service account token>"
  dev:
    grafana:
      server: https://myorg-dev.grafana.net
      token: "<service account token>"
cloud:
  grafana-com:
    token: "<cloud access policy token>"     # shared by both contexts
contexts:
  prod:
    stack: prod
    cloud: grafana-com
    datasources:
      prometheus: my-prom
  dev:
    stack: dev
    cloud: grafana-com
current-context: prod

Credential references

If your legacy file contains values like keychain:gcx:prod:cloud-token, they are references to secrets in the OS credential store. Let the migration move them rather than copying the strings yourself.

gcx only resolves legacy credential references from files you chose and own, such as your standard user config file (a symlinked home or XDG path still counts), or one you selected explicitly with --config or GCX_CONFIG, and only when the file is writable by you alone. A reference must also sit where it claims to belong: the context and field named inside it have to match its location in the file. Files discovered from repositories or system directories are never trusted.

If a repository config contains credential references, select it explicitly with --config (only if you trust it), or replace the references with fresh credentials before migrating. Copying a legacy reference into a version 1 file never grants access to the secret.

Version 1 credential references are tied to the config file’s path, the exact stack or Cloud entry and field they belong to, and the credential’s destination. Copying a version 1 config to a different path copies its structure but not access to its credentials - run gcx login or gcx cloud login for the copied file instead of copying reference strings by hand.

Verify the result

After migrating, confirm the configuration parses and every context connects:

gcx config view
gcx config check

Where:

gcx config view shows the effective configuration with secrets redacted.
gcx config check validates every context, including connectivity, and exits non-zero if any check fails. Pass --context <name> to validate only that context.

Usage statistics

Thu, 08 Oct 2026 12:24:49 +0000

Understand gcx usage statistics

gcx reports limited usage statistics about itself to Grafana Labs. This data is used to understand which commands and flags are used most, where commands fail, and which commands people try that don’t exist, so we can make the product better.

The statistics describe only the shape of usage, including command path, and flag names. Positional argument values, free-form flag values, and resource names are never sent, and the flags you set are recorded by name only. Numeric values such as exit code, duration, and HTTP status describe command execution or protocol behavior. No raw count of batch or resource volume is sent.

The one place an argument value is used at all is the api command, where the requested route and the datasource plugin type are first reduced to fixed vocabularies built into the binary, so only known, non-identifying names can ever be sent - see The api command for details.

For the resource commands that operate on batches, the size of the operation is sent as one of seven fixed categories rather than as a number. Two of those categories, 0 and 1, cover a single value each, so those two sizes are exact; every larger category is a range. See How to read the batch fields.

Further fields describe how the command ran rather than naming a flag: output_format records the output format used, from a fixed list of known formats; dry_run records whether the operation executed in dry-run mode; and grafana_auth_method records the authentication category selected for the Grafana connection, from a fixed vocabulary and never the credential itself. output_format is read from --output, which means a command that renders JSON because you passed --json is still recorded with --output’s value; that mismatch is a known bug rather than intended behaviour. dry_run is derived from the operation and is set even for commands that have no --dry-run flag; grafana_auth_method is described in Failure and authentication fields. Some server-side enrichment is also performed on the usage statistics exported - see Server-side enrichment for details.

Note
Usage statistics reporting is enabled by default. See the Opt out section below for guidance on how to turn off usage reporting.

Telemetry data and identifiers

The only identifier is a device_id field: a randomly generated UUID created on first use and stored at $XDG_STATE_HOME/gcx/device-id. It identifies an installation of gcx, not a person. It’s random, not derived from your hardware or account.

Understand which data is collected

Each gcx event contains the following properties:

Field	Description	Example
`service`	Always `gcx`, identifying the reporting product.	`gcx`
`version`	The version of `gcx`.	`0.4.1`
`os`	Operating system.	`linux`, `darwin`, `windows`
`arch`	CPU architecture.	`amd64`, `arm64`
`device_id`	The random per-installation ID described in Telemetry data and identifiers.	UUID
`device_id_persisted`	Whether the device ID was read from or saved to disk. `false` means a throwaway ID was used for this invocation.	`true`
`command`	The resolved command path only, no arguments are sent.	`dashboards push`
`flags`	The names of the flags you set, sorted. No flag values are sent in this field.	`dry-run,folder`
`provider`	The resource provider the command belongs to.	`dashboards`
`outcome`	How the invocation ended: `ok`, `runtime_error`, `canceled`, or `help`. (`parse_error` is reserved and not sent yet — see below.)	`ok`
`exit_code`	The process exit code.	`0`
`error_kind`	A coarse error category when the command failed: `usage_error`, `auth_failure`, `partial_failure`, `version_incompatible`, or `error`. Never an error message. Empty when the command did not fail, including when it was canceled.	`auth_failure`
`duration_ms`	Total invocation duration in milliseconds.	`1234`
`is_tty`	Whether `gcx` ran attached to an interactive terminal.	`false`
`is_ci`	Whether a CI environment was detected.	`true`
`ci_provider`	Which CI system was detected, from a fixed list of known names. `gcx` reads well-known CI environment variables to detect the provider but never sends their values.	`github_actions`
`is_agent`	Whether an AI coding agent drove the invocation.	`true`
`agent`	A fixed harness label, or `generic` when agent mode is enabled without a known identity.	`claude-code`
`target_kind`	Whether the target Grafana is `cloud` or `self-hosted`. Empty when no effective Grafana target could be resolved. Deliberately coarse — never the URL, hostname, or stack slug.	`cloud`
`output_format`	The output format the command used.	`table`, `json`

When the invocation is a batch resource operation (gcx resources push, pull, delete, or validate) that ran to completion, these additional fields are set. They describe the size of the operation, never what it contained:

Field	Description	Example
`batch_succeeded_bucket`	The size of the successful part of the operation, as one of seven fixed categories.	`21-100`
`batch_failed_bucket`	The size of the failed part, from the same seven categories.	`0`
`batch_skipped_bucket`	The size of the skipped part, from the same seven categories.	`0`
`dry_run`	Whether the operation executed in dry-run mode. `false` does not imply anything was changed: `gcx resources pull` is read-only and always reports `false`. Interpret it together with `command`. Derived from the operation, not read from a flag: `gcx resources validate` always reports `true` and `pull` always `false`, and neither has a `--dry-run` flag.	`false`

The seven categories are exactly 0, 1, 2-5, 6-20, 21-100, 101-1000, and 1001+. Note that 0 and 1 are singleton categories, so those two sizes are recoverable exactly; every larger category is a range.

Sizes are sent as categories rather than as numbers on purpose. An exact count of a large batch, correlated with the per-installation device_id and the network organization name added on receipt, would describe a specific organization’s resource inventory. Categories answer how gcx is used without carrying that detail, and the two singleton categories carry no inventory to infer. No raw numeric count field is sent.

How to read the batch fields

These fields are easy to misread, so the following constraints are part of the contract:

All four are present together, or none are. Their absence means the invocation was not one of those four commands, or it stopped before the operation reached a final count.
0 means nothing was counted in that outcome, which is not the same as nothing having happened. The three counts are not a complete partition of the work: a resource filtered out before processing is recorded in none of them. gcx resources validate over resources that are all managed elsewhere, or gcx resources delete against a resource type whose API does not support deletion, can therefore report 0/0/0 for a run that did examine resources. A 0 is still distinct from the field being absent, which means the operation never reached a final count.
The sizes describe the operation, not the output. They are recorded once the operation has finished and its counts are final. If the summary then fails to render or cannot be written to stdout, the sizes are still reported, because work that already happened is not undone by a display failure. Equally, they do not always correspond to a number printed on screen: --jq and --json <fields> reshape the output, and validate prints only failures and skips in JSON.
An operation that aborted partway reports nothing. It never reached a final count, so there is no size to report. Note that gcx resources delete with --on-error=abort may have deleted some resources before stopping; that partial work is deliberately not reported, so absence consistently means “no final count”, never “no work done”.
The unit depends on the command, so these must not be compared or totalled across commands. gcx resources pull is the clearest case, and its failure count is genuinely mixed: a resource fetched but not written to disk counts as one failure, and a whole resource type whose list call fails also counts as one failure. Skips there count whole resource types the server could not list. A pull failure count of 2 can therefore mean two resources or two entire types.
batch_skipped_bucket means different things per command, and whether it measures anything depends on the run. In gcx resources push and gcx resources delete a skip is recorded solely when a dry run cannot be verified server-side, so a run without --dry-run reports 0 by construction rather than as a measurement, while a dry run reports a real count. gcx resources validate is always a dry run, so its skip count is a genuine measurement on every run, and a non-zero value there is a normal outcome rather than a sign of trouble. In gcx resources pull it is also a genuine measurement on every run, counting resource types the server could not list.
dry_run is not a mutation flag. gcx resources validate always reports true and gcx resources pull always false, yet neither changes anything: pull is read-only. Read dry_run together with command, never as “this run modified resources”.
gcx resources get never reports these fields, because only the four commands listed above are instrumented. It is a read, but so is pull, which does report.

Canceled invocations

An invocation that stopped before it finished reports outcome: canceled with exit_code: 5, and error_kind present but empty, because a stop is not a kind of failure. No property is collected specifically for cancellation — and the failure fields described in Failure and authentication fields are never attached to one, for the same reason. Like every other event it is sent on a best-effort basis. For an invocation you interrupted, pressing Ctrl-C a second time ends the process immediately, before the report is sent; an invocation that stopped for another reason waits out the report like any other run, because there is no interrupt for the second Ctrl-C to follow.

Three things this value does not tell you:

It is not always your Ctrl-C. Any invocation whose exit code is 5 reports canceled, which includes a confirmation prompt you declined and a task the server itself reported as canceled. The field records that the invocation stopped early, not who stopped it.
Not every interrupted command reports it. Commands that treat an interrupt as a clean shutdown — gcx dev serve, for example — finish normally when you press Ctrl-C, so they report ok with exit_code: 0 like any other successful run.
Only Ctrl-C is caught. gcx installs a handler for SIGINT alone. A SIGTERM or a SIGKILL ends the process at once, before any report is built, so the invocation reports nothing at all. Orchestrators and CI runners usually stop a process with SIGTERM, so canceled undercounts the invocations that stopped early in those environments.

If your first-ever gcx command is one you interrupt, the notice described in The one-time notice is printed after the interrupt, because that invocation does report. The notice comes first and the export is attempted after it, so the notice records the attempt rather than a delivery: as above, the report is best-effort and may never arrive.

This moves the denominator of every outcome rate in two ways, so compare rates within a version rather than across the version where canceled first appears:

Some invocations start being counted at all. Earlier versions reported nothing for an invocation that ended on the interrupt path — exit code 5 with no error printed. Those now count towards the total, so the share of ok invocations falls without anything having got worse. This is narrower than “every Ctrl-C”: an interrupt a command turns into a clean shutdown was always reported as ok, and one that leaves a batch partially applied was always reported as a partial failure.
Some invocations change label. Exit-code-5 invocations that were already reported — a declined prompt, for instance — moved out of runtime_error with error_kind: error and into canceled with an empty error_kind. Both the runtime_error share and the volume of error_kind: error drop for the same reason, with no change in what happened.

Failure and authentication fields

For Grafana connections, gcx records the authentication category selected, such as oauth, token, basic, mtls, anonymous, or unknown, but never credentials. For some failed commands, it may also record a 4xx/5xx HTTP status or a fixed Kubernetes reason category; these details are omitted for partial failures and cancellations.

Field	Description	Example
`http_status`	The HTTP transport status of the failing request, only ever `400`–`599`. Never a status embedded inside a response body, and never a Kubernetes status code.	`403`
`k8s_reason`	The Kubernetes status reason of the failing API call, from a fixed vocabulary. Any reason outside the vocabulary is sent as `other`, never verbatim.	`NotFound`
`grafana_auth_method`	The authentication category selected for the Grafana connection. Exactly one of `oauth`, `token`, `basic`, `mtls`, `anonymous`, or `unknown`. Never a raw configured value, never credential material.	`token`

The k8s_reason vocabulary is exactly: Unauthorized, Forbidden, NotFound, AlreadyExists, Conflict, Gone, Invalid, BadRequest, MethodNotAllowed, NotAcceptable, RequestEntityTooLarge, UnsupportedMediaType, Expired, Timeout, ServerTimeout, TooManyRequests, InternalError, ServiceUnavailable, StorageReadError, plus the other sentinel.

These fields are easy to misread, so the following constraints are part of the contract:

http_status is a transport status, never a body status. Datasource queries can fail inside an HTTP 200 response, with the real error and its status embedded in the body. Such a failure sets no http_status at all. In exactly that case error_kind may still say auth_failure, because the command classifies and explains errors on the embedded status; the divergence is deliberate and must not be “fixed” by aligning either side.
Only failure statuses travel. A status outside 400–599 — a success, a redirect, anything malformed — is omitted, never coerced into the range.
Coverage is partial, so absence proves nothing. http_status is recorded where the failing client surfaces a machine-readable status: provider APIs that use the shared error helper, datasource query endpoints, datasource management commands, Knowledge Graph, Adaptive Logs, and gcx api. Clients that report failures as plain text — GCOM, Fleet, k6, Faro, Adaptive Metrics, and the assistant among them — are not instrumented, so the absence of http_status must never be read as “no HTTP failure occurred”.
Kubernetes failures report a reason, never a status. A Kubernetes API error sets k8s_reason and leaves http_status empty; the status code inside a Kubernetes error never feeds http_status.
Both failure fields are omitted for exit codes 4 and 5. A partial failure has no single causal status — the one that surfaced would stand in for many — and a canceled run is not a failure.
grafana_auth_method describes Grafana connection authentication only, never Grafana Cloud/GCOM authentication. Absent means the invocation never resolved a Grafana connection, or that it resolved several different methods (gcx config check examines every context, so it reports no single method when they differ). anonymous means a valid selection with no credential material — requests went out unauthenticated. unknown means the configured method could not be classified. A selected method whose credential is invalid or rejected reports the method: which authentication category fails is precisely what this field exists to show.
grafana_auth_method is present on every outcome — success, failure, partial failure, and cancellation — whenever the invocation resolved a Grafana connection. It follows that resolution rather than the configuration, so here too absence proves nothing: a command that never builds a Grafana connection, as Grafana Cloud–only commands do not, reports no method even under a fully configured context. gcx login reports the method it actually resolved by probing, even when the login fails after authentication was resolved.

Parse-failure fields

When the invocation fails to parse, these additional fields are set. They capture what was attempted so the team can understand the differences between what users expect and what exists. They are not populated yet: a parse failure currently reports no event at all (see Invocations that report nothing), and outcome is never parse_error today.

Field	Description	Example
`parse_error_kind`	The kind of parse failure: `unknown_command`, `unknown_flag`, or `invalid_args`.	`unknown_command`
`parse_error_parent`	The deepest valid command reached before the failure.	`dashboards`
`parse_error_token`	The first unknown toke. It’s only sent if it looks like a command name (short, lowercase, no digits, not a URL, IP address, or UUID); otherwise it’s replaced with `<redacted>`.	`serch`
`attempted_command`	The parent command plus the unknown token, truncated at the unknown token so no later arguments are included.	`dashboards serch`
`parse_error_flags`	The names of unknown flags. No flag values are sent.	`verbsoe`
`parse_error_nearest`	The nearest real command or flag name, if one is close.	`search`
`parse_error_distance`	The edit distance to the nearest real name, or `-1` if there is no near match.	`2`

The api command

The gcx api command is unique because it allows users to send an arbitrary request to the Grafana API. To get useful usage information (which endpoints, and methods are used) we need to inspect the argument values. This is an exception to our claim of not sending argument values as part of usage telemetry. We mitigate the risk of sending sensitive or identifying information by filtering argument values through a fixed vocabulary built into the binary, before anything is recorded. The filtered argument values are only used to learn which endpoints and queries our users use the api command for, so we can spot where we can add value with new gcx commands in the future.

Field	Description	Example
`api_method`	The HTTP method, from the fixed list of valid verbs.	`POST`
`api_route`	The requested route, matched against a built-in table of known Grafana API route templates. Variable segments such as UIDs and names are replaced with placeholders, and a path that matches no known route is sent as `other`. The raw path is never sent, and the query string is discarded before matching.	`/api/dashboards/uid/{uid}`
`api_datasource_types`	For datasource query requests only: the datasource plugin types named in the request body. A type is sent only when it appears on a fixed list of Grafana-published plugin IDs built into the binary (core datasource types plus the datasource plugins Grafana publishes in the catalog). Any other type, including third-party and private plugins, is sent as `other`. The body is used only to read the `queries[].datasource.type` field, and a query request whose body cannot be read that way (missing, oversized, or not a well-formed query request) is sent as `other`. The datasource UID and name, the query text, the time range, and everything else in the body are never sent.	`grafana-postgresql-datasource`

You can verify all of this for any invocation with GCX_TELEMETRY=log (see Inspect what would be sent).

Invocations that report nothing

Some invocations never emit an event:

Shell completion — the completion machinery runs on every tab-press and carries no usage signal.
gcx version
Invocations that failed to parse — an unknown command or flag reports nothing today, which is why the parse_error_* properties above are not yet populated.

How the report is sent

One invocation sends at most one report. gcx does not batch events, does not queue them for a later run, and does not start a background process that outlives the command.

Property	Value
Destination	`https://stats.grafana.org/gcx-usage-report`
Method	A single `POST` with the event as a JSON object
Attempts	One. A failed report is never retried and never stored.
Timing	Synchronous, after the command wrote its output and before the process exits
Time limit	One second for the whole exchange, including DNS, TCP, and TLS

The report is sent synchronously, so the invocation can take up to one extra second before it exits. In normal conditions the cost is much smaller, and an endpoint that refuses the connection or fails to resolve costs almost nothing, because the failure is immediate.

One case does cost the full second on every invocation: a network that drops the packets silently instead of refusing them. Some corporate firewalls do this. If you block the destination that way, each gcx invocation waits out the one-second limit before it exits. To avoid the delay, opt out with GCX_TELEMETRY=disabled instead of blocking the address. An opted-out invocation builds no event and opens no connection.

To send the report somewhere else, set GCX_TELEMETRY_ENDPOINT to another URL. This changes the destination only. It is not an opt-out, and the value is used as given.

Server-side enrichment

Reports are received by Grafana’s usage-stats service, the same service that receives usage reports from Grafana, Loki, Tempo, and Mimir. On receipt, the service adds two pieces of information derived from the connection:

A coarse geographic region (for example, a country or subdivision), taken from headers added by the CDN edge.
The network organization name from a whois lookup of the connecting IP address. For CLI traffic this typically resolves to your ISP or employer’s network.

The connecting IP address is not stored in the usage event.

Inspect what would be sent

To see exactly what gcx would report for an invocation, set GCX_TELEMETRY=log. The event is printed to stderr and nothing is sent:

GCX_TELEMETRY=log gcx dashboards list

Opt out

You can control usage statistics reporting three ways:

GCX_TELEMETRY environment variable: Set to enabled, disabled, or log. Takes precedence over everything else:

export GCX_TELEMETRY=disabled

DO_NOT_TRACK environment variable: Set to 1 or true to disable reporting, following the cross-tool DO_NOT_TRACK convention. Overridden by GCX_TELEMETRY.
Configuration file: Add a top-level diagnostics block to your gcx configuration file, with telemetry set to enabled, disabled, or log:

diagnostics:
  telemetry: disabled

Opting out disables reporting entirely. No event is constructed and nothing is sent.

The one-time notice

gcx prints a short notice to stderr the first time it reports an invocation. The notice states what is collected and how to opt out. It is printed after the command’s own output, so it never mixes into a result document on stdout.

The notice is shown at most once for each revision of its text. gcx records the revision it showed in $XDG_STATE_HOME/gcx/telemetry-notice-shown, which is ~/.local/state/gcx/telemetry-notice-shown on most systems. Delete that file to see the notice again. When the text changes in a material way, the revision changes with it, and the notice is shown once more — including to installations that already ran gcx.

Two limits are worth stating plainly:

The notice is only printed to an interactive terminal. It is skipped when stderr is not a terminal, when gcx detects a CI environment, and when gcx runs in agent mode. Those invocations still report. So a CI job or a coding agent can report usage statistics without the notice ever appearing. If you run gcx in either environment, opt out in the configuration file or in the environment of the job.
The first report is sent by the same invocation that prints the notice. The notice comes first and the report follows, in one process. So reading the notice tells you that one invocation has already reported. Every invocation after it obeys the opt-out you choose.

Agent identity

Agent identity uses the fixed labels in the agent environment reference. The GCX_AGENT_NAME override supports harnesses without a native marker. The shared AI_AGENT variable also accepts supported names. The bare AGENT variable is accepted only when its value is goose. Unknown names and version suffixes are not sent. Session markers are used only for detection; their values are not sent.

When agent mode is enabled without a known identity, agent is generic. When neither a known identity nor agent mode is present, agent is empty. This fallback applies only to usage events. It does not enable agent mode.

An explicit mode opt-out can produce is_agent=false with a non-empty agent. The label identifies the calling harness. The boolean records the active gcx mode.

Keychain credential storage

Fri, 18 Sep 2026 11:17:02 +0000

Keychain credential storage

gcx stores token-shaped credentials in the operating system credential store. It uses Keychain on macOS, Credential Manager on Windows, and Secret Service on Linux and BSD. The YAML file contains a reference to the stored credential.

The reference is bound to these values:

The canonical configuration file path.
The owner type and owner name.
The credential field.
The normalized credential destination.

A copied configuration file cannot use the stored credential. Authenticate the copied file separately.

Plaintext fallback

gcx keeps a new credential in a mode-0600 configuration file only when the credential-storage policy resolves to off, through GCX_KEYCHAIN=off or a trusted credentials.keychain: off. gcx writes a warning when it does this. See Configure credential storage.

gcx does not use plaintext fallback for these conditions:

An unavailable credential store.
A locked credential store.
A deletion of an existing credential.
A replacement of an existing credential, unless the credential-storage policy resolves to off.
A missing or rejected credential reference.
A value that is too large for the credential store.
An unknown credential store error.

Configure credential storage

The credential-storage policy is a trusted, process-wide setting. It accepts only on and off (case-insensitive after trimming); omitted means on. Configure it in a system or user configuration file:

credentials:
  keychain: off

Use off only when plaintext storage in a mode-0600 YAML file is deliberate, such as for a headless machine or CI runner whose OS credential store is not available. In off mode gcx does not contact the OS store; new and refreshed credentials are persisted in that configuration file.

GCX_KEYCHAIN can override the configuration for one invocation or a shell environment:

export GCX_KEYCHAIN=off

Policy precedence depends on how the configuration is selected (highest first):

With --config or GCX_CONFIG: GCX_KEYCHAIN, the selected file, then the default on. Selecting a file bypasses user and system configuration; an omitted field does not inherit their policy.
Otherwise: GCX_KEYCHAIN, user configuration, system configuration, then the default on.

An automatically discovered repository-local .gcx.yaml is not trusted to set this policy. gcx ignores its credentials.keychain value and warns, but still merges that file’s ordinary configuration fields. Review the file, then deliberately select it to make its policy apply: GCX_CONFIG=.gcx.yaml trusts it on every invocation, while --config .gcx.yaml trusts it only for the current command.

An invalid GCX_KEYCHAIN value warns and resolves to on, so a typo cannot silently enable plaintext storage. An invalid value in a trusted configuration file fails validation and names credentials.keychain and the source file. An invalid value in an automatically discovered local file is ignored with the same local-policy warning.

Replacing a stored credential in `off` mode

gcx does not move stored credentials back into the configuration file when you switch to off. It preserves their references and cannot read them. You have two choices for each one.

Keep the reference. Set GCX_KEYCHAIN=on for the invocation, or unset GCX_KEYCHAIN and set credentials.keychain: on in the trusted configuration file. The credential works again once the effective policy is on.

Replace the credential. Authenticate again, and gcx writes the new value in plaintext. This is not reversible: gcx cannot delete through a disabled store, so the credential you replaced stays in the OS credential store with nothing referencing it, and no gcx command can reach it again. gcx warns with cleanup guidance when this happens. Delete that stale OS-store entry yourself to finish the change, and treat that cleanup as required when you are replacing a leaked credential.

gcx cannot remove a credential that is in the credential store while off is resolved. gcx config unset on that field, and deleting the stack or Cloud entry that owns it, both fail. gcx does not drop the reference and leave the secret in the credential store, because that reports a deletion that did not happen. Set the policy to on and run the command again. When the credential store is permanently unavailable, setting it to on does not help, because gcx still cannot read the entry: edit the configuration file to remove the reference, then delete the entry through your OS credential store.

This applies only to credentials that are in the credential store. A credential that is already plaintext in the configuration file has nothing to remove from the store, so gcx config unset and entry deletion both work as usual.

Restricted execution sessions

Some agent tools run commands in a sandbox. The sandbox can allow credential reads and block credential writes. A read-only check cannot detect this state.

Before an OAuth login or token refresh, gcx writes, reads, and removes a random non-secret test value. If the check fails, gcx stops the OAuth flow. The stored OAuth session stays unchanged.

The remedy is to run the same command outside the sandbox. If an agent ran the command, use the agent approval flow to run gcx with access to the operating system credential store.

gcx detects this condition from credential-store behavior. It does not depend on an environment variable from one agent tool.

`Keychain locked`

This error means that macOS Keychain or a Linux or BSD Secret Service is available, but gcx cannot unlock it in the current session. gcx stops commands that need the credential. It does not use or write a plaintext credential. Configuration inspection and repair commands remain available.

Windows Credential Manager lock failures are not in this error class.

You can supply a credential with an environment variable when you cannot unlock the credential store. For example, you can use GRAFANA_TOKEN.

Unlock macOS Keychain

Unlock the login keychain in the same security session that runs gcx. An unlock in a different terminal or process tree might not apply to the gcx process.

Run this command in the gcx session:

security unlock-keychain

The command asks for the keychain password. Do not use the -p option. This option exposes the password in the process arguments.

Run the gcx command again after the unlock. If gcx still cannot use the keychain, run gcx from an unlocked desktop session.

Unlock a GNOME keyring in a headless session

A headless or SSH session might not have an agent that can answer the unlock prompt. First, read the lock state:

busctl --user get-property org.freedesktop.secrets \
  /org/freedesktop/secrets/collection/login \
  org.freedesktop.Secret.Collection Locked

b true means that the collection is locked.

gnome-keyring-daemon --unlock reads the password from standard input. It does not show a prompt. The --daemonize option creates a child process, so a password that you type does not reach that process. A trailing newline also prevents the unlock. Use this procedure:

stty -echo; printf 'Keyring password: '; read -r PW; stty echo; echo
printf '%s' "$PW" | gnome-keyring-daemon --replace --daemonize --unlock
unset PW

Read the lock state again. b false means that the collection is unlocked.

If the state does not change, a service manager might own the org.freedesktop.secrets name. Stop the service, and run the unlock procedure again:

systemctl --user stop gnome-keyring-daemon.service gnome-keyring-daemon.socket

A credential was `rejected before network use`

This error means that gcx did not send the credential. The error can have one of these causes:

The keychain reference is missing or belongs to a different source.
The credential destination changed.
The keychain is locked.
An environment credential is paired with an automatically discovered repository destination.

If the keychain is locked, gcx shows the Keychain locked error and the procedures on this page apply.

For another cause, review the file and run the exact repair command from the error. You can use gcx config edit user or gcx config edit --config "<path>" when the error gives that command. Then, re-authenticate, replace the field, or unset the field.

An explicit configuration path does not make a missing, foreign, or destination-mismatched keychain reference valid.

User guides

Mon, 12 Oct 2026 15:20:54 +0000

`gcx` user guides

Refer to the following documents to learn about specific workflows to use gcx:

Dashboards as code
Use gcx to manage dashboards as code.
Explore and modify resources
Use gcx to explore and modify resources.
Manage resources
Use gcx to manage resources.
Lint resources
Use gcx to lint resources.
Diagnose missing telemetry
Use gcx to diagnose missing telemetry.

CLI reference

Wed, 14 Oct 2026 13:20:26 +0000

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

`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

  -h, --help   help for gcx

Shared flags

      --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

  -h, --help   help for agent

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx agent prune [flags]

Flags

  -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 agent skills`

Install the canonical portable gcx Agent Skills bundle for .agents-compatible agent harnesses.

Flags

  -h, --help   help for skills

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx agent skills get SKILL [REFERENCE] [flags]

Examples

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

  -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 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.

gcx agent skills install [SKILL]... [flags]

Examples

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

      --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 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.

gcx agent skills list [flags]

Examples

gcx agent skills list
  gcx agent skills list -o json

Flags

      --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 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.

gcx agent skills uninstall [SKILL]... [flags]

Examples

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

      --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 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.

gcx agent skills update [SKILL]... [flags]

Examples

gcx agent skills update
  gcx agent skills update --dry-run
  gcx agent skills update setup-gcx debug-with-grafana

Flags

      --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 agento11y`

Manage Grafana Agent Observability resources

Flags

  -h, --help   help for agento11y

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y agents`

Query Agent Observability agent catalog.

Flags

  -h, --help   help for agents

Inherits --config from gcx agento11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y agents get`

Get the full agent definition. Use –version for a specific version.

gcx agento11y agents get <agent-name> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y agents list`

List agents.

gcx agento11y agents list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y agents list-versions`

List version history for an agent.

gcx agento11y agents list-versions <agent-name> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y collections`

Manage named groups of saved conversations.

Flags

  -h, --help   help for collections

Inherits --config from gcx agento11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y collections add-conversations`

Add one or more saved conversations to a collection.

gcx agento11y collections add-conversations <collection-id> <saved-id>... [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y collections create`

Create a new collection.

gcx agento11y collections create [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y collections delete`

Delete collections.

gcx agento11y collections delete COLLECTION-ID... [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y collections get`

Get a single collection.

gcx agento11y collections get <collection-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y collections list`

List collections.

gcx agento11y collections list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y collections list-conversations`

List saved conversations belonging to a collection.

gcx agento11y collections list-conversations <collection-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y collections remove-conversation`

Remove a single saved conversation from a collection.

gcx agento11y collections remove-conversation <collection-id> <saved-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y collections update`

Patch a collection’s name and/or description.

gcx agento11y collections update <collection-id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y conversations`

Query Agent Observability conversations.

Flags

  -h, --help   help for conversations

Inherits --config from gcx agento11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y conversations annotate`

Annotate a conversation.

gcx agento11y conversations annotate <conversation-id> [flags]

Examples

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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y conversations get`

Get a single conversation with all generations.

gcx agento11y conversations get <conversation-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y conversations list`

List conversations.

gcx agento11y conversations list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y conversations list-annotations`

List annotations for a conversation.

gcx agento11y conversations list-annotations <conversation-id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx agento11y conversations search [flags]

Examples

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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y evaluators`

Manage evaluator definitions (LLM judge, regex, heuristic).

Flags

  -h, --help   help for evaluators

Inherits --config from gcx agento11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y evaluators delete`

Delete evaluators.

gcx agento11y evaluators delete ID... [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y evaluators get`

Get a single evaluator definition.

gcx agento11y evaluators get <evaluator-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y evaluators list`

List evaluator definitions.

gcx agento11y evaluators list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y evaluators test`

Run an evaluator against a generation without persisting results.

gcx agento11y evaluators test [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y evaluators upsert`

Create or update an evaluator from a file.

gcx agento11y evaluators upsert [flags]

Examples

# 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 <template-id> -o yaml > evaluator.yaml
  gcx agento11y evaluators upsert -f evaluator.yaml

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments`

Manage eval experiment runs.

Flags

  -h, --help   help for experiments

Inherits --config from gcx agento11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments cancel`

Cancel a running experiment.

gcx agento11y experiments cancel <run-id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments create`

Create a new experiment from a JSON or YAML file.

gcx agento11y experiments create [flags]

Examples

# Create from a YAML file.
  gcx agento11y experiments create -f experiment.yaml

  # Create from stdin.
  cat experiment.json | gcx agento11y experiments create -f -

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments get`

Get a single experiment by run ID.

gcx agento11y experiments get <run-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments get-report`

Get the aggregate report for an experiment.

gcx agento11y experiments get-report <run-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments list`

List experiments.

gcx agento11y experiments list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments list-scores`

List scores produced by an experiment.

gcx agento11y experiments list-scores <run-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments list-trials`

List test case trials for an experiment.

gcx agento11y experiments list-trials <run-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx agento11y experiments pull <run-id> [flags]

Examples

# Pull experiment metadata, aggregate report, trials, and conversation IDs.
  gcx agento11y experiments pull <run-id> -d ./exports/run-1

  # Also download every referenced conversation and artifact with reduced request pressure.
  gcx agento11y experiments pull <run-id> -d ./exports/run-1 --include-conversations --include-artifacts --concurrency 4

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments test-suites`

Manage experiment test suites.

Aliases: suites

Flags

  -h, --help   help for test-suites

Inherits --config from gcx agento11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments test-suites cases`

Manage test cases in a suite version.

Flags

  -h, --help   help for cases

Inherits --config from gcx agento11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments test-suites cases delete`

Delete a test case from a mutable suite version.

gcx agento11y experiments test-suites cases delete <suite-id> <version> <test-case-id> [flags]

Flags

      --force   Skip confirmation prompt
  -h, --help    help for delete

Inherits --config from gcx agento11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments test-suites cases get`

Get a single test case.

gcx agento11y experiments test-suites cases get <suite-id> <version> <test-case-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments test-suites cases list`

List test cases in a suite version.

gcx agento11y experiments test-suites cases list <suite-id> <version> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments test-suites cases update`

Update a test case from a JSON or YAML file.

gcx agento11y experiments test-suites cases update <suite-id> <version> <test-case-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments test-suites cases upsert`

Create or replace a test case from a JSON or YAML file.

gcx agento11y experiments test-suites cases upsert <suite-id> <version> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments test-suites create`

Create a test suite.

gcx agento11y experiments test-suites create [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments test-suites get`

Get a single test suite.

gcx agento11y experiments test-suites get <suite-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments test-suites list`

List test suites.

gcx agento11y experiments test-suites list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments test-suites update`

Update a test suite.

gcx agento11y experiments test-suites update <suite-id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments test-suites versions`

Manage test suite versions.

Flags

  -h, --help   help for versions

Inherits --config from gcx agento11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments test-suites versions create`

Create a draft test suite version.

gcx agento11y experiments test-suites versions create <suite-id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments test-suites versions publish`

Publish a draft test suite version.

gcx agento11y experiments test-suites versions publish <suite-id> <version> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments trials`

Manage experiment test case trials.

Flags

  -h, --help   help for trials

Inherits --config from gcx agento11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments trials create`

Create or upsert a test case trial from a JSON or YAML file.

gcx agento11y experiments trials create <run-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments trials get`

Get a single test case trial.

gcx agento11y experiments trials get <trial-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments trials list-artifacts`

List artifacts for a test case trial.

gcx agento11y experiments trials list-artifacts <trial-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments trials list-scores`

List scores for a test case trial.

gcx agento11y experiments trials list-scores <trial-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments trials update`

Update a test case trial from a JSON or YAML file.

gcx agento11y experiments trials update <trial-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y experiments update`

Update an experiment’s mutable fields.

gcx agento11y experiments update <run-id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y generations`

Inspect individual LLM generations.

Flags

  -h, --help   help for generations

Inherits --config from gcx agento11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y generations get`

Get a generation’s full detail: input, output, model, tokens, and tool calls.

gcx agento11y generations get <generation-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y generations list-scores`

List evaluation scores produced by online rules for a generation.

gcx agento11y generations list-scores <generation-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for guards

Inherits --config from gcx agento11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y guards create`

Create a hook rule (guard) from a file.

gcx agento11y guards create [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y guards delete`

Delete hook rules (guards).

gcx agento11y guards delete ID... [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y guards get`

Get a single hook rule (guard).

gcx agento11y guards get <rule-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y guards list`

List hook rules (guards).

gcx agento11y guards list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y guards update`

Update a hook rule (guard) from a file. Full replace; omitted fields reset to defaults.

gcx agento11y guards update <rule-id> [flags]

Examples

# Update a guard from a YAML file.
  gcx agento11y guards update my-guard -f guard.yaml

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for judge

Inherits --config from gcx agento11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y judge list-models`

List available judge models.

gcx agento11y judge list-models --provider <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y judge list-providers`

List available judge providers.

gcx agento11y judge list-providers [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for model-rates

Inherits --config from gcx agento11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx agento11y model-rates create [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx agento11y model-rates delete [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx agento11y model-rates list [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y rules`

Manage rules that route generations to evaluators.

Flags

  -h, --help   help for rules

Inherits --config from gcx agento11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y rules create`

Create an evaluation rule from a file.

gcx agento11y rules create [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y rules delete`

Delete evaluation rules.

gcx agento11y rules delete ID... [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y rules get`

Get a single evaluation rule.

gcx agento11y rules get <rule-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y rules list`

List evaluation rules.

gcx agento11y rules list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx agento11y rules list-scores <rule-id> [flags]

Examples

# Recent scores (summary table; no explanations).
  gcx agento11y rules list-scores <rule-id>

  # Failing scores with explanations.
  gcx agento11y rules list-scores <rule-id> --passed=false -o json

  # Wide table with truncated explanation column.
  gcx agento11y rules list-scores <rule-id> --passed=false -o wide

  # Scoped to one evaluator and time window.
  gcx agento11y rules list-scores <rule-id> --evaluator-id <id> --from 2026-04-01T00:00:00Z --to 2026-04-02T00:00:00Z -o json

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y rules update`

Update an evaluation rule from a file.

gcx agento11y rules update <rule-id> [flags]

Examples

# Update a rule from a YAML file.
  gcx agento11y rules update my-rule -f rule.yaml

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y saved-conversations`

Bookmark live conversations as fixed inputs for evaluation runs.

Flags

  -h, --help   help for saved-conversations

Inherits --config from gcx agento11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y saved-conversations collections`

List collections that contain a saved conversation.

gcx agento11y saved-conversations collections <saved-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y saved-conversations delete`

Delete saved conversations.

gcx agento11y saved-conversations delete SAVED-ID... [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y saved-conversations get`

Get a single saved conversation.

gcx agento11y saved-conversations get <saved-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y saved-conversations list`

List saved conversations.

gcx agento11y saved-conversations list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx agento11y saved-conversations save <conversation-id> [flags]

Examples

# 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

  -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-<conversation-id>
      --tag stringArray   Tag in key=value form (repeatable)

Inherits --config from gcx agento11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y templates`

Browse reusable evaluator blueprints (global and tenant-scoped).

Flags

  -h, --help   help for templates

Inherits --config from gcx agento11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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’.

gcx agento11y templates get <template-id> [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y templates list`

List eval templates.

gcx agento11y templates list [flags]

Examples

# List all templates.
  gcx agento11y templates list

  # Filter by scope.
  gcx agento11y templates list --scope global

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx agento11y templates list-versions`

List version history for an eval template.

gcx agento11y templates list-versions <template-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert`

Manage Grafana alert rules and alert groups

Flags

  -h, --help   help for alert

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert contact-points`

Manage Grafana alerting contact points.

Aliases: contact-point

Flags

  -h, --help   help for contact-points

Inherits --config from gcx alert.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert contact-points create`

Create a new contact point.

gcx alert contact-points create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert contact-points delete`

Delete a contact point by UID.

gcx alert contact-points delete UID [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert contact-points export`

Export all contact points in provisioning format.

gcx alert contact-points export [flags]

Flags

      --format string   Export format: yaml, json, or hcl (default "yaml")
  -h, --help            help for export

Inherits --config from gcx alert.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert contact-points get`

Get a single contact point by UID.

gcx alert contact-points get UID [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert contact-points list`

List alerting contact points.

gcx alert contact-points list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert contact-points update`

Update an existing contact point by UID.

gcx alert contact-points update UID [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for groups

Inherits --config from gcx alert.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert groups get`

Get a single alert rule group.

gcx alert groups get NAME [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert groups list`

List alert rule groups.

gcx alert groups list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert groups status`

Show alert rule group status.

gcx alert groups status [NAME] [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert instances`

Manage alert instances.

Aliases: alerts

Flags

  -h, --help   help for instances

Inherits --config from gcx alert.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert instances list`

List alert instances.

gcx alert instances list [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert mute-timings`

Manage Grafana alerting mute timings.

Aliases: mute-timing

Flags

  -h, --help   help for mute-timings

Inherits --config from gcx alert.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert mute-timings create`

Create a new mute timing.

gcx alert mute-timings create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert mute-timings delete`

Delete a mute timing by name.

gcx alert mute-timings delete NAME [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert mute-timings export`

Export mute timings in provisioning format.

gcx alert mute-timings export [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert mute-timings get`

Get a mute timing by name.

gcx alert mute-timings get NAME [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert mute-timings list`

List mute timings.

gcx alert mute-timings list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert mute-timings update`

Update an existing mute timing by name.

gcx alert mute-timings update NAME [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for notification-history

Inherits --config from gcx alert.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert notification-history list`

List notification delivery history.

gcx alert notification-history list [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx alert notification-history list-alerts [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert notification-policies`

Manage the Grafana alerting notification policy tree.

Aliases: notification-policy, policies

Flags

  -h, --help   help for notification-policies

Inherits --config from gcx alert.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert notification-policies export`

Export the notification policy tree in provisioning format.

gcx alert notification-policies export [flags]

Flags

      --format string   Export format: yaml, json, or hcl (default "yaml")
  -h, --help            help for export

Inherits --config from gcx alert.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert notification-policies get`

Get the notification policy tree.

gcx alert notification-policies get [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert notification-policies reset`

Reset the notification policy tree to its default.

gcx alert notification-policies reset [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert notification-policies set`

Replace the entire notification policy tree.

gcx alert notification-policies set [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for routing-trees

Inherits --config from gcx alert.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx alert routing-trees create -f <file> [flags]

Examples

gcx alert routing-trees create -f team-a.yaml

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

gcx alert routing-trees delete <name> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx alert routing-trees get <name> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert routing-trees list`

List routing trees, including the default tree.

Aliases: ls

gcx alert routing-trees list [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx alert routing-trees update <name> -f <file> [flags]

Examples

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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for ruler

Inherits --config from gcx alert.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert ruler groups`

Manage datasource-managed (Mimir/Loki ruler) rule groups.

Aliases: group

Flags

  -h, --help   help for groups

Inherits --config from gcx alert.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert ruler groups delete`

Delete a ruler rule group.

gcx alert ruler groups delete NAMESPACE GROUP [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert ruler groups get`

Get a ruler rule group (YAML by default, round-trips into upsert).

gcx alert ruler groups get NAMESPACE GROUP [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert ruler groups list`

List ruler rule groups.

gcx alert ruler groups list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx alert ruler groups upsert NAMESPACE [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert ruler namespaces`

Manage datasource-managed (Mimir/Loki ruler) namespaces.

Aliases: namespace

Flags

  -h, --help   help for namespaces

Inherits --config from gcx alert.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert ruler namespaces delete`

Delete a ruler namespace and all rule groups in it.

gcx alert ruler namespaces delete NAMESPACE [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert ruler namespaces list`

List ruler namespaces with group and rule counts.

gcx alert ruler namespaces list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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:

  gcx resources pull alertrules -p ./rules   # export rules to disk
  gcx resources push -p ./rules              # apply edited rules
  gcx resources delete alertrules/<name>     # delete a rule

Flags

  -h, --help   help for rules

Inherits --config from gcx alert.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert rules get`

Get a single alert rule.

gcx alert rules get UID [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert rules list`

List alert rules.

gcx alert rules list [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

  gcx alert state-history list --rule <uid> --from now-24h
  gcx alert state-history list --label severity=critical --limit 200

Flags

  -h, --help   help for state-history

Inherits --config from gcx alert.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert state-history list`

List recorded alert state transitions.

gcx alert state-history list [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert templates`

Manage Grafana alerting notification templates.

Aliases: template

Flags

  -h, --help   help for templates

Inherits --config from gcx alert.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert templates delete`

Delete a notification template by name.

gcx alert templates delete NAME [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert templates get`

Get a notification template by name.

gcx alert templates get NAME [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx alert templates list`

List notification templates.

gcx alert templates list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx alert templates upsert [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx api PATH [flags]

Examples

# 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

  -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

      --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 appo11y`

Manage Grafana App Observability settings

Flags

  -h, --help   help for appo11y

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx appo11y operations`

Rank and inspect operations (span names) across App Observability services

Flags

  -h, --help   help for operations

Inherits --config from gcx appo11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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).

gcx appo11y operations get <operation> --service <service> [--namespace ns] [flags]

Examples

# 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

  -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 "<namespace>/<name>" 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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx appo11y operations list [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx appo11y overrides`

Manage App Observability metrics generator overrides.

Flags

  -h, --help   help for overrides

Inherits --config from gcx appo11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx appo11y overrides get`

Get the App Observability metrics generator overrides.

gcx appo11y overrides get [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx appo11y overrides update`

Update App Observability metrics generator overrides from a file.

gcx appo11y overrides update [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx appo11y services`

Inspect Application Observability services discovered from telemetry

Flags

  -h, --help   help for services

Inherits --config from gcx appo11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx appo11y services get <service> [--namespace ns] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx appo11y services list [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx appo11y services list-labels <service> [--namespace ns] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx appo11y services list-operations <service> [--namespace ns] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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”.

gcx appo11y services map <service> [--namespace ns] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx appo11y settings`

Manage App Observability plugin settings.

Flags

  -h, --help   help for settings

Inherits --config from gcx appo11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx appo11y settings get`

Get App Observability plugin settings.

gcx appo11y settings get [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx appo11y settings update`

Update App Observability plugin settings.

gcx appo11y settings update [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

Flags

  -h, --help   help for assistant

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx assistant conversation`

Fetch conversation metadata and message history without sending a new prompt.

Flags

  -h, --help   help for conversation

Inherits --config from gcx assistant.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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’.

gcx assistant conversation get <id-or-url> [flags]

Examples

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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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’.

gcx assistant conversation list [flags]

Examples

gcx assistant conversation list
  gcx assistant conversation list --source assistant --limit 25
  gcx assistant conversation list -o json

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx assistant investigations`

Manage Grafana Assistant investigations.

Flags

  -h, --help   help for investigations

Inherits --config from gcx assistant.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx assistant investigations cancel`

Cancel a running investigation.

gcx assistant investigations cancel <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx assistant investigations create`

Create a new investigation. On v2-enabled stacks, uses the v2 API with –instruction; falls back to legacy create otherwise.

gcx assistant investigations create [flags]

Examples

gcx assistant investigations create --instruction="Debug API latency spike" --team=sre

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx assistant investigations get <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx assistant investigations get-narrative <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx assistant investigations list`

List investigations. Auto-detects whether the stack supports the v2 investigations API and uses the richer endpoint when available.

gcx assistant investigations list [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx assistant investigations list-evidence <investigation-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx assistant investigations list-messages <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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).

gcx assistant investigations list-tool-calls <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx assistant investigations mode`

Change the autonomy mode of a running v2 investigation. Valid modes: low, medium, high.

gcx assistant investigations mode <id> <mode> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx assistant investigations pause`

Pause a v2 investigation. Unlike cancel, paused investigations can be resumed.

gcx assistant investigations pause <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx assistant investigations resume`

Resume a paused v2 investigation.

gcx assistant investigations resume <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx assistant investigations share`

Widen the visibility of a v2 investigation. Sharing is additive — teams cannot be removed.

gcx assistant investigations share <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

# 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 <token>"

Flags

  -h, --help   help for mcp-servers

Inherits --config from gcx assistant.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx assistant mcp-servers create [flags]

Examples

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 <token>"

  gcx assistant mcp-servers create --file server.yaml --if-not-exists

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx assistant mcp-servers delete <id-or-name> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx assistant mcp-servers get`

Get an Assistant MCP server.

gcx assistant mcp-servers get <id-or-name> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx assistant mcp-servers list [flags]

Examples

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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx assistant mcp-servers update <id-or-name> [flags]

Examples

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=<token>"

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx assistant prompt <message> [flags]

Examples

gcx assistant prompt "What alerts are firing?"
  gcx assistant prompt "Show CPU usage" --json
  gcx assistant prompt "Follow up" --continue

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx cloud`

Manage your Grafana Cloud resources

Flags

  -h, --help   help for cloud

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx cloud login [flags]

Examples

gcx cloud login
  gcx cloud login --cloud-token glc_abc123

Flags

      --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 cloud orgs`

Discover your Grafana Cloud organisations

Flags

  -h, --help   help for orgs

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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 .

gcx cloud orgs list [flags]

Examples

gcx cloud orgs list
  gcx cloud orgs list -o json
  gcx cloud orgs list --json slug,role

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx cloud stacks`

Manage Grafana Cloud stacks (list, create, update, delete)

Flags

  -h, --help   help for stacks

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx cloud stacks create [flags]

Examples

gcx cloud stacks create --org example-org --name my-stack --slug mystack --region us --dry-run

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx cloud stacks delete <stack-slug> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx cloud stacks get`

Get details of a single stack.

gcx cloud stacks get <stack-slug> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx cloud stacks list`

List stacks in an organisation.

gcx cloud stacks list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx cloud stacks list-regions`

List available regions for stack creation.

gcx cloud stacks list-regions [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx cloud stacks update <stack-slug> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx commands [flags]

Flags

      --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 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

  -h, --help   help for completion

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx completion bash

Flags

  -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 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.

gcx completion fish [flags]

Flags

  -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 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.

gcx completion powershell [flags]

Flags

  -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 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.

gcx completion zsh [flags]

Flags

  -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 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:

System configuration: $XDG_CONFIG_DIRS/gcx/config.yaml (for example, /etc/xdg/gcx/config.yaml).
User configuration: $HOME/.config/gcx/config.yaml, then the platform $XDG_CONFIG_HOME fallback.
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

  -h, --help   help for config

Shared flags

      --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 config check`

Check configured contexts for issues.

Without –context, checks every configured context. With –context, checks only the selected context.

gcx config check [flags]

Examples

gcx config check
	gcx config check --context production

Flags

  -h, --help   help for check

Inherits --config, --context from gcx config.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx config current-context`

Display the current context name.

gcx config current-context [flags]

Examples

gcx config current-context

Flags

  -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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx config edit [type] [flags]

Flags

      --create   Create the config file if it doesn't exist
  -h, --help     help for edit

Inherits --config, --context from gcx config.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx config list-contexts`

List the contexts defined in the configuration.

gcx config list-contexts [flags]

Examples

gcx config list-contexts

Flags

  -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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx config path`

Display all config files that contribute to the merged configuration, ordered by priority.

gcx config path [flags]

Flags

  -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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx config set PROPERTY_NAME PROPERTY_VALUE [flags]

Examples

# 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

      --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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx config unset PROPERTY_NAME [flags]

Examples

# 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

      --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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

gcx config use-context [CONTEXT_NAME] [flags]

Examples

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

      --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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx config view`

Display the current configuration

gcx config view [flags]

Examples

gcx config view

Flags

  -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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx dashboards`

Create, read, update, delete, and search Grafana dashboards via the Kubernetes-compatible Grafana API.

Flags

  -h, --help   help for dashboards

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx dashboards create`

Create a dashboard from a manifest

gcx dashboards create -f <file> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx dashboards delete`

Delete a dashboard

Aliases: rm

gcx dashboards delete <name> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx dashboards get`

Get a Grafana dashboard by its Kubernetes resource name.

The name argument equals the legacy Dashboard UID.

gcx dashboards get <name> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx dashboards list`

List dashboards

Aliases: ls

gcx dashboards list [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx dashboards list-versions`

List dashboard version history

gcx dashboards list-versions <name> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx dashboards search [query] [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx dashboards snapshot`

Render one or more Grafana dashboards or individual panels as PNG images using the Grafana Image Renderer.

gcx dashboards snapshot <name> [name...] [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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:

  gcx dashboards get <name> -o yaml > dashboard.yaml
  # edit dashboard.yaml
  gcx dashboards update <name> -f dashboard.yaml

gcx dashboards update <name> -f <file> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx dashboards versions`

Manage dashboard version history

Flags

  -h, --help   help for versions

Inherits --config from gcx dashboards.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx dashboards versions restore`

Restore a dashboard to a previous version

gcx dashboards versions restore <name> <version> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources`

List, inspect, and query Grafana datasources. Use top-level signal commands (metrics, logs, traces, profiles) for datasource-specific queries.

Flags

  -h, --help   help for datasources

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources athena`

Query Amazon Athena datasources

Flags

  -h, --help   help for athena

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources athena describe-table`

List the column names of the specified table. Only names are returned, not types or other schema details.

gcx datasources athena describe-table TABLE [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources athena list-catalogs`

List available Athena data catalogs

gcx datasources athena list-catalogs [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources athena list-databases`

List databases in an Athena data catalog

gcx datasources athena list-databases [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources athena list-tables`

List tables in an Athena database

gcx datasources athena list-tables [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources athena query [EXPR] [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources azuremonitor`

Query Azure Monitor datasources

Flags

  -h, --help   help for azuremonitor

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources azuremonitor list-metrics`

List the Azure Monitor metric definitions available for a resource, including each metric’s primary aggregation, unit, and dimensions.

gcx datasources azuremonitor list-metrics [flags]

Examples

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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources azuremonitor list-resource-groups`

List the resource groups in an Azure subscription via an Azure Monitor datasource.

gcx datasources azuremonitor list-resource-groups [flags]

Examples

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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources azuremonitor list-resources`

List the Azure resources in a subscription, optionally scoped to a resource group, via an Azure Monitor datasource.

gcx datasources azuremonitor list-resources [flags]

Examples

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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources azuremonitor list-subscriptions`

List the Azure subscriptions the Azure Monitor datasource’s credentials can access.

gcx datasources azuremonitor list-subscriptions [flags]

Examples

gcx datasources azuremonitor list-subscriptions -d UID
  gcx datasources azuremonitor list-subscriptions -d UID -o json

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources azuremonitor logs`

Query Log Analytics workspaces with KQL

Flags

  -h, --help   help for logs

Inherits --config from gcx datasources azuremonitor.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources azuremonitor logs query KQL [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources azuremonitor query [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources azuremonitor resource-graph`

Query Azure Resource Graph with KQL

Flags

  -h, --help   help for resource-graph

Inherits --config from gcx datasources azuremonitor.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources azuremonitor resource-graph query KQL [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources bigquery`

Query BigQuery datasources

Flags

  -h, --help   help for bigquery

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources bigquery describe-table TABLE [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources bigquery list-datasets [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources bigquery list-tables [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources bigquery query [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources clickhouse`

Query ClickHouse datasources

Flags

  -h, --help   help for clickhouse

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources clickhouse describe-table`

Show column details including name, type, default, and comment for each column in the specified table.

gcx datasources clickhouse describe-table TABLE [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources clickhouse list-tables [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources clickhouse query [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources cloudmonitoring`

Query Google Cloud Monitoring datasources

Flags

  -h, --help   help for cloudmonitoring

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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).

gcx datasources cloudmonitoring list-metrics [flags]

Examples

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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources cloudmonitoring list-projects`

List the Google Cloud projects the datasource’s credentials can access.

gcx datasources cloudmonitoring list-projects [flags]

Examples

gcx datasources cloudmonitoring list-projects -d UID
  gcx datasources cloudmonitoring list-projects -d UID -o json

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources cloudmonitoring query [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources cloudwatch`

Query AWS CloudWatch datasources

Flags

  -h, --help   help for cloudwatch

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources cloudwatch list-accounts [flags]

Examples

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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources cloudwatch list-dimensions`

List the dimension keys available for a CloudWatch metric within a namespace and region.

gcx datasources cloudwatch list-dimensions [flags]

Examples

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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources cloudwatch list-metrics`

List the CloudWatch metrics available within a namespace and region from a CloudWatch datasource.

gcx datasources cloudwatch list-metrics [flags]

Examples

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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources cloudwatch list-namespaces`

List the CloudWatch namespaces visible in the given region from a CloudWatch datasource.

gcx datasources cloudwatch list-namespaces [flags]

Examples

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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources cloudwatch list-regions`

List the AWS regions exposed by the configured CloudWatch datasource.

gcx datasources cloudwatch list-regions [flags]

Examples

gcx datasources cloudwatch list-regions -d UID
  gcx datasources cloudwatch list-regions -d UID -o json

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources cloudwatch query [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources create [flags]

Examples

# 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

      --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 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).

gcx datasources delete UID... [flags]

Examples

# 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

      --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 datasources elasticsearch`

Query Elasticsearch datasources

Flags

  -h, --help   help for elasticsearch

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources elasticsearch list-fields [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources elasticsearch list-indices [flags]

Examples

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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources elasticsearch metrics [EXPR] [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources elasticsearch query [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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 -.

gcx datasources get UID [flags]

Examples

# Human-readable detail
	gcx datasources get my-prometheus

	# Apply-ready manifest (round-trips into update -f -)
	gcx datasources get my-prometheus -o yaml

Flags

      --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 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)

gcx datasources health [UID] [flags]

Examples

# 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

      --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 datasources infinity`

Query Infinity datasources (JSON, CSV, XML, GraphQL from any URL)

Flags

  -h, --help   help for infinity

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources infinity query [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources influxdb`

Query InfluxDB datasources

Flags

  -h, --help   help for influxdb

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources influxdb list-field-keys`

List field keys from an InfluxDB datasource. Only supported in InfluxQL mode.

gcx datasources influxdb list-field-keys [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources influxdb list-measurements`

List measurement names from an InfluxDB datasource.

gcx datasources influxdb list-measurements [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources influxdb list-tag-keys`

List tag keys from an InfluxDB datasource. Only supported in InfluxQL mode.

gcx datasources influxdb list-tag-keys [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources influxdb list-tag-values`

List tag values for a given key from an InfluxDB datasource. Only supported in InfluxQL mode.

gcx datasources influxdb list-tag-values [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources influxdb query [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources list`

List all datasources configured in Grafana. Filter by type and/or name (case-insensitive substring match).

gcx datasources list [flags]

Examples

# 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

      --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 datasources loki`

Query Loki datasources

Flags

  -h, --help   help for loki

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources loki labels`

List all labels or get values for a specific label from a Loki datasource.

gcx datasources loki labels [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources loki metrics [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources loki query [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources loki series`

List log streams (series) from a Loki datasource using LogQL stream selectors. At least one –match selector is required.

gcx datasources loki series [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources mssql`

Query Microsoft SQL Server datasources

Flags

  -h, --help   help for mssql

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources mssql describe-table TABLE [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources mssql list-tables [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources mssql query [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources mysql`

Query MySQL datasources

Flags

  -h, --help   help for mysql

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources mysql describe-table TABLE [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources mysql list-tables [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources mysql query [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources opensearch`

Query OpenSearch datasources

Flags

  -h, --help   help for opensearch

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources opensearch list-fields [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources opensearch list-indices [flags]

Examples

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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources opensearch metrics [EXPR] [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

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.

gcx datasources opensearch query [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources pinot`

Query StarTree Pinot datasources

Flags

  -h, --help   help for pinot

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources pinot query [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources postgres`

Query PostgreSQL datasources

Flags

  -h, --help   help for postgres

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources postgres describe-table TABLE [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources postgres list-tables [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources postgres query [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources prometheus`

Query Prometheus datasources

Flags

  -h, --help   help for prometheus

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources prometheus labels`

List all labels or get values for a specific label from a Prometheus datasource.

gcx datasources prometheus labels [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources prometheus metadata`

Get metadata (type, help text) for metrics from a Prometheus datasource.

gcx datasources prometheus metadata [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources prometheus query [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources prometheus search-label-names [TERM...] [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

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.

gcx datasources prometheus search-label-values LABEL [TERM...] [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources prometheus search-metric-names TERM... [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources pyroscope`

Query Pyroscope datasources

Flags

  -h, --help   help for pyroscope

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources pyroscope data-range [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for exemplars

Inherits --config from gcx datasources pyroscope.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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”}’).

gcx datasources pyroscope exemplars profile [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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”}’).

gcx datasources pyroscope exemplars span [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx datasources pyroscope labels`

List all labels or get values for a specific label from a Pyroscope datasource.

gcx datasources pyroscope labels [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources pyroscope list-profile-types [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources pyroscope metrics [EXPR] [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources pyroscope query [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources pyroscope query-anomalies [EXPR] [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources pyroscope series [SELECTOR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources query DATASOURCE_UID [EXPR] [flags]

Examples

# 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

      --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 datasources schemas`

Inspect the configuration schema of a datasource plugin type, to author manifests correctly.

Flags

  -h, --help   help for schemas

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources schemas get [flags]

Examples

# 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

      --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 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.

gcx datasources schemas list [flags]

Examples

# List available datasource plugin types
	gcx datasources schemas list

	# As JSON
	gcx datasources schemas list -o json

Flags

      --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 datasources tempo`

Query Tempo datasources

Flags

  -h, --help   help for tempo

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources tempo baseline TRACE_ID [flags]

Examples

# Find a small shortlist; COHORT is an already-verified TraceQL spanset
  gcx traces baseline --context prod -d UID <seed-id> --filter "$COHORT" --limit 5

  # With no additional known scope, use the seed-derived defaults
  gcx traces baseline --context prod -d UID <seed-id> --limit 5

  # Inspect selected candidates; repeat for a small batch, not every result
  gcx traces get --context prod -d UID <candidate-id> --llm -o agents

  # Assess a candidate with an exploratory diff (seed minus candidate)
  gcx traces diff --context prod -d UID <candidate-id> <seed-id>

  # Set the candidate window; this does not bound the seed trace lookup
  gcx traces baseline --context prod -d UID <seed-id> --filter "$COHORT" --limit 5 \
    --from 2026-01-15T08:00:00Z --to 2026-01-15T09:00:00Z

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources tempo diff TRACE_A TRACE_B [flags]

Examples

# Compare an already-known pair directly; baseline search is not required
  gcx traces diff --context prod -d UID <baseline-id> <comparison-id>

  # Inspect a plausible candidate before using a diff to assess it
  gcx traces get --context prod -d UID <candidate-id> --llm -o agents

  # Assess selected candidates against the seed; repeat only as useful
  gcx traces diff --context prod -d UID <candidate-id> <seed-id>

  # Bound BOTH trace lookups, including an older candidate, and allow spilling
  gcx traces diff --context prod -d UID <candidate-id> <seed-id> \
    --from 2026-01-15T08:00:00Z --to 2026-01-15T10:00:00Z -o agents

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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).

gcx datasources tempo get TRACE_ID [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

gcx datasources tempo labels [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources tempo metrics [TRACEQL] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

gcx datasources tempo query [TRACEQL] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx datasources update UID [flags]

Examples

# 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

      --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 dbo11y`

Inspect Grafana Database Observability instances and query performance

Flags

  -h, --help   help for dbo11y

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx dbo11y instances`

Inspect Database Observability instances discovered from telemetry

Flags

  -h, --help   help for instances

Inherits --config from gcx dbo11y.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx dbo11y instances get <name> [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx dbo11y instances list [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for dev

Shared flags

      --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 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.

gcx dev generate [FILE_PATH]... [flags]

Examples

# 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

  -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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx dev import [RESOURCE_SELECTOR]... [flags]

Examples

# 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

      --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 dev lint`

Lint Grafana resources.

Flags

  -h, --help   help for lint

Inherits --config, --context from gcx dev.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx dev lint list-rules [flags]

Examples

# List built-in rules:

	gcx dev lint list-rules

	# List built-in and custom rules:

	gcx dev lint list-rules -r ./custom-rules

Flags

  -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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx dev lint new RESOURCE_TYPE NAME [flags]

Examples

# 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

  -c, --category string   Rule category (default "idiomatic")
  -h, --help              help for new
  -o, --output string     Output directory

Inherits --config, --context from gcx dev.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx dev lint run PATH... [flags]

Examples

# 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

      --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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx dev lint test PATH... [flags]

Examples

# Run all tests in a directory:

	gcx dev lint test ./internal/linter/bundle/gcx/

Flags

      --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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx dev scaffold [flags]

Examples

# 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

      --go-module-path string   Go module path.
  -h, --help                    help for scaffold
  -p, --project string          Project name.

Inherits --config, --context from gcx dev.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx dev serve [RESOURCE_DIR]... [flags]

Examples

# 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

      --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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx docs`

Search, fetch, and outline Grafana Labs product documentation, backed by an in-memory index of grafana.com docs.

Flags

  -h, --help   help for docs

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx docs get`

Fetch a documentation page as cleaned markdown. Supports section extraction and offset/limit paging for bounded retrieval.

gcx docs get <url> [flags]

Examples

# 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

  -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 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.

gcx docs list-links [flags]

Examples

gcx docs list-links

Flags

  -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 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.

gcx docs list-products [flags]

Examples

gcx docs list-products

Flags

  -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 docs outline`

List the headings of a documentation page so you can target a section with ‘gcx docs get –section’.

gcx docs outline <url> [flags]

Examples

gcx docs outline https://grafana.com/docs/tempo/latest/traceql/construct-traceql-queries/

Flags

  -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 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.

gcx docs search <query> [flags]

Examples

# 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

  -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 fleet`

Manage Grafana Fleet Management pipelines and collectors

Flags

  -h, --help   help for fleet

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx fleet collectors`

Manage Fleet Management collectors.

Aliases: collector

Flags

  -h, --help   help for collectors

Inherits --config from gcx fleet.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx fleet collectors create`

Create a collector from a file.

gcx fleet collectors create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx fleet collectors delete`

Delete a collector.

gcx fleet collectors delete <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx fleet collectors get <id|name> [flags]

Examples

# Get the full collector resource
  gcx fleet collectors get <id>

  # Show the collector health fields as a table
  gcx fleet collectors get <id> -o wide

  # Select attributes and update time
  gcx fleet collectors get <id> --json spec.local_attributes,spec.remote_attributes,spec.updated_at

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx fleet collectors list [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx fleet collectors update`

Update a collector from a file.

gcx fleet collectors update <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx fleet pipelines`

Manage Fleet Management pipelines.

Aliases: pipeline

Flags

  -h, --help   help for pipelines

Inherits --config from gcx fleet.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx fleet pipelines create`

Create a pipeline from a file.

gcx fleet pipelines create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx fleet pipelines delete`

Delete a pipeline.

gcx fleet pipelines delete <name> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx fleet pipelines get`

Get a pipeline by ID or name.

gcx fleet pipelines get <id|name> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx fleet pipelines list`

List pipelines.

gcx fleet pipelines list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx fleet pipelines update`

Update a pipeline from a file.

gcx fleet pipelines update <name> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx fleet tenant`

Fleet Management tenant settings.

Flags

  -h, --help   help for tenant

Inherits --config from gcx fleet.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx fleet tenant get-limits`

Get tenant limits.

gcx fleet tenant get-limits [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx frontend`

Manage Grafana Frontend Observability resources

Flags

  -h, --help   help for frontend

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx frontend apps`

Manage Frontend Observability apps.

Aliases: app

Flags

  -h, --help   help for apps

Inherits --config from gcx frontend.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx frontend apps apply-sourcemap`

Upload a sourcemap for a Frontend Observability app.

gcx frontend apps apply-sourcemap <app-name> [flags]

Examples

# Upload a sourcemap bundle.
  gcx frontend apps apply-sourcemap my-web-app-42 -f bundle.js.map

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx frontend apps create [flags]

Examples

# Create an app from a YAML file.
  gcx frontend apps create -f app.yaml

  # Create a native Android app from stdin.
  cat <<EOF | gcx frontend apps create -f -
  apiVersion: faro.ext.grafana.app/v1alpha1
  kind: FaroApp
  metadata:
    name: my-mobile-app
  spec:
    name: my-mobile-app
    appType: mobile
    runtime: android-native
  EOF

Flags

  -f, --filename string   File containing the Frontend Observability app 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 frontend.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx frontend apps delete`

Delete a Frontend Observability app.

Deleting requires the grafana-kowalski-app.apps:delete permission (granted to Admin and Frontend Observability Admin by default). A user with only apps:write can create and update apps but cannot delete them.

The argument is a slug-id or numeric ID, not a name. Any trailing “-” is read as the app ID, so “Checkout-2024” deletes app 2024. Find the slug-id with “gcx frontend apps list” first. There is no confirmation prompt.

gcx frontend apps delete <name> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx frontend apps delete-sourcemap`

Delete sourcemap bundles from a Frontend Observability app.

gcx frontend apps delete-sourcemap <app-name> <bundle-id> [bundle-id...] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx frontend apps get <slug-id|name> [flags]

Examples

# Get by slug-id.
  gcx frontend apps get my-web-app-42

  # Get by name.
  gcx frontend apps get "My Web App"

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx frontend apps list`

List Frontend Observability apps.

gcx frontend apps list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx frontend apps list-sourcemaps`

List sourcemaps for a Frontend Observability app.

gcx frontend apps list-sourcemaps <app-name> [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx frontend apps update <name> [flags]

Examples

# Update an app using its slug-id.
  gcx frontend apps update my-web-app-42 -f app.yaml

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx frontend sessions`

Inspect Frontend Observability sessions.

Aliases: session

Flags

  -h, --help   help for sessions

Inherits --config from gcx frontend.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx frontend sessions get <session-id> [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx help`

Help provides help for any command in the application. Simply type gcx help [path to command] for full details.

gcx help [command] [flags]

Flags

  -h, --help   help for help

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx help-tree [COMMAND...] [flags]

Flags

      --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 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

  -h, --help   help for instrumentation

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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).

gcx instrumentation check [components] [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for clusters

Inherits --config from gcx instrumentation.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for apps

Inherits --config from gcx instrumentation.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx instrumentation clusters apps configure <cluster> <namespace> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx instrumentation clusters apps get <cluster> <namespace> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx instrumentation clusters apps list <cluster> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx instrumentation clusters apps remove <cluster> <namespace> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx instrumentation clusters apps wait <cluster> <namespace> [flags]

Flags

  -h, --help               help for wait
      --timeout duration   Maximum time to wait (e.g. 5m, 10m, 1h) (default 5m0s)

Inherits --config from gcx instrumentation.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx instrumentation clusters configure <cluster> [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx instrumentation clusters get <cluster> [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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).

gcx instrumentation clusters list [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx instrumentation clusters remove <cluster> [flags]

Examples

# Remove K8s monitoring for cluster "prod-eu"
  gcx instrumentation clusters remove prod-eu --yes

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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)

gcx instrumentation clusters wait <cluster> [flags]

Examples

# 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

  -h, --help               help for wait
      --timeout duration   Maximum time to wait for INSTRUMENTED status (default 5m0s)

Inherits --config from gcx instrumentation.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx instrumentation explain <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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 <id> to see the full explanation for a specific finding.

gcx instrumentation list-explanations [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for services

Inherits --config from gcx instrumentation.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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:

  gcx instrumentation services clear prod-1 checkout frontend

gcx instrumentation services clear <cluster> <namespace> <service> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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:

  gcx instrumentation services exclude prod-1 checkout payment-svc

gcx instrumentation services exclude <cluster> <namespace> <service> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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:

  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=”.

gcx instrumentation services get <cluster> <namespace> <service> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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:

  gcx instrumentation services include prod-1 checkout frontend

gcx instrumentation services include <cluster> <namespace> <service> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx instrumentation services list`

List all workloads discovered by the Beyla survey collector.

Calls RunK8sDiscovery() (fleet-wide RPC) and applies client-side filters.

Examples:

  # List all workloads
  gcx instrumentation services list

  # Filter to a specific cluster
  gcx instrumentation services list --cluster prod-1

  # Filter to a specific namespace
  gcx instrumentation services list --namespace checkout

  # Show only workloads in terminal error state
  gcx instrumentation services list --status=ERROR

  # 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=”.

gcx instrumentation services list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx instrumentation setup`

Onboard a Kubernetes cluster end-to-end by configuring K8s monitoring and printing a runnable helm install command.

Steps performed:

Calls SetupK8sDiscovery — idempotent, safe to re-run.
Reads the cluster’s current K8s monitoring configuration.
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.
Calls SetK8SInstrumentation only when at least one flag changed.
Emits a mutation summary to stderr.
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.

gcx instrumentation setup <cluster> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx instrumentation status [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

Flags

  -h, --help   help for irm

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm incidents`

Manage incidents.

Aliases: incident, inc

Flags

  -h, --help   help for incidents

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm incidents activity`

Manage incident activity timeline.

Flags

  -h, --help   help for activity

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm incidents activity add`

Add a note to an incident’s activity timeline.

gcx irm incidents activity add <incident-id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm incidents close`

Close (resolve) an incident.

gcx irm incidents close <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm incidents create`

Create a new incident from a file.

gcx irm incidents create [flags]

Examples

# Create an incident from a YAML manifest:
  cat <<EOF | gcx irm incidents create -f -
  apiVersion: incident.ext.grafana.app/v1alpha1
  kind: Incident
  metadata:
    name: my-incident
  spec:
    title: "Service degradation in production"
    status: active
    # The display label, not the identifier. Run
    # 'gcx irm incidents severities list' for the valid values.
    severity: Minor
    isDrill: false
    incidentType: internal
    labels:
      - key: team
        label: platform
      - key: env
        label: production
  EOF

  # Create from a file:
  gcx irm incidents create -f incident.yaml

Flags

  -f, --filename string   File containing the incident 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 irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm incidents get`

Get a single incident by ID.

gcx irm incidents get <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx irm incidents get-pir <incident-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx irm incidents list [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm incidents list-activity`

List activity items for an incident.

gcx irm incidents list-activity <incident-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm incidents list-contexts`

List contexts attached to an incident.

gcx irm incidents list-contexts <incident-id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm incidents open`

Open an incident in the browser.

gcx irm incidents open <id> [flags]

Flags

  -h, --help   help for open

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm incidents severities`

Manage incident severity levels.

Aliases: severity

Flags

  -h, --help   help for severities

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm incidents severities list`

List severity levels for the organization.

gcx irm incidents severities list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx irm incidents update <id> [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall`

Manage Grafana OnCall resources.

Aliases: oc

Flags

  -h, --help   help for oncall

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall alert-groups`

Manage alert groups.

Aliases: alert-group, ag

Flags

  -h, --help   help for alert-groups

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx irm oncall alert-groups acknowledge [<id>] [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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).

Destructive: delete removes the alert group; there is no idempotent skip path.

gcx irm oncall alert-groups delete [<id>] [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall alert-groups get`

Get an alert group by ID.

gcx irm oncall alert-groups get <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx irm oncall alert-groups list [flags]

Examples

# 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 <team-id> --max-age 24h

  # Attribute load to a rotation (chain IDs: gcx irm oncall escalation-chains list)
  gcx irm oncall alert-groups list --escalation-chain <chain-id> --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 <user-id> --resolved-from now-7d --all

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall alert-groups list-alerts`

List individual alerts for an alert group.

gcx irm oncall alert-groups list-alerts <alert-group-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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).

Idempotent: re-running on an already-resolved group reports changed:false (single-target) or summary.skipped++ (bulk) — not an error.

gcx irm oncall alert-groups resolve [<id>] [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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).

Idempotent: re-running on an already-silenced group reports changed:false (single-target) or summary.skipped++ (bulk) — not an error.

gcx irm oncall alert-groups silence [<id>] [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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).

Idempotent: re-running on an already-unacknowledged group reports changed:false (single-target) or summary.skipped++ (bulk) — not an error.

gcx irm oncall alert-groups unacknowledge [<id>] [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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).

Idempotent: re-running on an already-unresolved group reports changed:false (single-target) or summary.skipped++ (bulk) — not an error.

gcx irm oncall alert-groups unresolve [<id>] [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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).

Idempotent: re-running on an already-unsilenced group reports changed:false (single-target) or summary.skipped++ (bulk) — not an error.

gcx irm oncall alert-groups unsilence [<id>] [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall escalate`

Create a direct escalation.

gcx irm oncall escalate [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall escalation-chains`

Manage escalation chains.

Aliases: escalation-chain, ec

Flags

  -h, --help   help for escalation-chains

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall escalation-chains create`

Create an escalation chain.

gcx irm oncall escalation-chains create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall escalation-chains delete`

Delete an escalation chain by ID.

gcx irm oncall escalation-chains delete <id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall escalation-chains get`

Get an escalation chain by ID.

gcx irm oncall escalation-chains get <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall escalation-chains list`

List escalation chains.

gcx irm oncall escalation-chains list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall escalation-chains update`

Update an escalation chain by ID.

gcx irm oncall escalation-chains update <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall escalation-policies`

Manage escalation policies.

Aliases: escalation-policy, ep

Flags

  -h, --help   help for escalation-policies

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall escalation-policies create`

Create an escalation policy.

gcx irm oncall escalation-policies create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall escalation-policies delete`

Delete an escalation policy by ID.

gcx irm oncall escalation-policies delete <id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall escalation-policies get`

Get an escalation policy by ID.

gcx irm oncall escalation-policies get <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall escalation-policies list`

List escalation policies.

gcx irm oncall escalation-policies list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx irm oncall escalation-policies list-step-types [flags]

Examples

# 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 == "<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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall escalation-policies steps`

Discover allowed escalation policy step types.

Flags

  -h, --help   help for steps

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall escalation-policies steps list`

gcx irm oncall escalation-policies steps list [flags]

Examples

# 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 == "<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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall escalation-policies update`

Update an escalation policy by ID.

gcx irm oncall escalation-policies update <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall integrations`

Manage OnCall integrations.

Aliases: integration

Flags

  -h, --help   help for integrations

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall integrations create`

Create an integration.

gcx irm oncall integrations create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall integrations delete`

Delete an integration by ID.

gcx irm oncall integrations delete <id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall integrations get`

Get an integration by ID.

gcx irm oncall integrations get <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx irm oncall integrations get-templates <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall integrations list`

List OnCall integrations.

gcx irm oncall integrations list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx irm oncall integrations start-maintenance <id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall integrations stop-maintenance`

Stop maintenance on an integration.

Use this to end maintenance before its scheduled end. Escalation resumes at once.

gcx irm oncall integrations stop-maintenance <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall integrations update`

Update an integration by ID.

gcx irm oncall integrations update <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx irm oncall integrations update-templates <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall organizations`

View organization info.

Aliases: organization, org

Flags

  -h, --help   help for organizations

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall organizations get`

Get organization info.

gcx irm oncall organizations get [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall resolution-notes`

Manage resolution notes.

Aliases: resolution-note, rn

Flags

  -h, --help   help for resolution-notes

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall resolution-notes create`

Create a resolution note.

gcx irm oncall resolution-notes create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall resolution-notes delete`

Delete a resolution note by ID.

gcx irm oncall resolution-notes delete <id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall resolution-notes get`

Get a resolution note by ID.

gcx irm oncall resolution-notes get <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall resolution-notes list`

List resolution notes.

gcx irm oncall resolution-notes list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall resolution-notes update`

Update a resolution note by ID.

gcx irm oncall resolution-notes update <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall routes`

Manage OnCall routes.

Aliases: route

Flags

  -h, --help   help for routes

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall routes create`

Create a route.

gcx irm oncall routes create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall routes delete`

Delete a route by ID.

gcx irm oncall routes delete <id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall routes filter-types`

Discover route filtering term types.

Flags

  -h, --help   help for filter-types

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx irm oncall routes filter-types list [flags]

Examples

# 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 == "<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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall routes get`

Get a route by ID.

gcx irm oncall routes get <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall routes list`

List OnCall routes.

gcx irm oncall routes list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall routes list-filter-types`

gcx irm oncall routes list-filter-types [flags]

Examples

# 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 == "<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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall routes update`

Update a route by ID.

gcx irm oncall routes update <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall schedules`

Manage OnCall schedules.

Aliases: schedule

Flags

  -h, --help   help for schedules

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall schedules create`

Create a schedule.

gcx irm oncall schedules create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall schedules delete`

Delete a schedule by ID.

gcx irm oncall schedules delete <id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall schedules get`

Get a schedule by ID.

gcx irm oncall schedules get <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx irm oncall schedules list [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall schedules list-final-shifts`

List final shifts for a schedule.

gcx irm oncall schedules list-final-shifts <schedule-id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall schedules update`

Update a schedule by ID.

gcx irm oncall schedules update <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall shift-swaps`

Manage shift swaps.

Aliases: shift-swap, ss

Flags

  -h, --help   help for shift-swaps

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall shift-swaps create`

Create a shift swap.

gcx irm oncall shift-swaps create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall shift-swaps delete`

Delete a shift swap by ID.

gcx irm oncall shift-swaps delete <id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall shift-swaps get`

Get a shift swap by ID.

gcx irm oncall shift-swaps get <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall shift-swaps list`

List shift swaps.

gcx irm oncall shift-swaps list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall shift-swaps update`

Update a shift swap by ID.

gcx irm oncall shift-swaps update <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall shifts`

Manage OnCall shifts.

Aliases: shift

Flags

  -h, --help   help for shifts

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall shifts create`

Create a shift.

gcx irm oncall shifts create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall shifts delete`

Delete a shift by ID.

gcx irm oncall shifts delete <id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall shifts get`

Get a shift by ID.

gcx irm oncall shifts get <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall shifts list`

List OnCall shifts.

gcx irm oncall shifts list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall shifts update`

Update a shift by ID.

gcx irm oncall shifts update <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall slack-channels`

List Slack channels.

Aliases: slack-channel

Flags

  -h, --help   help for slack-channels

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall slack-channels list`

List Slack channels.

gcx irm oncall slack-channels list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall teams`

Manage OnCall teams.

Aliases: team

Flags

  -h, --help   help for teams

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall teams get`

Get a team by ID.

gcx irm oncall teams get <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall teams list`

List OnCall teams.

gcx irm oncall teams list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall user-groups`

List user groups.

Aliases: user-group

Flags

  -h, --help   help for user-groups

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall user-groups list`

List user groups.

gcx irm oncall user-groups list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall users`

Manage OnCall users.

Aliases: user

Flags

  -h, --help   help for users

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall users current`

Get the current user.

gcx irm oncall users current [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall users get`

Get a user by ID.

gcx irm oncall users get <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall users list`

List OnCall users.

gcx irm oncall users list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall webhooks`

Manage outgoing webhooks.

Aliases: webhook

Flags

  -h, --help   help for webhooks

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall webhooks create`

Create an outgoing webhook.

gcx irm oncall webhooks create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall webhooks delete`

Delete an outgoing webhook by ID.

gcx irm oncall webhooks delete <id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall webhooks get`

Get an outgoing webhook by ID.

gcx irm oncall webhooks get <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall webhooks list`

List outgoing webhooks.

gcx irm oncall webhooks list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx irm oncall webhooks list-presets [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx irm oncall webhooks list-triggers [flags]

Examples

# 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 == "<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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall webhooks presets`

Discover webhook configuration presets.

Flags

  -h, --help   help for presets

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall webhooks presets list`

gcx irm oncall webhooks presets list [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall webhooks triggers`

Discover allowed webhook trigger types.

Flags

  -h, --help   help for triggers

Inherits --config from gcx irm.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall webhooks triggers list`

gcx irm oncall webhooks triggers list [flags]

Examples

# 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 == "<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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx irm oncall webhooks update`

Update an outgoing webhook by ID.

gcx irm oncall webhooks update <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6`

Manage Grafana k6 Cloud projects, load tests, and schedules

Flags

  -h, --help   help for k6

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 auth`

k6 authentication commands.

Flags

  -h, --help   help for auth

Inherits --config from gcx k6.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 auth token`

Print the authenticated k6 API token.

gcx k6 auth token [flags]

Flags

  -h, --help   help for token

Inherits --config from gcx k6.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 env-vars`

Manage k6 Cloud environment variables.

Aliases: envvars, envvar, env

Flags

  -h, --help   help for env-vars

Inherits --config from gcx k6.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 env-vars create`

Create a k6 environment variable from a file.

gcx k6 env-vars create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 env-vars delete`

Delete a k6 environment variable.

gcx k6 env-vars delete <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 env-vars list`

List k6 environment variables.

gcx k6 env-vars list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 env-vars update`

Update a k6 environment variable.

gcx k6 env-vars update <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 load-tests`

Manage k6 Cloud load tests.

Aliases: tests, test

Flags

  -h, --help   help for load-tests

Inherits --config from gcx k6.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx k6 load-tests create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 load-tests delete`

Delete a k6 load test.

gcx k6 load-tests delete <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 load-tests delete-schedule`

Delete the schedule for a k6 load test.

gcx k6 load-tests delete-schedule <load-test-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 load-tests get`

Get a single k6 load test by ID or name.

gcx k6 load-tests get <id-or-name> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx k6 load-tests list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 load-tests update`

Update a k6 load test from a file.

gcx k6 load-tests update <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 load-tests update-script`

Update the script of a k6 load test from a file.

gcx k6 load-tests update-script <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 load-zones`

Manage k6 private load zones.

Aliases: load-zone, lz

Flags

  -h, --help   help for load-zones

Inherits --config from gcx k6.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 load-zones create`

gcx k6 load-zones create [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 load-zones delete`

Deregister a Private Load Zone.

gcx k6 load-zones delete <name> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 load-zones list`

List all k6 load zones.

gcx k6 load-zones list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 load-zones list-allowed-projects`

List projects allowed to use a load zone.

gcx k6 load-zones list-allowed-projects <load-zone-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 load-zones update-allowed-projects`

Replace the set of projects allowed to use a load zone.

gcx k6 load-zones update-allowed-projects <load-zone-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 projects`

Manage k6 Cloud projects.

Aliases: project, proj

Flags

  -h, --help   help for projects

Inherits --config from gcx k6.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 projects create`

Create a new k6 project from a file.

gcx k6 projects create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 projects delete`

Delete a k6 project.

gcx k6 projects delete <id-or-name> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 projects get`

Get a single k6 project by ID or name.

gcx k6 projects get <id-or-name> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 projects list`

List k6 Cloud projects.

gcx k6 projects list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 projects list-allowed-load-zones`

List load zones allowed for a project.

gcx k6 projects list-allowed-load-zones <project-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 projects update`

Update a k6 project.

gcx k6 projects update <id-or-name> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 projects update-allowed-load-zones`

Replace the set of load zones allowed for a project.

gcx k6 projects update-allowed-load-zones <project-id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 runs`

Manage k6 test runs.

Flags

  -h, --help   help for runs

Inherits --config from gcx k6.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 runs list`

List test runs for a load test.

gcx k6 runs list [id-or-name] [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 schedules`

Manage k6 Cloud schedules.

Aliases: schedule

Flags

  -h, --help   help for schedules

Inherits --config from gcx k6.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 schedules create`

Create a k6 schedule from a file.

gcx k6 schedules create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 schedules get`

Get a single k6 schedule by ID.

gcx k6 schedules get <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 schedules list`

List all k6 schedules.

gcx k6 schedules list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 schedules update`

Update a k6 schedule from a file.

gcx k6 schedules update <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 test-run`

Manage k6 TestRun CRD manifests.

Aliases: testrun

Flags

  -h, --help   help for test-run

Inherits --config from gcx k6.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx k6 test-run emit [test-name] [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 test-run runs`

Query k6 Cloud test run history.

Flags

  -h, --help   help for runs

Inherits --config from gcx k6.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 test-run runs list`

List all test runs for a k6 load test.

gcx k6 test-run runs list [test-name] [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx k6 test-run status`

Show the most recent test run status for a k6 load test.

gcx k6 test-run status [test-name] [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg`

Manage Grafana Knowledge Graph rules, entities, and insights

Aliases: knowledge-graph

Flags

  -h, --help   help for kg

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx kg diagnose [flags]

Examples

gcx kg diagnose
  gcx kg diagnose --env production
  gcx kg diagnose --env staging --output json
  gcx kg diagnose --datasource grafanacloud-prom

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx kg diagnose labels [flags]

Examples

gcx kg diagnose labels
  gcx kg diagnose labels --datasource grafanacloud-prom
  gcx kg diagnose labels -o json

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx kg diagnose service NAME [flags]

Examples

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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for entities

Inherits --config from gcx kg.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx kg entities correlate [flags]

Examples

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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx kg entities delete [Type--Name] [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx kg entities inspect [Type--Name] [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx kg entities list [flags]

Examples

gcx kg entities list --type Service --env <env> --namespace <namespace> --property name=<service-name>
  gcx kg entities list --type Service --env <env> --insight any
  gcx kg entities list --type Service --env <env> --insight name=Saturation --insight severity=critical
  gcx kg entities list --type Service --env <env> --property name=~api --insight severity=critical
  gcx kg entities list --type Service --env <env> --insight severity=critical --json name,scope

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx kg entities query <cypher-query> [flags]

Examples

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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx kg entities upsert [flags]

Examples

gcx kg entities upsert --domain myapp --type Service --name checkout --scope env=prod --ttl 1h
  gcx kg entities upsert -f entity.yaml

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg insights`

Fetch chart data and source metrics for an active insight.

Flags

  -h, --help   help for insights

Inherits --config from gcx kg.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg insights chart`

Get chart data (series + thresholds) for a specific insight on an entity.

gcx kg insights chart [Type--Name] [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg insights sources`

List the underlying metrics (name + label matchers) that source a specific insight.

gcx kg insights sources [Type--Name] [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg meta`

Show Knowledge Graph metadata: entity types, valid env/namespace/site values, and telemetry query configs.

Flags

  -h, --help   help for meta

Inherits --config from gcx kg.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg meta all`

Load all sections: schema, scopes, logs, traces, profiles, and metrics.

gcx kg meta all [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg meta logs`

Show Loki label mappings for log drilldown.

gcx kg meta logs [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg meta metrics`

Show the asserts:* KPI metrics (Knowledge Graph recording rules) and the entity-property → Prometheus label mapping for querying them.

gcx kg meta metrics [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg meta profiles`

Show Pyroscope label mappings for profile drilldown.

gcx kg meta profiles [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg meta schema`

Show entity types, properties, and relationships.

gcx kg meta schema [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg meta scopes`

Show all valid env/namespace/site filter values.

gcx kg meta scopes [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg meta traces`

Show Tempo label mappings for trace drilldown.

gcx kg meta traces [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg model-rules`

Manage model rules in the Knowledge Graph.

Flags

  -h, --help   help for model-rules

Inherits --config from gcx kg.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg model-rules delete`

Delete a custom model rules configuration by name.

gcx kg model-rules delete <name> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg model-rules get`

Get a custom model rules configuration by name.

gcx kg model-rules get <name> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg model-rules list`

List all custom model rules configurations.

gcx kg model-rules list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx kg model-rules schema [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg model-rules upsert`

Upload model rules from a YAML file.

gcx kg model-rules upsert [flags]

Examples

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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for notifications

Inherits --config from gcx kg.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg notifications delete`

Delete an alert notification config by name.

gcx kg notifications delete <name> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg notifications get`

Get an alert notification config by name.

gcx kg notifications get <name> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg notifications list`

List alert notification configs, optionally filtered by category.

gcx kg notifications list [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx kg notifications upsert [flags]

Examples

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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg open`

Open the Knowledge Graph app in the browser.

gcx kg open [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg prom-rules`

Manage Knowledge Graph Custom Prometheus rules.

Flags

  -h, --help   help for prom-rules

Inherits --config from gcx kg.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg prom-rules delete`

Delete a Knowledge Graph Custom Prometheus rule by name.

gcx kg prom-rules delete <name> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg prom-rules get`

Get a Knowledge Graph Custom Prometheus rule by name.

gcx kg prom-rules get <name> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg prom-rules list`

List Knowledge Graph Custom Prometheus rules.

gcx kg prom-rules list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx kg prom-rules schema [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg prom-rules upsert`

Upload Knowledge Graph Custom Prometheus rules from a YAML file.

gcx kg prom-rules upsert [flags]

Examples

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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for quality

Inherits --config from gcx kg.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg quality get`

Get the full quality report for a single entity.

gcx kg quality get <entity-name> [flags]

Examples

gcx kg quality get my-service --env <env>
  gcx kg quality get my-service --env <env> --namespace <namespace>
  gcx kg quality get my-service --env <env> --yaml

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg quality list`

List entity quality reports, ranked by quality percent.

gcx kg quality list [flags]

Examples

gcx kg quality list --env <env>
  gcx kg quality list --env <env> --namespace <namespace> --sort asc
  gcx kg quality list --env <env> --failed-check span-metrics --failed-check service-graph-metrics
  gcx kg quality list --env <env> --json entityName,qualityPercent,failedCheckIds

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg relabel-rules`

Inspect Mimir relabel rules used by the Knowledge Graph.

Flags

  -h, --help   help for relabel-rules

Inherits --config from gcx kg.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg relabel-rules get`

Fetch a relabel rule group (prologue, epilogue, or generated).

gcx kg relabel-rules get [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for relationships

Inherits --config from gcx kg.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx kg relationships delete [flags]

Examples

gcx kg relationships delete --type CALLS \
    --from myapp/Service/checkout --to myapp/Service/cart --force

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx kg relationships upsert [flags]

Examples

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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg stats`

Show entity and active-insight counts, broken down by type, severity, and insight name.

gcx kg stats [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg status`

Show Knowledge Graph stack status.

gcx kg status [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg suppressions`

Manage alert suppressions in the Knowledge Graph.

Flags

  -h, --help   help for suppressions

Inherits --config from gcx kg.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg suppressions delete`

Delete a suppression by name.

gcx kg suppressions delete <name> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx kg suppressions list`

List all alert suppressions.

gcx kg suppressions list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx kg suppressions upsert [flags]

Examples

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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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 –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

gcx login [CONTEXT_NAME] [flags]

Examples

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

      --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 logs`

Query Loki datasources and manage Adaptive Logs

Flags

  -h, --help   help for logs

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx logs adaptive`

Manage Adaptive Logs resources

Flags

  -h, --help   help for adaptive

Inherits --config from gcx logs.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for drop-rules

Inherits --config from gcx logs.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx logs adaptive drop-rules create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx logs adaptive drop-rules delete`

Delete an adaptive log drop rule.

gcx logs adaptive drop-rules delete ID [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx logs adaptive drop-rules get ID [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx logs adaptive drop-rules list`

List adaptive log drop rules.

gcx logs adaptive drop-rules list [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx logs adaptive drop-rules update ID [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx logs adaptive exemptions`

Manage adaptive log exemptions.

Flags

  -h, --help   help for exemptions

Inherits --config from gcx logs.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx logs adaptive exemptions create`

Create an adaptive log exemption.

gcx logs adaptive exemptions create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx logs adaptive exemptions delete`

Delete an adaptive log exemption.

gcx logs adaptive exemptions delete ID [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx logs adaptive exemptions list`

List adaptive log exemptions.

gcx logs adaptive exemptions list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx logs adaptive exemptions update`

Update an adaptive log exemption.

gcx logs adaptive exemptions update ID [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx logs adaptive patterns`

Manage adaptive log patterns.

Flags

  -h, --help   help for patterns

Inherits --config from gcx logs.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx logs adaptive patterns list`

List adaptive log pattern recommendations.

gcx logs adaptive patterns list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx logs adaptive patterns stats`

Summarize pattern volume aggregated by segment.

gcx logs adaptive patterns stats [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx logs adaptive segments`

Manage adaptive log segments.

Flags

  -h, --help   help for segments

Inherits --config from gcx logs.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx logs adaptive segments create`

Create an adaptive log segment.

gcx logs adaptive segments create [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx logs adaptive segments delete`

Delete an adaptive log segment.

gcx logs adaptive segments delete ID [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx logs adaptive segments list`

List adaptive log segments.

gcx logs adaptive segments list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx logs adaptive segments update`

Update an adaptive log segment.

gcx logs adaptive segments update ID [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx logs labels`

List all labels or get values for a specific label from a Loki datasource.

gcx logs labels [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx logs metrics [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx logs query [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx logs series`

List log streams (series) from a Loki datasource using LogQL stream selectors. At least one –match selector is required.

gcx logs series [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics`

Query Prometheus datasources and manage Adaptive Metrics

Flags

  -h, --help   help for metrics

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive`

Manage Adaptive Metrics resources

Flags

  -h, --help   help for adaptive

Inherits --config from gcx metrics.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive exemptions`

Manage Adaptive Metrics recommendation exemptions.

Flags

  -h, --help   help for exemptions

Inherits --config from gcx metrics.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive exemptions create`

Create a recommendation exemption.

gcx metrics adaptive exemptions create [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive exemptions delete`

Delete a recommendation exemption.

gcx metrics adaptive exemptions delete <id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive exemptions get`

Get a recommendation exemption by ID.

gcx metrics adaptive exemptions get <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive exemptions list`

List Adaptive Metrics recommendation exemptions.

gcx metrics adaptive exemptions list [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive exemptions update`

Update a recommendation exemption.

gcx metrics adaptive exemptions update <id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive recommendations`

Manage metric recommendations.

Flags

  -h, --help   help for recommendations

Inherits --config from gcx metrics.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive recommendations apply`

Apply specific or all recommendations as rules.

gcx metrics adaptive recommendations apply [<metric>...|--all] [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive recommendations diff`

Show what applying recommendation(s) would change.

gcx metrics adaptive recommendations diff <metric>... [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive recommendations list`

List metric recommendations.

gcx metrics adaptive recommendations list [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive rules`

Manage aggregation rules.

Flags

  -h, --help   help for rules

Inherits --config from gcx metrics.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive rules create`

Create an aggregation rule.

gcx metrics adaptive rules create [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive rules delete`

Delete an aggregation rule.

gcx metrics adaptive rules delete <metric> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive rules get`

Get an aggregation rule by metric name.

gcx metrics adaptive rules get <metric> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive rules list`

List aggregation rules.

gcx metrics adaptive rules list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive rules update`

Update an aggregation rule.

gcx metrics adaptive rules update <metric> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive segments`

Manage Adaptive Metrics segments.

Flags

  -h, --help   help for segments

Inherits --config from gcx metrics.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive segments create`

Create an Adaptive Metrics segment.

gcx metrics adaptive segments create [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive segments delete`

Delete an Adaptive Metrics segment.

gcx metrics adaptive segments delete <id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive segments get`

Get an Adaptive Metrics segment by ID.

gcx metrics adaptive segments get <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive segments list`

List Adaptive Metrics segments.

gcx metrics adaptive segments list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics adaptive segments update`

Update an Adaptive Metrics segment.

gcx metrics adaptive segments update <id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for billing

Inherits --config from gcx metrics.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics billing labels`

List all labels or get values for a specific label from a Prometheus datasource.

gcx metrics billing labels [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics billing query`

Execute a PromQL query against a Prometheus datasource.

gcx metrics billing query [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx metrics billing series [SELECTOR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for cardinality

Inherits --config from gcx metrics.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics cardinality label-names`

Show, for each label name, how many distinct values it has, via the Mimir cardinality analysis API.

gcx metrics cardinality label-names [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx metrics cardinality label-values [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics labels`

List all labels or get values for a specific label from a Prometheus datasource.

gcx metrics labels [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx metrics list-names [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics metadata`

Get metadata (type, help text) for metrics from a Prometheus datasource.

gcx metrics metadata [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx metrics query`

Execute a PromQL query against a Prometheus datasource.

gcx metrics query [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for search

Inherits --config from gcx metrics.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

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.

gcx metrics search label-names [TERM...] [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

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.

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.

gcx metrics search label-values LABEL [TERM...] [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx metrics search metric-names TERM... [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx metrics series [SELECTOR] [flags]

Examples

# Match a single metric family
  gcx metrics series -d <datasource-uid> '{__name__="up"}'

  # Match multiple selectors scoped to the last hour
  gcx metrics series -d <datasource-uid> --match '{job="grafana"}' --match '{job="loki"}' --since 1h

  # Output as JSON
  gcx metrics series -d <datasource-uid> '{__name__=~"grafanacloud_.*"}' -o json

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx profiles`

Query Pyroscope datasources and manage continuous profiling

Flags

  -h, --help   help for profiles

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx profiles adaptive`

Manage Adaptive Profiles (not yet available)

gcx profiles adaptive [flags]

Flags

  -h, --help   help for adaptive

Inherits --config from gcx profiles.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx profiles data-range`

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.

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.

gcx profiles data-range [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx profiles exemplars`

Query profile or span exemplars from a Pyroscope datasource.

Examples

# 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

  -h, --help   help for exemplars

Inherits --config from gcx profiles.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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”}’).

gcx profiles exemplars profile [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx profiles exemplars span`

List span exemplars by calling SelectHeatmap with HEATMAP_QUERY_TYPE_SPAN.

EXPR is the label selector (e.g. ‘{service_name=“frontend”}’).

gcx profiles exemplars span [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx profiles labels`

List all labels or get values for a specific label from a Pyroscope datasource.

gcx profiles labels [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx profiles list-profile-types [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

EXPR is the label selector (e.g., ‘{service_name=“frontend”}’). Datasource is resolved from -d flag or datasources.pyroscope in your context.

gcx profiles metrics [EXPR] [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx profiles query [EXPR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx profiles query-anomalies [EXPR] [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx profiles series`

List unique profile label sets from a Pyroscope datasource.

gcx profiles series [SELECTOR] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx providers`

Manage registered providers

Flags

  -h, --help   help for providers

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx providers list`

List registered providers

gcx providers list [flags]

Flags

  -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 resources`

Manipulate Grafana resources.

Flags

  -h, --help   help for resources

Shared flags

      --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 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).

gcx resources delete [RESOURCE_SELECTOR]... [flags]

Examples

# 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

      --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 (<resource>.<group>), 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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx resources edit RESOURCE_SELECTOR [flags]

Examples

# 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

  -h, --help            help for edit
  -o, --output string   Output format. One of: json, yaml (default "json")

Inherits --config, --context from gcx resources.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx resources get`

Get resources from Grafana using a specific format. See examples below for more details.

gcx resources get [RESOURCE_SELECTOR]... [flags]

Examples

# 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

  -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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx resources list-examples [RESOURCE_SELECTOR] [flags]

Examples

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

  -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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx resources list-types [RESOURCE_SELECTOR] [flags]

Examples

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

  -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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx resources pull`

Pull resources from Grafana using a specific format. See examples below for more details.

gcx resources pull [RESOURCE_SELECTOR]... [flags]

Examples

# 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

  -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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx resources push`

Push resources to Grafana using a specific format. See examples below for more details.

gcx resources push [RESOURCE_SELECTOR]... [flags]

Examples

# 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

      --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 (<resource>.<group>), 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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx resources validate [RESOURCE_SELECTOR]... [flags]

Examples

# 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

      --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 (<resource>.<group>), 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.

Inherits --agent, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx setup`

Onboard and configure Grafana Cloud products.

Flags

  -h, --help   help for setup

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx setup status`

Show aggregated setup status across all products.

gcx setup status [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx signup [CONTEXT_NAME] [flags]

Examples

gcx signup
  gcx signup my-stack
  gcx signup --oauth-manual

Flags

      --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 slo`

Manage Grafana SLO definitions and reports

Flags

  -h, --help   help for slo

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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

  -h, --help   help for definitions

Inherits --config from gcx slo.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx slo definitions delete`

Delete SLO definitions.

gcx slo definitions delete UUID... [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx slo definitions get`

Get a single SLO definition.

gcx slo definitions get UUID [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx slo definitions list`

List SLO definitions.

gcx slo definitions list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx slo definitions pull [flags]

Flags

  -h, --help                help for pull
  -d, --output-dir string   Directory to write SLO definitions to (default ".")

Inherits --config from gcx slo.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx slo definitions push FILE... [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx slo definitions status [UUID] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx slo definitions timeline [UUID] [flags]

Examples

# 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

      --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-<since> --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx slo reports`

Manage SLO reports.

Aliases: report

Flags

  -h, --help   help for reports

Inherits --config from gcx slo.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx slo reports delete`

Delete SLO reports.

gcx slo reports delete UUID... [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx slo reports get`

Get a single SLO report.

gcx slo reports get UUID [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx slo reports list`

List SLO reports.

gcx slo reports list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx slo reports pull [flags]

Flags

  -h, --help                help for pull
  -d, --output-dir string   Directory to write SLO reports to (default ".")

Inherits --config from gcx slo.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx slo reports push FILE... [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx slo reports status [UUID] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx slo reports timeline [UUID] [flags]

Examples

# 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

      --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-<since> --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx synthetic-monitoring`

Manage Grafana Synthetic Monitoring checks and probes

Aliases: sm, synth

Flags

  -h, --help   help for synthetic-monitoring

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx synthetic-monitoring checks`

Manage Synthetic Monitoring checks.

Aliases: check

Flags

  -h, --help   help for checks

Inherits --config from gcx synthetic-monitoring.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx synthetic-monitoring checks create [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx synthetic-monitoring checks delete`

Delete Synthetic Monitoring checks.

gcx synthetic-monitoring checks delete NAME... [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx synthetic-monitoring checks get`

Get a single Synthetic Monitoring check.

gcx synthetic-monitoring checks get NAME [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx synthetic-monitoring checks list`

List Synthetic Monitoring checks.

gcx synthetic-monitoring checks list [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx synthetic-monitoring checks status [ID] [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx synthetic-monitoring checks test [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx synthetic-monitoring checks timeline ID [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx synthetic-monitoring checks update <name> [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx synthetic-monitoring probes`

Manage Synthetic Monitoring probes.

Aliases: probe

Flags

  -h, --help   help for probes

Inherits --config from gcx synthetic-monitoring.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx synthetic-monitoring probes create`

Create a Synthetic Monitoring probe.

gcx synthetic-monitoring probes create [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx synthetic-monitoring probes delete`

Delete Synthetic Monitoring probes.

gcx synthetic-monitoring probes delete ID... [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx synthetic-monitoring probes deploy [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx synthetic-monitoring probes list`

List Synthetic Monitoring probes.

gcx synthetic-monitoring probes list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx synthetic-monitoring probes reset-token ID [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx synthetic-monitoring queries`

Discover Synthetic Monitoring named queries.

Flags

  -h, --help   help for queries

Inherits --config from gcx synthetic-monitoring.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx synthetic-monitoring queries get NAME [flags]

Examples

gcx synthetic-monitoring queries get checks_uptime

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx synthetic-monitoring queries list [flags]

Examples

gcx synthetic-monitoring queries list

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx synthetic-monitoring query NAME [flags]

Examples

# 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

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx traces`

Query Tempo datasources and manage Adaptive Traces

Flags

  -h, --help   help for traces

Shared flags

      --config string   Path to the configuration file to use

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx traces adaptive`

Manage Adaptive Traces resources

Flags

  -h, --help   help for adaptive

Inherits --config from gcx traces.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx traces adaptive policies`

Manage Adaptive Traces sampling policies.

Flags

  -h, --help   help for policies

Inherits --config from gcx traces.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx traces adaptive policies create`

Create an Adaptive Traces sampling policy from a file.

gcx traces adaptive policies create [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx traces adaptive policies delete`

Delete one or more Adaptive Traces sampling policies.

gcx traces adaptive policies delete <id>... [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx traces adaptive policies get`

Get an Adaptive Traces sampling policy by ID.

gcx traces adaptive policies get <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx traces adaptive policies list`

List Adaptive Traces sampling policies.

gcx traces adaptive policies list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx traces adaptive policies update`

Update an Adaptive Traces sampling policy by ID.

gcx traces adaptive policies update <id> [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx traces adaptive recommendations`

Manage Adaptive Traces recommendations.

Flags

  -h, --help   help for recommendations

Inherits --config from gcx traces.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx traces adaptive recommendations apply`

Apply an Adaptive Traces recommendation.

gcx traces adaptive recommendations apply <id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx traces adaptive recommendations dismiss`

Dismiss an Adaptive Traces recommendation.

gcx traces adaptive recommendations dismiss <id> [flags]

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx traces adaptive recommendations list`

List Adaptive Traces recommendations.

gcx traces adaptive recommendations list [flags]

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx traces baseline TRACE_ID [flags]

Examples

# Find a small shortlist; COHORT is an already-verified TraceQL spanset
  gcx traces baseline --context prod -d UID <seed-id> --filter "$COHORT" --limit 5

  # With no additional known scope, use the seed-derived defaults
  gcx traces baseline --context prod -d UID <seed-id> --limit 5

  # Inspect selected candidates; repeat for a small batch, not every result
  gcx traces get --context prod -d UID <candidate-id> --llm -o agents

  # Assess a candidate with an exploratory diff (seed minus candidate)
  gcx traces diff --context prod -d UID <candidate-id> <seed-id>

  # Set the candidate window; this does not bound the seed trace lookup
  gcx traces baseline --context prod -d UID <seed-id> --filter "$COHORT" --limit 5 \
    --from 2026-01-15T08:00:00Z --to 2026-01-15T09:00:00Z

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

gcx traces diff TRACE_A TRACE_B [flags]

Examples

# Compare an already-known pair directly; baseline search is not required
  gcx traces diff --context prod -d UID <baseline-id> <comparison-id>

  # Inspect a plausible candidate before using a diff to assess it
  gcx traces get --context prod -d UID <candidate-id> --llm -o agents

  # Assess selected candidates against the seed; repeat only as useful
  gcx traces diff --context prod -d UID <candidate-id> <seed-id>

  # Bound BOTH trace lookups, including an older candidate, and allow spilling
  gcx traces diff --context prod -d UID <candidate-id> <seed-id> \
    --from 2026-01-15T08:00:00Z --to 2026-01-15T10:00:00Z -o agents

Flags

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

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).

gcx traces get TRACE_ID [flags]

Examples

# Fetch a trace by ID for agent analysis
  gcx traces get -d UID <trace-id> --llm -o json

  # Print a Grafana Explore share link for the trace
  gcx traces get -d UID <trace-id> --share-link

  # Output raw OTLP-shaped JSON when explicitly needed
  gcx traces get -d UID <trace-id> -o json

  # Narrow a large trace to error spans and their ancestor path
  gcx traces get -d UID <trace-id> --filter '{ status = error }' --keep-hierarchy

  # Collapse repeated sibling spans to shrink a huge trace before analysis
  gcx traces get -d UID <trace-id> --prune --llm -o json

Flags

      --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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`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.

Aliases: tags

gcx traces labels [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx traces metrics`

Execute a TraceQL metrics query against a Tempo datasource.

gcx traces metrics [TRACEQL] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx traces query`

Search for traces using a TraceQL query against a Tempo datasource.

Aliases: search

gcx traces query [TRACEQL] [flags]

Examples

# 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

  -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.

Inherits --agent, --context, --insecure-log-http-payload, --no-color, --no-truncate, --verbose from gcx.

`gcx version`

Print version, commit, build date, Go version, OS, and architecture. Supports structured output via –output json/yaml.

gcx version [flags]

Examples

# Human-readable version
  gcx version

  # JSON output for automation
  gcx version -o json

  # Select specific fields
  gcx version --json version,commit

Flags

  -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.

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.

`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 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

gcx CLI on Grafana Labs

Introduction to gcx

Overview of the gcx CLI

Benefits of gcx

Costs

Compatibility

CLI command reference

Configure gcx

Experimental commands

Manage your resources

Work with resources from other tools

Extract dashboards

Migrate from grafanactl

Learn more

Install gcx

Install gcx

Quick install using the script

Upgrade

Installer configuration options

Examples

Uninstall

Install gcx with Homebrew (macOS and Linux)

Install from the Grafana tap

Homebrew and macOS Gatekeeper

Install a prebuilt binary

Run gcx in a container

Install gcx from source

The version does not change after an upgrade

macOS Gatekeeper and killed 9

Bypass the macOS gatekeeper

Configure gcx

Configure gcx

Choose an authentication method

Required role for OAuth sign-in

Understand the gcx configuration file in use

Define contexts

Useful commands

Configure gcx with environment variables

Configuration reference

Migrate your gcx configuration

Migrate your gcx configuration files to v1 format

How migration works

Migration doesn’t delete any information

Roll back a completed migration

Why a migration paused or stopped

How to migrate layered files

How to consolidate overlapping layers

Map a legacy configuration to version 1

Example of a legacy configuration update

Credential references

Verify the result

Usage statistics

Understand gcx usage statistics

Telemetry data and identifiers

Understand which data is collected

How to read the batch fields

Canceled invocations

Failure and authentication fields

Parse-failure fields

The api command

Invocations that report nothing

How the report is sent

Server-side enrichment

Inspect what would be sent

Opt out

The one-time notice

Agent identity

Keychain credential storage

Keychain credential storage

Plaintext fallback

Configure credential storage

Replacing a stored credential in off mode

Restricted execution sessions

Keychain locked

Unlock macOS Keychain

Unlock a GNOME keyring in a headless session

A credential was rejected before network use

User guides

gcx user guides

CLI reference

Overview of the `gcx` CLI

Benefits of `gcx`

Configure `gcx`

Migrate from `grafanactl`

Install `gcx`

Install `gcx` with Homebrew (macOS and Linux)

Run `gcx` in a container

Install `gcx` from source

Configure `gcx`

Understand the `gcx` configuration file in use

Configure `gcx` with environment variables

Migrate your `gcx` configuration files to v1 format

Replacing a stored credential in `off` mode

`Keychain locked`

A credential was `rejected before network use`

`gcx` user guides

`gcx`

`gcx agent`

`gcx agent prune`

`gcx agent skills`

`gcx agent skills get`

`gcx agent skills install`

`gcx agent skills list`

`gcx agent skills uninstall`

`gcx agent skills update`

`gcx agento11y`

`gcx agento11y agents`

`gcx agento11y agents get`

`gcx agento11y agents list`

`gcx agento11y agents list-versions`

`gcx agento11y collections`

`gcx agento11y collections add-conversations`

`gcx agento11y collections create`

`gcx agento11y collections delete`

`gcx agento11y collections get`

`gcx agento11y collections list`

`gcx agento11y collections list-conversations`

`gcx agento11y collections remove-conversation`

`gcx agento11y collections update`

`gcx agento11y conversations`

`gcx agento11y conversations annotate`

`gcx agento11y conversations get`

`gcx agento11y conversations list`

`gcx agento11y conversations list-annotations`

`gcx agento11y conversations search`

`gcx agento11y evaluators`

`gcx agento11y evaluators delete`

`gcx agento11y evaluators get`

`gcx agento11y evaluators list`

`gcx agento11y evaluators test`

`gcx agento11y evaluators upsert`

`gcx agento11y experiments`

`gcx agento11y experiments cancel`

`gcx agento11y experiments create`

`gcx agento11y experiments get`

`gcx agento11y experiments get-report`

`gcx agento11y experiments list`

`gcx agento11y experiments list-scores`

`gcx agento11y experiments list-trials`

`gcx agento11y experiments pull`

`gcx agento11y experiments test-suites`

`gcx agento11y experiments test-suites cases`

`gcx agento11y experiments test-suites cases delete`

`gcx agento11y experiments test-suites cases get`

`gcx agento11y experiments test-suites cases list`

`gcx agento11y experiments test-suites cases update`

`gcx agento11y experiments test-suites cases upsert`

`gcx agento11y experiments test-suites create`

`gcx agento11y experiments test-suites get`

`gcx agento11y experiments test-suites list`

`gcx agento11y experiments test-suites update`

`gcx agento11y experiments test-suites versions`

`gcx agento11y experiments test-suites versions create`

`gcx agento11y experiments test-suites versions publish`

`gcx agento11y experiments trials`

`gcx agento11y experiments trials create`

`gcx agento11y experiments trials get`

`gcx agento11y experiments trials list-artifacts`

`gcx agento11y experiments trials list-scores`

`gcx agento11y experiments trials update`