--- title: "CLI reference | Grafana documentation" description: "Complete gcx command, flag, and environment variable reference." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # edit dashboard.yaml gcx dashboards update -f dashboard.yaml shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dashboards update -f [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --api-version string API version to use (e.g. dashboard.grafana.app/v1); defaults to server preferred version -f, --filename string Path to JSON/YAML manifest file ('-' reads from stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx dashboards`](#gcx-dashboards-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dashboards versions` Manage dashboard version history **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for versions ``` Inherits `--config` from [`gcx dashboards`](#gcx-dashboards-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dashboards versions restore` Restore a dashboard to a previous version shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dashboards versions restore [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --api-version string API version to use (e.g. dashboard.grafana.app/v1); defaults to server preferred version --force Skip confirmation prompt -h, --help help for restore --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --message string Commit message for the restored revision (default: "Restored from version N") -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx dashboards`](#gcx-dashboards-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources` List, inspect, and query Grafana datasources. Use top-level signal commands (metrics, logs, traces, profiles) for datasource-specific queries. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for datasources ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources athena` Query Amazon Athena datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for athena ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources athena describe-table` List the column names of the specified table. Only names are returned, not types or other schema details. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources athena describe-table TABLE [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List columns for a table gcx datasources athena describe-table my_table -d UID --database mydb # With catalog and region gcx datasources athena describe-table my_table -d UID --catalog AwsDataCatalog --database mydb --region us-east-1 # Output as JSON gcx datasources athena describe-table my_table -d UID --database mydb -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --catalog string Data catalog --database string Database name -d, --datasource string Datasource UID (required unless datasources.athena is configured) -h, --help help for describe-table --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --region string AWS region override ``` Inherits `--config` from [`gcx datasources athena`](#gcx-datasources-athena-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources athena list-catalogs` List available Athena data catalogs shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources athena list-catalogs [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all catalogs gcx datasources athena list-catalogs # With explicit datasource and region gcx datasources athena list-catalogs -d UID --region us-east-1 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.athena is configured) -h, --help help for list-catalogs --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --region string AWS region override ``` Inherits `--config` from [`gcx datasources athena`](#gcx-datasources-athena-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources athena list-databases` List databases in an Athena data catalog shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources athena list-databases [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List databases in the default catalog gcx datasources athena list-databases -d UID --catalog AwsDataCatalog # With region override gcx datasources athena list-databases -d UID --catalog AwsDataCatalog --region us-east-1 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --catalog string Data catalog to query -d, --datasource string Datasource UID (required unless datasources.athena is configured) -h, --help help for list-databases --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --region string AWS region override ``` Inherits `--config` from [`gcx datasources athena`](#gcx-datasources-athena-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources athena list-tables` List tables in an Athena database shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources athena list-tables [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List tables in a database gcx datasources athena list-tables -d UID --database mydb # With catalog and region gcx datasources athena list-tables -d UID --catalog AwsDataCatalog --database mydb --region us-east-1 # Output as JSON gcx datasources athena list-tables -d UID --database mydb -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --catalog string Data catalog to query --database string Database to query -d, --datasource string Datasource UID (required unless datasources.athena is configured) -h, --help help for list-tables --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --region string AWS region override ``` Inherits `--config` from [`gcx datasources athena`](#gcx-datasources-athena-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources athena query` Execute a SQL query against an Amazon Athena datasource. EXPR is the SQL query to execute, passed as a positional argument or via –expr. Datasource is resolved from -d flag or datasources.athena in your context. Server-side macros ($\_\_timeFilter, $\_\_dateFilter, etc.) are supported. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources athena query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Simple query gcx datasources athena query 'SELECT count(*) FROM events' # With time macro and explicit datasource gcx datasources athena query -d UID 'SELECT * FROM logs WHERE $__timeFilter(event_time)' --since 1h # With connection overrides gcx datasources athena query -d UID 'SELECT 1' --region us-west-2 --database analytics # Enable result reuse (Athena engine v3) gcx datasources athena query -d UID 'SELECT count(*) FROM events' --result-reuse --ttl-minutes 60 # Disable limit enforcement gcx datasources athena query 'SELECT * FROM big_table' --limit 0 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --catalog string Data catalog override --database string Database override -d, --datasource string Datasource UID (required unless datasources.athena is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Max rows to return (0 disables enforcement) (default 100) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --region string AWS region override --result-reuse Enable Athena query result reuse (engine v3) --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') --ttl-minutes int Cache TTL in minutes for result reuse; 0 disables (default 60) ``` Inherits `--config` from [`gcx datasources athena`](#gcx-datasources-athena-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor` Query Azure Monitor datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for azuremonitor ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor list-metrics` List the Azure Monitor metric definitions available for a resource, including each metric’s primary aggregation, unit, and dimensions. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor list-metrics [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor list-metrics -d UID --subscription SUB_ID \ --resource-group my-rg --namespace Microsoft.Storage/storageAccounts --resource mystorage gcx datasources azuremonitor list-metrics -d UID --subscription SUB_ID \ --resource-group my-rg --namespace Microsoft.Compute/virtualMachines --resource my-vm -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.azuremonitor is configured) -h, --help help for list-metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --namespace string Metric namespace, e.g. Microsoft.Storage/storageAccounts (required; matches the resource type from list-resources) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --resource string Azure resource name; use the slash form for sub-resources, e.g. mystorage/blobServices/default (required) --resource-group string Azure resource group name (required) --subscription string Azure subscription ID (defaults to the datasource's default subscription) ``` Inherits `--config` from [`gcx datasources azuremonitor`](#gcx-datasources-azuremonitor-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor list-resource-groups` List the resource groups in an Azure subscription via an Azure Monitor datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor list-resource-groups [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor list-resource-groups -d UID --subscription SUB_ID gcx datasources azuremonitor list-resource-groups -d UID --subscription SUB_ID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.azuremonitor is configured) -h, --help help for list-resource-groups --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --subscription string Azure subscription ID (defaults to the datasource's default subscription) ``` Inherits `--config` from [`gcx datasources azuremonitor`](#gcx-datasources-azuremonitor-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor list-resources` List the Azure resources in a subscription, optionally scoped to a resource group, via an Azure Monitor datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor list-resources [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor list-resources -d UID --subscription SUB_ID --resource-group my-rg gcx datasources azuremonitor list-resources -d UID --subscription SUB_ID -o json # Uses the datasource's default subscription when --subscription is omitted gcx datasources azuremonitor list-resources -d UID ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.azuremonitor is configured) -h, --help help for list-resources --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --resource-group string Azure resource group name (optional; lists the whole subscription when omitted) --subscription string Azure subscription ID (defaults to the datasource's default subscription) ``` Inherits `--config` from [`gcx datasources azuremonitor`](#gcx-datasources-azuremonitor-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor list-subscriptions` List the Azure subscriptions the Azure Monitor datasource’s credentials can access. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor list-subscriptions [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor list-subscriptions -d UID gcx datasources azuremonitor list-subscriptions -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.azuremonitor is configured) -h, --help help for list-subscriptions --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources azuremonitor`](#gcx-datasources-azuremonitor-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor logs` Query Log Analytics workspaces with KQL **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for logs ``` Inherits `--config` from [`gcx datasources azuremonitor`](#gcx-datasources-azuremonitor-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor logs query` Execute a KQL (Kusto Query Language) query against an Azure Log Analytics workspace. KQL is the query expression, e.g. ‘AppRequests | take 10’. The workspace is identified by –subscription, –resource-group, and –workspace; use list-resources to discover workspaces (type Microsoft.OperationalInsights/workspaces). Datasource is resolved from -d flag or datasources.azuremonitor in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor logs query KQL [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Query a workspace gcx datasources azuremonitor logs query 'AppRequests | take 10' -d UID \ --subscription SUB_ID --resource-group my-rg --workspace my-workspace # With a time range gcx datasources azuremonitor logs query 'AppRequests | summarize count() by bin(TimeGenerated, 5m)' \ -d UID --subscription SUB_ID --resource-group my-rg --workspace my-workspace --since 1h # Output as JSON gcx datasources azuremonitor logs query 'AppTraces | take 5' -d UID \ --subscription SUB_ID --resource-group my-rg --workspace my-workspace -o json # Print a Grafana Explore share link for the executed query gcx datasources azuremonitor logs query 'AppRequests | take 10' -d UID \ --subscription SUB_ID --resource-group my-rg --workspace my-workspace --share-link # Open the executed query in Grafana Explore gcx datasources azuremonitor logs query 'AppRequests | take 10' -d UID \ --subscription SUB_ID --resource-group my-rg --workspace my-workspace --open ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.azuremonitor is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --resource-group string Azure resource group of the workspace (required) --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --subscription string Azure subscription ID (required) --to string End time (RFC3339, Unix timestamp, or relative like 'now') --workspace string Log Analytics workspace name (required) ``` Inherits `--config` from [`gcx datasources azuremonitor`](#gcx-datasources-azuremonitor-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor query` Execute an Azure Monitor metrics query. Queries are structured (subscription, resource group, resource, metric namespace, metric, aggregation) — there is no expression language for Azure Monitor metrics. Use –dimensions (repeatable) to filter or split by dimension values: a specific value filters the series, “\*” splits the result into one series per value. Use the list-subscriptions, list-resource-groups, list-resources, and list-metrics subcommands to discover valid flag values. Datasource is resolved from -d flag or datasources.azuremonitor in your context. Note: datasources configured with “Current User” (Azure AD passthrough) authentication cannot be queried with API tokens or service accounts. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor query [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Query a storage account metric gcx datasources azuremonitor query -d UID --subscription SUB_ID \ --resource-group my-rg --namespace Microsoft.Storage/storageAccounts \ --resource mystorage --metric Transactions --aggregation Total --since 1h # Split the series by a dimension gcx datasources azuremonitor query -d UID --subscription SUB_ID \ --resource-group my-rg --namespace Microsoft.Storage/storageAccounts \ --resource mystorage --metric Transactions --aggregation Total \ --dimensions ApiName='*' --since 1h # Output as JSON gcx datasources azuremonitor query -d UID --subscription SUB_ID \ --resource-group my-rg --namespace Microsoft.Compute/virtualMachines \ --resource my-vm --metric 'Percentage CPU' -o json # Print a Grafana Explore share link for the executed query gcx datasources azuremonitor query -d UID --subscription SUB_ID \ --resource-group my-rg --namespace Microsoft.Compute/virtualMachines \ --resource my-vm --metric 'Percentage CPU' --since 1h --share-link # Open the executed query in Grafana Explore gcx datasources azuremonitor query -d UID --subscription SUB_ID \ --resource-group my-rg --namespace Microsoft.Compute/virtualMachines \ --resource my-vm --metric 'Percentage CPU' --since 1h --open ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --aggregation string Aggregation: Average, Total, Maximum, Minimum, or Count (must be supported by the metric; see list-metrics) (default "Average") -d, --datasource string Datasource UID (required unless datasources.azuremonitor is configured) --dimensions stringToString Dimension key=value filters (repeatable, e.g. --dimensions ApiName=GetBlob); use "*" as the value to split the result by that dimension (default []) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --metric string Metric name, e.g. Transactions (required) --namespace string Metric namespace, e.g. Microsoft.Storage/storageAccounts (required) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --region string Azure region, e.g. uksouth (optional; used for multi-resource queries) --resource string Azure resource name; use the slash form for sub-resources, e.g. mystorage/blobServices/default (required) --resource-group string Azure resource group name (required) --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --subscription string Azure subscription ID (defaults to the datasource's default subscription) --time-grain string Time grain as an ISO 8601 duration (e.g. PT1M, PT1H) or "auto" to fit the time range (default "auto") --to string End time (RFC3339, Unix timestamp, or relative like 'now') --top string Maximum number of dimension value series to return (only with --dimensions) ``` Inherits `--config` from [`gcx datasources azuremonitor`](#gcx-datasources-azuremonitor-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor resource-graph` Query Azure Resource Graph with KQL **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for resource-graph ``` Inherits `--config` from [`gcx datasources azuremonitor`](#gcx-datasources-azuremonitor-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources azuremonitor resource-graph query` Execute a KQL (Kusto Query Language) query against Azure Resource Graph, Azure’s inventory of resources across subscriptions. KQL is the query expression, e.g. ‘Resources | project name, type | limit 10’. Pass –subscription (repeatable) to scope the query. Datasource is resolved from -d flag or datasources.azuremonitor in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources azuremonitor resource-graph query KQL [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List resources by type gcx datasources azuremonitor resource-graph query \ 'Resources | summarize count() by type | order by count_ desc' \ -d UID --subscription SUB_ID # Query across multiple subscriptions, output as JSON gcx datasources azuremonitor resource-graph query 'Resources | project name, type, location' \ -d UID --subscription SUB_A --subscription SUB_B -o json # Print a Grafana Explore share link for the executed query gcx datasources azuremonitor resource-graph query 'Resources | project name, type' \ -d UID --subscription SUB_ID --share-link # Open the executed query in Grafana Explore gcx datasources azuremonitor resource-graph query 'Resources | project name, type' \ -d UID --subscription SUB_ID --open ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.azuremonitor is configured) -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --subscription stringArray Azure subscription ID to query (repeatable; at least one required) ``` Inherits `--config` from [`gcx datasources azuremonitor`](#gcx-datasources-azuremonitor-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources bigquery` Query BigQuery datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for bigquery ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources bigquery describe-table` Show column name, data type, and nullability for each column in a table via INFORMATION\_SCHEMA.COLUMNS. The dataset is required, supplied either in the table name (DATASET.TABLE or PROJECT.DATASET.TABLE) or via –dataset. When the project is omitted, the datasource’s default project is used. At most 1000 columns are returned; if a table is wider, a warning is printed on stderr rather than silently truncating. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources bigquery describe-table TABLE [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Describe a table in a dataset (default project; equivalent forms) gcx datasources bigquery describe-table my_dataset.events gcx datasources bigquery describe-table events --dataset my_dataset # Describe a table in a specific project (equivalent forms) gcx datasources bigquery describe-table my-project.my_dataset.events gcx datasources bigquery describe-table events --project my-project --dataset my_dataset # Output as JSON gcx datasources bigquery describe-table my_dataset.events -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dataset string Dataset containing the table (required) -d, --datasource string Datasource UID (required unless datasources.bigquery is configured) -h, --help help for describe-table --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --project string GCP project ID (default: the datasource's default project) ``` Inherits `--config` from [`gcx datasources bigquery`](#gcx-datasources-bigquery-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources bigquery list-datasets` List datasets (schemas) in a BigQuery project via INFORMATION\_SCHEMA.SCHEMATA. When –project is omitted, the datasource’s default project is queried. At most 1000 datasets are returned; if more match, a warning is printed on stderr rather than silently truncating. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources bigquery list-datasets [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List datasets in the default project gcx datasources bigquery list-datasets # List datasets in a specific project gcx datasources bigquery list-datasets --project my-project # Output as JSON gcx datasources bigquery list-datasets -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.bigquery is configured) -h, --help help for list-datasets --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --project string GCP project ID (default: the datasource's default project) ``` Inherits `--config` from [`gcx datasources bigquery`](#gcx-datasources-bigquery-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources bigquery list-tables` List tables in a BigQuery dataset via INFORMATION\_SCHEMA.TABLES. –dataset is required. When –project is omitted, the datasource’s default project is used. Run ’list-datasets’ to discover available datasets. At most 1000 tables are returned; if more match, a warning is printed on stderr rather than silently truncating. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources bigquery list-tables [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List tables in a dataset (default project) gcx datasources bigquery list-tables --dataset my_dataset # List tables in a dataset in a specific project gcx datasources bigquery list-tables --project my-project --dataset my_dataset # Output as JSON gcx datasources bigquery list-tables --dataset my_dataset -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dataset string Dataset to list tables from (required) -d, --datasource string Datasource UID (required unless datasources.bigquery is configured) -h, --help help for list-tables --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --project string GCP project ID (default: the datasource's default project) ``` Inherits `--config` from [`gcx datasources bigquery`](#gcx-datasources-bigquery-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources bigquery query` Execute a GoogleSQL query against a BigQuery datasource. EXPR is the SQL query to execute, passed as a positional argument or via –expr. Datasource is resolved from -d flag or datasources.bigquery in your context. Reference tables as `project.dataset.table`; when the project is omitted the datasource’s default project is used. Server-side macros ($\_\_timeFilter, etc.) are supported against TIMESTAMP columns; a DATETIME column needs an explicit CAST(col AS TIMESTAMP) first, since $\_\_timeFilter substitutes a TIMESTAMP literal BigQuery won’t compare against DATETIME directly. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources bigquery query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Simple query gcx datasources bigquery query 'SELECT count(*) FROM `my-project.my_dataset.events`' # Explicit datasource gcx datasources bigquery query -d UID 'SELECT * FROM `my_dataset.logs`' --since 1h # $__timeFilter against a TIMESTAMP column gcx datasources bigquery query -d UID 'SELECT * FROM `my_dataset.events` WHERE $__timeFilter(event_ts)' --since 1h # Output as JSON gcx datasources bigquery query -d UID 'SELECT 1' -o json # Print a Grafana Explore share link for the executed query gcx datasources bigquery query 'SELECT 1' --share-link # Disable limit enforcement gcx datasources bigquery query 'SELECT * FROM `my_dataset.big_table`' --limit 0 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.bigquery is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Max rows to return; requests above 1000 are capped, with a warning (0 disables enforcement) (default 100) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources bigquery`](#gcx-datasources-bigquery-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources clickhouse` Query ClickHouse datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for clickhouse ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources clickhouse describe-table` Show column details including name, type, default, and comment for each column in the specified table. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources clickhouse describe-table TABLE [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Describe a table in the default database gcx datasources clickhouse describe-table otel_logs # Describe a table in a specific database gcx datasources clickhouse describe-table otel_logs --database otel # Output as JSON gcx datasources clickhouse describe-table otel_logs -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --database string Database name (default: "default") -d, --datasource string Datasource UID (required unless datasources.clickhouse is configured) -h, --help help for describe-table --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx datasources clickhouse`](#gcx-datasources-clickhouse-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources clickhouse list-tables` List tables from all non-system databases, or filter to a specific database. Shows database, name, engine, total\_rows, and total\_bytes for each table. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources clickhouse list-tables [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all tables gcx datasources clickhouse list-tables # Filter to a specific database gcx datasources clickhouse list-tables --database otel # Output as JSON gcx datasources clickhouse list-tables -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --database string Filter tables to this database -d, --datasource string Datasource UID (required unless datasources.clickhouse is configured) -h, --help help for list-tables --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx datasources clickhouse`](#gcx-datasources-clickhouse-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources clickhouse query` Execute a SQL query against a ClickHouse datasource. EXPR is the SQL query to execute, passed as a positional argument or via –expr. Datasource is resolved from -d flag or datasources.clickhouse in your context. Server-side macros ($\_\_timeFilter, $\_\_timeInterval, etc.) are supported. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources clickhouse query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Simple query gcx datasources clickhouse query 'SELECT count() FROM events' # With time macro and explicit datasource gcx datasources clickhouse query -d UID 'SELECT * FROM logs WHERE $__timeFilter(timestamp)' --since 1h # Output as JSON gcx datasources clickhouse query -d UID 'SELECT 1' -o json # Print a Grafana Explore share link for the executed query gcx datasources clickhouse query 'SELECT 1' --share-link # Disable limit enforcement gcx datasources clickhouse query 'SELECT * FROM big_table' --limit 0 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.clickhouse is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Max rows to return (0 disables enforcement) (default 100) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources clickhouse`](#gcx-datasources-clickhouse-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudmonitoring` Query Google Cloud Monitoring datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for cloudmonitoring ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudmonitoring list-metrics` List the Cloud Monitoring metric descriptors available in a project, with kind, value type, and unit. Use –service to narrow the listing (recommended; unfiltered listings page through every metric in the project and can be slow). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudmonitoring list-metrics [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudmonitoring list-metrics -d UID --project my-project --service compute.googleapis.com gcx datasources cloudmonitoring list-metrics -d UID --project my-project --service monitoring.googleapis.com -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.cloudmonitoring is configured) -h, --help help for list-metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --project string GCP project ID (required) --service string Restrict to metrics of this service prefix, e.g. compute.googleapis.com (recommended: unfiltered listings page through every metric and can be slow) ``` Inherits `--config` from [`gcx datasources cloudmonitoring`](#gcx-datasources-cloudmonitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudmonitoring list-projects` List the Google Cloud projects the datasource’s credentials can access. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudmonitoring list-projects [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudmonitoring list-projects -d UID gcx datasources cloudmonitoring list-projects -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.cloudmonitoring is configured) -h, --help help for list-projects --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources cloudmonitoring`](#gcx-datasources-cloudmonitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudmonitoring query` Execute a Google Cloud Monitoring (formerly Stackdriver) metrics query. Queries are structured (project, metric type, reducer, aligner) — there is no expression language. Use –group-by to split the result into one series per label value, and –filter to narrow by labels. –group-by only has an effect when –reducer is set to something other than the default REDUCE\_NONE: GCP’s Aggregation API ignores groupByFields unless a cross-series reducer combines them, so –group-by without –reducer is rejected rather than silently returning one ungrouped series. –filter matches are exact and case-sensitive, not regex or wildcard — GCM has no equivalent of “=~”. Repeated –filter flags are AND-combined. A filter like “zone=~us-east.\*” is not a regex match; it is a literal equality comparison against that exact string, which will not match real zone values and returns “No data” with no error. Use list-projects and list-metrics to discover valid flag values. Datasource is resolved from -d flag or datasources.cloudmonitoring in your context. Use –share-link to print the equivalent Grafana Explore URL after the query, or –open to open it in your browser. Note: when no –from/–to/–since flags are provided, the link encodes “now-1h”/“now” (relative), not the absolute window the CLI just queried. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudmonitoring query [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # CPU utilization across a project gcx datasources cloudmonitoring query -d UID --project my-project \ --metric compute.googleapis.com/instance/cpu/utilization --since 1h # Print a Grafana Explore share link for the executed query gcx datasources cloudmonitoring query -d UID --project my-project \ --metric compute.googleapis.com/instance/cpu/utilization --since 1h --share-link # Run the query and continue in Grafana Explore gcx datasources cloudmonitoring query -d UID --project my-project \ --metric compute.googleapis.com/instance/cpu/utilization --since 1h --open # Split by instance, mean-reduced gcx datasources cloudmonitoring query -d UID --project my-project \ --metric compute.googleapis.com/instance/cpu/utilization \ --reducer REDUCE_MEAN --group-by resource.label.instance_name --since 1h # Chart it gcx datasources cloudmonitoring query -d UID --project my-project \ --metric compute.googleapis.com/instance/cpu/utilization --since 6h -o graph ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --aligner string Per-series aligner: ALIGN_MEAN, ALIGN_SUM, ALIGN_MIN, ALIGN_MAX, ALIGN_RATE, ALIGN_DELTA, ... (default "ALIGN_MEAN") --alignment-period string Alignment period, e.g. +60s (default: auto-fit the time range) -d, --datasource string Datasource UID (required unless datasources.cloudmonitoring is configured) --filter stringToString Label filter key=value (repeatable, AND-combined, exact-match and case-sensitive only — no regex/wildcard; e.g. --filter resource.label.zone=us-east1-b) (default []) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --group-by stringArray Label to split series by, e.g. resource.label.instance_name (repeatable; requires --reducer other than REDUCE_NONE) -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --metric string Metric type, e.g. compute.googleapis.com/instance/cpu/utilization (required) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --project string GCP project ID (required) --reducer string Cross-series reducer: REDUCE_NONE, REDUCE_MEAN, REDUCE_SUM, REDUCE_MIN, REDUCE_MAX, REDUCE_COUNT, ... (default "REDUCE_NONE") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources cloudmonitoring`](#gcx-datasources-cloudmonitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudwatch` Query AWS CloudWatch datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for cloudwatch ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudwatch list-accounts` List the AWS accounts accessible via this CloudWatch datasource. Only returns data for cross-account monitoring datasources; other datasources may return a 404 which is surfaced as a clear error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-accounts [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-accounts -d UID --region us-east-1 gcx datasources cloudwatch list-accounts -d UID --region us-east-1 -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.cloudwatch is configured) -h, --help help for list-accounts --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --region string AWS region (required) ``` Inherits `--config` from [`gcx datasources cloudwatch`](#gcx-datasources-cloudwatch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudwatch list-dimensions` List the dimension keys available for a CloudWatch metric within a namespace and region. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-dimensions [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-dimensions -d UID --region us-east-1 --namespace AWS/EC2 --metric CPUUtilization gcx datasources cloudwatch list-dimensions -d UID --region us-east-1 --namespace AWS/EC2 --metric CPUUtilization -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --account-id string AWS account ID for cross-account monitoring (or 'all') -d, --datasource string Datasource UID (required unless datasources.cloudwatch is configured) -h, --help help for list-dimensions --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --metric string CloudWatch metric name (required) --namespace string CloudWatch namespace (required) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --region string AWS region (required) ``` Inherits `--config` from [`gcx datasources cloudwatch`](#gcx-datasources-cloudwatch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudwatch list-metrics` List the CloudWatch metrics available within a namespace and region from a CloudWatch datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-metrics [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-metrics -d UID --region us-east-1 --namespace AWS/EC2 gcx datasources cloudwatch list-metrics -d UID --region us-east-1 --namespace AWS/Lambda -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --account-id string AWS account ID for cross-account monitoring (or 'all') -d, --datasource string Datasource UID (required unless datasources.cloudwatch is configured) -h, --help help for list-metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --namespace string CloudWatch namespace (required) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --region string AWS region (required) ``` Inherits `--config` from [`gcx datasources cloudwatch`](#gcx-datasources-cloudwatch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudwatch list-namespaces` List the CloudWatch namespaces visible in the given region from a CloudWatch datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-namespaces [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-namespaces -d UID --region us-east-1 gcx datasources cloudwatch list-namespaces -d UID --region us-east-1 -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --account-id string AWS account ID for cross-account monitoring (or 'all') -d, --datasource string Datasource UID (required unless datasources.cloudwatch is configured) -h, --help help for list-namespaces --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --region string AWS region (required) ``` Inherits `--config` from [`gcx datasources cloudwatch`](#gcx-datasources-cloudwatch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudwatch list-regions` List the AWS regions exposed by the configured CloudWatch datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-regions [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch list-regions -d UID gcx datasources cloudwatch list-regions -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.cloudwatch is configured) -h, --help help for list-regions --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources cloudwatch`](#gcx-datasources-cloudwatch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources cloudwatch query` Execute a CloudWatch metric query. Queries are structured (namespace, metric, region, statistic, period, dimensions) — there is no expression language for CloudWatch. Use –dimensions (repeatable) for dimension filters, or omit them to aggregate across all combinations. Use –share-link to print the equivalent Grafana Explore URL after the query. Note: when no –from/–to/–since flags are provided, the share link encodes “now-1h”/“now” (relative), not the absolute window the CLI just queried. Cross-account monitoring datasources: if your datasource is configured for cross-account monitoring (a “monitoring account”), –dimensions filters scope to the datasource’s own account by default. To surface dimensions from source accounts, pass –account-id (run list-accounts to discover IDs) or –account-id all to query all linked accounts. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources cloudwatch query [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Query with required flags gcx datasources cloudwatch query -d UID --region us-east-1 --namespace AWS/EC2 --metric CPUUtilization # With time range gcx datasources cloudwatch query -d UID --region us-east-1 --namespace AWS/EC2 --metric CPUUtilization --since 1h # With dimension filter gcx datasources cloudwatch query -d UID --region us-east-1 --namespace AWS/EC2 --metric CPUUtilization \ --dimensions InstanceId=i-0123456789abcdef0 --since 1h # Print as JSON gcx datasources cloudwatch query -d UID --region us-east-1 --namespace AWS/EC2 --metric CPUUtilization -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --account-id string AWS account ID for cross-account monitoring; pass 'all' to query all linked accounts, or a specific ID from list-accounts. Required to surface dimensions from source accounts on monitoring datasources. -d, --datasource string Datasource UID (required unless datasources.cloudwatch is configured) --dimensions stringToString Dimension key=value pairs (repeatable, e.g. --dimensions InstanceId=i-abc) (default []) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --metric string CloudWatch metric name, e.g. CPUUtilization (required) --namespace string CloudWatch namespace, e.g. AWS/EC2 (required) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --period string Period in seconds (e.g. 60, 300) or "auto" to let CloudWatch pick a period that fits the time range (default "auto") --region string AWS region, e.g. us-east-1 (required) --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --statistic string Statistic: Average, Sum, Maximum, Minimum, SampleCount, or a percentile/trimmed-mean (e.g. p95, p99, tm99) (default "Average") --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources cloudwatch`](#gcx-datasources-cloudwatch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources create` Create a datasource instance from a declarative manifest file. The manifest is a Kubernetes-style envelope. spec.type is the plugin ID (e.g. grafana-sentry-datasource) and selects the API group. Secret values go in the top-level secure block via {create: }, {fromEnv: `}, or {fromFile: }; they are never returned on read.` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources create [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Create a datasource from a YAML manifest gcx datasources create -f sentry.yaml # Create from stdin cat sentry.yaml | gcx datasources create -f - # Preview without writing gcx datasources create -f sentry.yaml --dry-run ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use --dry-run Render the object that would be created without writing it -f, --filename string File containing the datasource manifest (use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") --secrets-file string File containing secret values to merge into the secure block ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources delete` Delete one or more datasources by UID. Deletion prompts for confirmation unless –force/–yes, GCX\_AUTO\_APPROVE, or agent mode is in effect. Exit codes: 0 (all deleted), 4 (some deletions failed). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources delete UID... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Delete one datasource (prompts to confirm) gcx datasources delete sentry-dev # Delete several without prompting gcx datasources delete sentry-dev sentry-staging --yes # Preview only gcx datasources delete sentry-dev --dry-run ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use --dry-run Report what would be deleted without deleting --force Skip the confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") -y, --yes Skip the confirmation prompt ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources elasticsearch` Query Elasticsearch datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for elasticsearch ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources elasticsearch list-fields` List the mapped fields and their types, per index. Nested object fields are flattened with dotted names. Use these names in Lucene queries and –group-by. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources elasticsearch list-fields [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # All fields across indices gcx datasources elasticsearch list-fields # Fields of one index gcx datasources elasticsearch list-fields -d UID --index grafana-logs -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.elasticsearch is configured) -h, --help help for list-fields --index string Restrict to this index or index pattern --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources elasticsearch`](#gcx-datasources-elasticsearch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources elasticsearch list-indices` List the indices visible to an Elasticsearch datasource, with their mapped field counts. Pass –index to restrict to one index or pattern; fetching the mapping for every index can hit the response size cap on a large cluster. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources elasticsearch list-indices [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources elasticsearch list-indices gcx datasources elasticsearch list-indices -d UID -o json # Restrict to one index or pattern gcx datasources elasticsearch list-indices -d UID --index grafana-logs ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.elasticsearch is configured) -h, --help help for list-indices --index string Restrict to this index or index pattern --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources elasticsearch`](#gcx-datasources-elasticsearch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources elasticsearch metrics` Run a metric aggregation bucketed by a time histogram, optionally split into series by a terms field. EXPR is a Lucene query string scoping the documents; omit it to aggregate all. Returns (time, value, series) rows. Use –step to control bucket size. Datasource is resolved from -d flag or datasources.elasticsearch in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources elasticsearch metrics [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Document count over time gcx datasources elasticsearch metrics --since 6h # Error count per app gcx datasources elasticsearch metrics 'level:error' --group-by app.keyword --since 6h # Average value of a numeric field gcx datasources elasticsearch metrics --agg avg --field duration_ms --since 1h -o json # Print a Grafana Explore share link for the executed query gcx datasources elasticsearch metrics 'level:error' --since 6h --share-link # Continue the same aggregation in Grafana Explore gcx datasources elasticsearch metrics 'level:error' --since 6h --open ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --agg string Metric aggregation: count, avg, sum, min, max, or cardinality (default "count") -d, --datasource string Datasource UID (required unless datasources.elasticsearch is configured) --expr string Query expression (alternative to positional argument) --field string Field to aggregate (required unless --agg count) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --group-by string Split series by this field's terms (use .keyword for text fields) --group-size int Max number of series when using --group-by (default 10) -h, --help help for metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --time-field string Time field for the date histogram bucket (defaults to the datasource's configured time field if omitted) --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources elasticsearch`](#gcx-datasources-elasticsearch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources elasticsearch query` Search documents in an Elasticsearch datasource with a Lucene query. EXPR is a Lucene query string (e.g. ‘app:frontend AND level:error’); omit it to match all documents in the time range. The index pattern comes from the datasource configuration. –mode documents (default) returns raw source documents. –mode logs returns the same documents newest-first with plugin-internal fields (\_source, sort, highlight, \_type) omitted, matching how Grafana Explore’s Logs view reads them. Datasource is resolved from -d flag or datasources.elasticsearch in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources elasticsearch query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Match all documents in the last hour gcx datasources elasticsearch query --since 1h # Lucene query with explicit datasource gcx datasources elasticsearch query -d UID 'app:frontend AND level:error' --since 1h # Newest-first logs, plugin-internal fields omitted gcx datasources elasticsearch query -d UID 'level:error' --mode logs --since 6h --limit 50 # Output as JSON, limit results gcx datasources elasticsearch query -d UID 'datacenter:us-east' --limit 20 -o json # Print a Grafana Explore share link for the executed query gcx datasources elasticsearch query 'level:error' --since 1h --share-link # Continue the same search in Grafana Explore gcx datasources elasticsearch query 'level:error' --since 1h --open ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.elasticsearch is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Max documents to return (1-1000) (default 100) --mode string Search mode: "documents" (raw documents) or "logs" (newest-first, plugin-internal fields omitted) (default "documents") --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources elasticsearch`](#gcx-datasources-elasticsearch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources get` Get a datasource by its UID. The default text output shows a human-readable detail view. -o yaml/json emits an apply-ready manifest that can be edited and re-applied via update -f -. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources get UID [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Human-readable detail gcx datasources get my-prometheus # Apply-ready manifest (round-trips into update -f -) gcx datasources get my-prometheus -o yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources health` Check datasource health via the Grafana datasource health endpoint. With a UID, checks a single datasource. Without arguments, checks all datasources. Use –type to check all datasources of a given plugin type. Exit codes distinguish resource failure from command failure: 0 - all checked datasources are healthy 4 - the check ran but one or more datasources are unhealthy (resource failure) 1/2/3 - the check could not run (operational, usage, or auth failure) shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources health [UID] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Check a single datasource gcx datasources health my-ds-uid # Check all datasources gcx datasources health # Check all datasources of a given type gcx datasources health --type grafana-sentry-datasource ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use -h, --help help for health --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") -t, --type string Filter by datasource type (e.g., prometheus, grafana-sentry-datasource) ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources infinity` Query Infinity datasources (JSON, CSV, XML, GraphQL from any URL) **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for infinity ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources infinity query` Query a Grafana Infinity datasource using its saved configuration. The datasource’s URL, type, method, and headers are read from its saved configuration. EXPR is an optional root selector expression (JSONPath for JSON, XPath for XML/HTML) that narrows the returned data. Datasource is resolved from -d flag or datasources.infinity in your context. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources infinity query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Query using datasource UID gcx datasources infinity query -d UID # Narrow results with a JSONPath expression gcx datasources infinity query -d UID '$.items' # Output as JSON gcx datasources infinity query -d UID '$.results' -o json # Query with a time range gcx datasources infinity query -d UID --from now-24h --to now ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.infinity is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources infinity`](#gcx-datasources-infinity-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources influxdb` Query InfluxDB datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for influxdb ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources influxdb list-field-keys` List field keys from an InfluxDB datasource. Only supported in InfluxQL mode. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources influxdb list-field-keys [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all field keys (use datasource UID, not name) gcx datasources influxdb list-field-keys -d UID # Filter by measurement gcx datasources influxdb list-field-keys -d UID --measurement cpu # Output as JSON gcx datasources influxdb list-field-keys -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.influxdb is configured) -h, --help help for list-field-keys --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -m, --measurement string Filter by measurement name -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources influxdb`](#gcx-datasources-influxdb-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources influxdb list-measurements` List measurement names from an InfluxDB datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources influxdb list-measurements [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all measurements (use datasource UID, not name) gcx datasources influxdb list-measurements -d UID # List measurements with Flux mode (requires --bucket) gcx datasources influxdb list-measurements -d UID --bucket my-bucket # Output as JSON gcx datasources influxdb list-measurements -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --bucket string Bucket name for Flux mode (defaults to datasource defaultBucket) -d, --datasource string Datasource UID (required unless datasources.influxdb is configured) -h, --help help for list-measurements --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources influxdb`](#gcx-datasources-influxdb-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources influxdb list-tag-keys` List tag keys from an InfluxDB datasource. Only supported in InfluxQL mode. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources influxdb list-tag-keys [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all tag keys (use datasource UID, not name) gcx datasources influxdb list-tag-keys -d UID # Filter by measurement gcx datasources influxdb list-tag-keys -d UID --measurement cpu # Output as JSON gcx datasources influxdb list-tag-keys -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.influxdb is configured) -h, --help help for list-tag-keys --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -m, --measurement string Filter by measurement name -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources influxdb`](#gcx-datasources-influxdb-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources influxdb list-tag-values` List tag values for a given key from an InfluxDB datasource. Only supported in InfluxQL mode. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources influxdb list-tag-values [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List values for a tag key (use datasource UID, not name) gcx datasources influxdb list-tag-values -d UID --key host # Filter by measurement gcx datasources influxdb list-tag-values -d UID --key host --measurement cpu # Output as JSON gcx datasources influxdb list-tag-values -d UID --key host -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.influxdb is configured) -h, --help help for list-tag-values --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -k, --key string Tag key to get values for (required) -m, --measurement string Filter by measurement name -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources influxdb`](#gcx-datasources-influxdb-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources influxdb query` Execute a query against an InfluxDB datasource. EXPR is the InfluxQL, Flux, or SQL expression to evaluate, passed as a positional argument or via –expr. The query language mode is auto-detected from the datasource configuration. Datasource is resolved from -d flag or datasources.influxdb in your context. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources influxdb query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # InfluxQL instant query gcx datasources influxdb query -d UID 'SELECT mean("value") FROM "cpu" WHERE time > now() - 1h' # InfluxQL range query gcx datasources influxdb query -d UID 'SELECT mean("value") FROM "cpu"' --from now-1h --to now # Output as JSON gcx datasources influxdb query -d UID 'SELECT * FROM "cpu" LIMIT 10' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.influxdb is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources influxdb`](#gcx-datasources-influxdb-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources list` List all datasources configured in Grafana. Filter by type and/or name (case-insensitive substring match). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all datasources gcx datasources list # List only Prometheus datasources gcx datasources list --type prometheus # Filter by name substring (matches "prometheus-prod-eu", "loki-prod-us", ...) gcx datasources list --name prod # Combine type and name filters gcx datasources list --type prometheus --name prod # Output as JSON gcx datasources list -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of datasources to return. 0 means all results are returned --name string Filter by datasource name (case-insensitive substring match) -o, --output string Output format. One of: agents, json, table, yaml (default "table") -t, --type string Filter by datasource type (e.g., prometheus, loki) ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources loki` Query Loki datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for loki ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources loki labels` List all labels or get values for a specific label from a Loki datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources loki labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all labels (use datasource UID, not name) gcx datasources loki labels -d UID # Get values for a specific label gcx datasources loki labels -d UID --label job # Output as JSON gcx datasources loki labels -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.loki is configured) -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label string Get values for this label (omit to list all labels) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources loki`](#gcx-datasources-loki-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources loki metrics` Execute a metric LogQL query and return time-series results. EXPR is a metric LogQL expression (e.g., rate, count\_over\_time, sum). Datasource is resolved from -d flag or datasources.loki in your context. Unlike ’logs query’ which returns log lines, ’logs metrics’ returns time-series data with proper table, graph, and JSON formatters. Instant vs range is deduced from time flags: no time flags = instant query, –since or –from/–to = range query. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources loki metrics [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Rate of log lines over 5 minutes gcx datasources loki metrics 'rate({job="varlogs"}[5m])' --since 1h -o table # Count of error logs gcx datasources loki metrics 'count_over_time({job="varlogs"} |= "error" [5m])' --since 1h # Print a Grafana Explore share link for the query gcx datasources loki metrics 'rate({job="varlogs"}[5m])' --share-link # Line chart output gcx datasources loki metrics -d loki-001 'rate({job="varlogs"}[5m])' --since 1h -o graph # Output as JSON gcx datasources loki metrics 'rate({job="varlogs"}[5m])' --since 1h -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.loki is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources loki`](#gcx-datasources-loki-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources loki query` Execute a LogQL query against a Loki datasource. EXPR is the LogQL expression to evaluate. Datasource is resolved from -d flag or datasources.loki in your context. Default table output is optimized for humans. Use -o raw for original line bodies or -o json for the full structured response. Default –limit is 50; use –limit 0 for no cap. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources loki query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Query logs using configured default datasource gcx datasources loki query '{job="varlogs"}' # Query with explicit datasource UID gcx datasources loki query -d UID '{job="varlogs"} |= "error"' # Print a Grafana Explore share link for the query gcx datasources loki query '{job="varlogs"}' --share-link # Raw line bodies only gcx datasources loki query -d UID '{job="varlogs"}' -o raw # Output as JSON gcx datasources loki query -d UID '{job="varlogs"}' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.loki is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of log lines to return (0 means no limit) (default 50) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, raw, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources loki`](#gcx-datasources-loki-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources loki series` List log streams (series) from a Loki datasource using LogQL stream selectors. At least one –match selector is required. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources loki series [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List series matching a selector (use datasource UID, not name) gcx datasources loki series -d UID --match '{job="varlogs"}' # Match with regex and multiple labels gcx datasources loki series -d UID --match '{container_name=~"prometheus.*", component="server"}' # Multiple matchers (OR logic) gcx datasources loki series -d UID --match '{job="varlogs"}' --match '{namespace="default"}' # Output as JSON gcx datasources loki series -d UID --match '{job="varlogs"}' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.loki is configured) -h, --help help for series --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -M, --match stringArray LogQL stream selector (required, e.g., '{job="varlogs"}') -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources loki`](#gcx-datasources-loki-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources mssql` Query Microsoft SQL Server datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for mssql ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources mssql describe-table` List the columns of the specified table from INFORMATION\_SCHEMA.COLUMNS, reporting name, data type, nullability, max length, and default. Disambiguate a table that exists in multiple schemas with a schema-qualified name (SCHEMA.TABLE) or the –schema flag. INFORMATION\_SCHEMA is per-database, so this only sees tables in the datasource’s configured database — it cannot describe a table in another database on the same server. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources mssql describe-table TABLE [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Describe a table gcx datasources mssql describe-table WORLD_DATA # Restrict to a schema (equivalent forms) gcx datasources mssql describe-table dbo.WORLD_DATA gcx datasources mssql describe-table WORLD_DATA --schema dbo # Output as JSON gcx datasources mssql describe-table WORLD_DATA -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.mssql is configured) -h, --help help for describe-table --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --schema string Schema the table belongs to (e.g. dbo) ``` Inherits `--config` from [`gcx datasources mssql`](#gcx-datasources-mssql-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources mssql list-tables` List base tables and views from INFORMATION\_SCHEMA.TABLES, optionally filtered to a single schema. Reports schema, name, and type for each. INFORMATION\_SCHEMA is per-database, so this only sees tables in the datasource’s configured database — it cannot list tables in another database on the same server. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources mssql list-tables [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all tables and views gcx datasources mssql list-tables # Filter to the dbo schema gcx datasources mssql list-tables --schema dbo # Output as JSON gcx datasources mssql list-tables -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.mssql is configured) -h, --help help for list-tables --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --schema string Filter tables to this schema (e.g. dbo) ``` Inherits `--config` from [`gcx datasources mssql`](#gcx-datasources-mssql-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources mssql query` Execute a SQL query against a Microsoft SQL Server datasource. EXPR is the SQL query to execute, passed as a positional argument or via –expr. Datasource is resolved from -d flag or datasources.mssql in your context. Server-side macros ($\_\_timeFilter, $\_\_timeGroup, etc.) are supported. Use –step to set the interval the $\_\_interval / $\_\_timeGroup(col, $\_\_interval) macros resolve to (e.g. –step 1h buckets time-series results hourly). T-SQL has no LIMIT keyword. By default the result is capped with an injected TOP (n) clause (see –limit); use –limit 0 to disable it, or write your own TOP / OFFSET … FETCH. Injection only applies to simple leading-SELECT statements — CTEs (WITH), set operations (UNION/INTERSECT/EXCEPT), queries that already use TOP, and OFFSET/FETCH queries are left unchanged. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources mssql query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Simple query (capped at TOP (100)) gcx datasources mssql query 'SELECT name, id FROM dbo.WORLD_DATA' # With time macro and explicit datasource gcx datasources mssql query -d UID 'SELECT * FROM events WHERE $__timeFilter(created_at)' --since 1h # Time-series query bucketed hourly via --step (feeds $__interval) gcx datasources mssql query -d UID 'SELECT $__timeGroup(created_at, $__interval) AS t, COUNT(*) FROM events GROUP BY $__timeGroup(created_at, $__interval)' --since 24h --step 1h # Cap at 10 rows (injects TOP (10)) gcx datasources mssql query -d UID 'SELECT * FROM dbo.WORLD_DATA' --limit 10 # Disable TOP injection and output JSON gcx datasources mssql query 'SELECT * FROM dbo.WORLD_DATA' --limit 0 -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.mssql is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Max rows to return via injected TOP (n) (0 disables injection) (default 100) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources mssql`](#gcx-datasources-mssql-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources mysql` Query MySQL datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for mysql ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources mysql describe-table` Show the columns of a MySQL table: name, column type, nullability, and default. The table can be database-qualified (db.table); otherwise use –database to disambiguate when the same table name exists in multiple databases. TABLE and –database both match exactly and are case-sensitive, which can differ from how information\_schema itself compares names depending on the server’s platform and lower\_case\_table\_names setting. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources mysql describe-table TABLE [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Describe a table gcx datasources mysql describe-table orders -d UID # Disambiguate by database gcx datasources mysql describe-table mydb.orders gcx datasources mysql describe-table orders --database mydb # Output as JSON gcx datasources mysql describe-table orders -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --database string Database of the table (exact match, case-sensitive; defaults to all databases) -d, --datasource string Datasource UID (required unless datasources.mysql is configured) -h, --help help for describe-table --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx datasources mysql`](#gcx-datasources-mysql-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources mysql list-tables` List tables and views from all non-system databases, or filter to a specific database. Shows database, name, and type for each table. –database matches exactly and is case-sensitive. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources mysql list-tables [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all tables gcx datasources mysql list-tables -d UID # Filter to a specific database gcx datasources mysql list-tables --database mydb # Output as JSON gcx datasources mysql list-tables -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --database string Filter tables to this database (exact match, case-sensitive) -d, --datasource string Datasource UID (required unless datasources.mysql is configured) -h, --help help for list-tables --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx datasources mysql`](#gcx-datasources-mysql-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources mysql query` Execute a SQL query against a MySQL datasource. EXPR is the SQL query to execute, passed as a positional argument or via –expr. Datasource is resolved from -d flag or datasources.mysql in your context. Server-side macros ($\_\_timeFilter, $\_\_timeGroup, etc.) are supported. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources mysql query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Simple query gcx datasources mysql query 'SELECT count(*) FROM orders' # With time macro and explicit datasource gcx datasources mysql query -d UID 'SELECT * FROM events WHERE $__timeFilter(created_at)' --since 1h # Output as JSON gcx datasources mysql query -d UID 'SELECT 1' -o json # Disable limit enforcement gcx datasources mysql query 'SELECT * FROM big_table' --limit 0 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.mysql is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Max rows to return; requests above 1000 are capped, with a warning (0 disables enforcement) (default 100) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources mysql`](#gcx-datasources-mysql-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources opensearch` Query OpenSearch datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for opensearch ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources opensearch list-fields` List the mapped fields and their types, per index. Nested object fields are flattened with dotted names. Use these names in Lucene queries and –group-by. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources opensearch list-fields [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # All fields across indices gcx datasources opensearch list-fields # Fields of one index gcx datasources opensearch list-fields -d UID --index grafana-logs -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.opensearch is configured) -h, --help help for list-fields --index string Restrict to this index or index pattern --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources opensearch`](#gcx-datasources-opensearch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources opensearch list-indices` List the indices visible to an OpenSearch datasource, with their mapped field counts. Pass –index to restrict to one index or pattern; fetching the mapping for every index can hit the response size cap on a large cluster. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources opensearch list-indices [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources opensearch list-indices gcx datasources opensearch list-indices -d UID -o json # Restrict to one index or pattern gcx datasources opensearch list-indices -d UID --index grafana-logs ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.opensearch is configured) -h, --help help for list-indices --index string Restrict to this index or index pattern --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources opensearch`](#gcx-datasources-opensearch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources opensearch metrics` Run a metric aggregation bucketed by a time histogram, optionally split into series by a terms field. EXPR is a Lucene query string scoping the documents; omit it to aggregate all. Returns (time, value, series) rows. Use –step to control bucket size. Datasource is resolved from -d flag or datasources.opensearch in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources opensearch metrics [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Document count over time gcx datasources opensearch metrics --since 6h # Error count per app gcx datasources opensearch metrics 'level:error' --group-by app.keyword --since 6h # Average value of a numeric field gcx datasources opensearch metrics --agg avg --field duration_ms --since 1h -o json # Print a Grafana Explore share link for the executed query gcx datasources opensearch metrics 'level:error' --since 6h --share-link # Continue the same aggregation in Grafana Explore gcx datasources opensearch metrics 'level:error' --since 6h --open ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --agg string Metric aggregation: count, avg, sum, min, max, or cardinality (default "count") -d, --datasource string Datasource UID (required unless datasources.opensearch is configured) --expr string Query expression (alternative to positional argument) --field string Field to aggregate (required unless --agg count) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --group-by string Split series by this field's terms (use .keyword for text fields) --group-size int Max number of series when using --group-by (1-1000) (default 10) -h, --help help for metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --time-field string Time field for the date histogram bucket (defaults to the datasource's configured time field if omitted) --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources opensearch`](#gcx-datasources-opensearch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources opensearch query` Search documents in an OpenSearch datasource with a Lucene query. EXPR is a Lucene query string (e.g. ‘app:frontend AND level:error’); omit it to match all documents in the time range. The index pattern comes from the datasource configuration. –mode documents (default) returns raw source documents. –mode logs returns the same documents newest-first with plugin-internal fields (\_source, sort, highlight, \_type) omitted, matching how Grafana Explore’s Logs view reads them. Datasource is resolved from -d flag or datasources.opensearch in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources opensearch query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Match all documents in the last hour gcx datasources opensearch query --since 1h # Lucene query with explicit datasource gcx datasources opensearch query -d UID 'app:frontend AND level:error' --since 1h # Newest-first logs, plugin-internal fields omitted gcx datasources opensearch query -d UID 'level:error' --mode logs --since 6h --limit 50 # Output as JSON, limit results gcx datasources opensearch query -d UID 'datacenter:us-east' --limit 20 -o json # Print a Grafana Explore share link for the executed query gcx datasources opensearch query 'level:error' --since 1h --share-link # Continue the same search in Grafana Explore gcx datasources opensearch query 'level:error' --since 1h --open ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.opensearch is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Max documents to return (1-1000) (default 100) --mode string Search mode: "documents" (raw documents) or "logs" (newest-first, plugin-internal fields omitted) (default "documents") --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources opensearch`](#gcx-datasources-opensearch-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pinot` Query StarTree Pinot datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for pinot ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pinot query` Execute a PinotQL query against a StarTree Pinot datasource. EXPR is the SQL query to execute, passed as a positional argument or via –expr. Datasource is resolved from -d flag or datasources.pinot in your context. Server-side macros ($\_\_timeFilter, $\_\_timeGroup, etc.) are supported. Table name (StarTree tableName field): - StarTree requires tableName to load schema and expand macros before it runs pinotQlCode (sent alongside your SQL in the query request). - By default, gcx derives tableName from the first real FROM in the SQL. - Derivation supports schema.table, double-quoted identifiers, and the inner table in FROM (subquery) … (for example SELECT … FROM (SELECT … FROM events)). - Ignored for derivation: FROM inside string literals, line or block comments, or EXTRACT/TRIM/SUBSTRING/OVERLAY calls (they are not table clauses). - When the SQL has no extractable table (for example SELECT 1), pass –table with a table the query actually uses; the command fails otherwise. - –table overrides any name that would be derived from the SQL. Row limit (–limit): - Default 100 when –limit is omitted on this command and the expression does not have a LIMIT; generic gcx datasources query uses the same Pinot default when the datasource kind is pinot. - –limit 0 disables enforcement (SQL is sent unchanged) and prints no notice. - Requests above 1000 are capped to 1000 in the emitted LIMIT when the SQL can be rewritten. –limit never overwrites an existing LIMIT n that is already at or below 1000. - Only SELECT/WITH-shaped PinotQL may be rewritten; optional leading SET …; prefixes are ignored for this check. - Left unchanged (no append): UNION, OFFSET, LIMIT offset,count, OPTION(…), trailing line comments, LIMIT before a trailing comment, unclosed block comments; keywords only in string literals or comments do not trigger these. - A LIMIT inside a comment (LIMIT /* note \*/ n) still counts as an existing LIMIT. The number is read after comments are blanked but the SQL is not rewritten because it is not safe to modify. Stderr notices (one line, never the full SQL): When –limit N is set: | Query | Sent | Notice | |——————————-|—————–|——–| | no LIMIT, safe | append LIMIT N | Query adjusted: appended LIMIT N (–limit). Use –limit 0 to disable enforcement. | | no LIMIT, not safe | unchanged | You asked for –limit N, but a row limit was not appended (this query shape is not safe to modify). Add LIMIT in the SQL or use –limit 0. | | has LIMIT, n == N | unchanged | (none) | | has LIMIT, n != N, n <= 1000 | unchanged | You requested –limit N but the query already has a LIMIT, so no change was applied. | | bare LIMIT n, n > 1000 | LIMIT 1000 | You requested –limit N but the existing LIMIT was above the maximum, so it was reduced to 1000. | | LIMIT /* … \*/ n, n > 1000 | unchanged | The query has a LIMIT above 1000 that should be reduced to 1000, but the query is not safe to modify. | When –limit is omitted (default 100): | Query | Sent | Notice | |——————————-|—————–|——–| | no LIMIT, safe | append LIMIT 100 | Query adjusted: appended default LIMIT 100. Use –limit 0 to disable enforcement. | | no LIMIT, not safe | unchanged | (none) | | has LIMIT, n <= 1000 | unchanged | (none) | | bare LIMIT n, n > 1000 | LIMIT 1000 | Query adjusted: LIMIT reduced to 1000 (maximum). Use –limit 0 to disable enforcement. | | LIMIT /* … \*/ n, n > 1000 | unchanged | The query has a LIMIT above 1000 that should be reduced to 1000, but the query is not safe to modify. | Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pinot query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Simple query gcx datasources pinot query -d UID 'SELECT count(*) FROM events' # With time range gcx datasources pinot query -d UID --since 7d \ 'SELECT count(*) FROM events WHERE $__timeFilter("timestamp")' # Output as JSON gcx datasources pinot query -d UID 'SELECT 1 FROM events' -o json # Print a Grafana Explore share link for the executed query gcx datasources pinot query -d UID 'SELECT 1 FROM events' --share-link # Disable limit enforcement gcx datasources pinot query -d UID 'SELECT * FROM events' --limit 0 # SQL with no extractable table gcx datasources pinot query -d UID --table events 'SELECT 1' ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pinot is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Max rows to return; requests above 1000 are capped (stderr notice when the query is adjusted). 0 disables enforcement (default 100) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --table string StarTree table name when the SQL has no extractable FROM (required in that case) --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources pinot`](#gcx-datasources-pinot-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources postgres` Query PostgreSQL datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for postgres ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources postgres describe-table` Show the columns of a PostgreSQL table: name, data type, nullability, and default. The table can be schema-qualified (schema.table); otherwise use –schema to disambiguate when the same table name exists in multiple schemas. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources postgres describe-table TABLE [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Describe a table gcx datasources postgres describe-table orders -d UID # Disambiguate by schema gcx datasources postgres describe-table public.orders gcx datasources postgres describe-table orders --schema public # Output as JSON gcx datasources postgres describe-table orders -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.postgres is configured) -h, --help help for describe-table --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --schema string Schema of the table (exact match, case-sensitive; defaults to all schemas) ``` Inherits `--config` from [`gcx datasources postgres`](#gcx-datasources-postgres-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources postgres list-tables` List tables and views from all non-system schemas, or filter to a specific schema. Shows schema, name, and type for each table. –schema matches exactly and is case-sensitive. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources postgres list-tables [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all tables gcx datasources postgres list-tables -d UID # Filter to a specific schema gcx datasources postgres list-tables --schema public # Output as JSON gcx datasources postgres list-tables -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.postgres is configured) -h, --help help for list-tables --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --schema string Filter tables to this schema (exact match, case-sensitive) ``` Inherits `--config` from [`gcx datasources postgres`](#gcx-datasources-postgres-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources postgres query` Execute a SQL query against a PostgreSQL datasource. EXPR is the SQL query to execute, passed as a positional argument or via –expr. Datasource is resolved from -d flag or datasources.postgres in your context. Server-side macros ($\_\_timeFilter, $\_\_timeGroup, etc.) are supported. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources postgres query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Simple query gcx datasources postgres query 'SELECT count(*) FROM orders' # With time macro and explicit datasource gcx datasources postgres query -d UID 'SELECT * FROM events WHERE $__timeFilter(created_at)' --since 1h # Output as JSON gcx datasources postgres query -d UID 'SELECT 1' -o json # Disable limit enforcement gcx datasources postgres query 'SELECT * FROM big_table' --limit 0 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.postgres is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Max rows to return; requests above 1000 are capped, with a warning (0 disables enforcement) (default 100) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources postgres`](#gcx-datasources-postgres-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources prometheus` Query Prometheus datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for prometheus ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources prometheus labels` List all labels or get values for a specific label from a Prometheus datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources prometheus labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all labels (use datasource UID, not name) gcx datasources prometheus labels -d UID # Get values for a specific label gcx datasources prometheus labels -d UID --label job # List labels present on a metric gcx datasources prometheus labels -d UID --metric http_requests_total # Get values a label takes on a metric gcx datasources prometheus labels -d UID --metric http_requests_total --label job # Scope with an arbitrary series selector gcx datasources prometheus labels -d UID --match '{job="api"}' # Output as JSON gcx datasources prometheus labels -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label string Get values for this label (omit to list all labels) --match stringArray Series selector(s) to scope results; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) --metric string Only results from series of this metric (narrows every --match selector) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources prometheus`](#gcx-datasources-prometheus-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources prometheus metadata` Get metadata (type, help text) for metrics from a Prometheus datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources prometheus metadata [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Get all metric metadata (use datasource UID, not name) gcx datasources prometheus metadata -d UID # Get metadata for a specific metric gcx datasources prometheus metadata -d UID --metric http_requests_total # Output as JSON gcx datasources prometheus metadata -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) -h, --help help for metadata --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -m, --metric string Filter by metric name -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources prometheus`](#gcx-datasources-prometheus-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources prometheus query` Execute a PromQL query against a Prometheus datasource. EXPR is the PromQL expression to evaluate, passed as a positional argument or via –expr (familiar to promtool users). Datasource is resolved from -d flag or datasources.prometheus in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources prometheus query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Instant query using configured default datasource gcx datasources prometheus query 'up{job="grafana"}' # Instant query at a specific time gcx datasources prometheus query 'rate(http_requests_total[5m])' --time 2026-01-15T10:30:00Z # Range query with explicit datasource UID gcx datasources prometheus query -d UID 'rate(http_requests_total[5m])' --from now-1h --to now --step 1m # Query the last hour gcx datasources prometheus query 'up' --since 1h # Print a Grafana Explore share link for the executed query gcx datasources prometheus query 'up' --share-link # Output as JSON gcx datasources prometheus query -d UID 'up' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --time string Evaluation time for an instant query (RFC3339, Unix timestamp, or relative like 'now-5m'). Mutually exclusive with --from/--to/--since --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources prometheus`](#gcx-datasources-prometheus-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources prometheus search-label-names` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Search label names from a Prometheus/Mimir datasource. Requires TERM (performs a fuzzy search; multiple TERM values combine as OR), or a scope instead: –metric, –metric-regex or –match. sort\_by=score (the default) requires a search term — omitting TERM in favor of a scope falls back to sort\_by=alpha, and an explicit –sort-by=score without TERM is rejected. –metric-regex is used exactly as given — PromQL anchors =~ at ^…$, so “kube” matches only a metric literally named “kube”, not one containing it. Write “.*kube.*” for a contains search. Without –from/–to or –since, the server searches only the last hour; use –since (for example –since 7d) to look further back. This API is experimental and disabled by default on both self-hosted Prometheus (requires –enable-feature=search-api) and self-hosted Mimir (requires -querier.experimental-search-api-enabled). See also the sibling metric-name search and label-value search commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources prometheus search-label-names [TERM...] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Fuzzy search label names (use datasource UID, not name) gcx datasources prometheus search-label-names job -d UID # Show label names available on a given metric gcx datasources prometheus search-label-names -d UID --metric http_requests_total # Show label names on series matching a selector gcx datasources prometheus search-label-names -d UID --match '{job="api"}' # Search for label names on a given metric gcx datasources prometheus search-label-names namespace -d UID --metric http_requests_total # Search for label names across a range of metrics gcx datasources prometheus search-label-names namespace -d UID --metric-regex '.*kube.*' # Search label names seen in the last 7 days (default: the last hour) gcx datasources prometheus search-label-names job -d UID --since 7d # Output as JSON gcx datasources prometheus search-label-names job -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --case-sensitive Case-sensitive search term matching (case-insensitive by default) -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --fuzz-alg string Fuzzy match algorithm: jarowinkler or subsequence (default "jarowinkler") --fuzz-threshold int Minimum fuzzy match score as a percentage, 0-100; scores are reported from 0 to 1. With jarowinkler the threshold applies only to fuzzy matches: substring matches are always kept, and 0 turns fuzzy matching off (default 70) -h, --help help for search-label-names --include-score Include each result's relevance score (0 to 1; higher is a closer match) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum results to return (0: unlimited on Mimir, subject to server-side caps; Prometheus requires a positive value) (default 50) --match stringArray PromQL series selector(s) restricting candidates; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) --metric string Only results from series of this metric name; mutually exclusive with --metric-regex --metric-regex string Only results from series whose metric name matches this regex. Used exactly as given. To match all metric names which contain "kube" use ".*kube.*". Mutually exclusive with --metric. -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --sort-by string Sort by: score (requires a search term) or alpha (default "score") --sort-dir string Sort direction for --sort-by alpha: asc (default) or dsc --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources prometheus`](#gcx-datasources-prometheus-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources prometheus search-label-values` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Search the values of a single label from a Prometheus/Mimir datasource. LABEL is always required; TERM (multiple values combine as OR), –metric, –metric-regex and –match are all optional and may be combined or omitted — LABEL alone lists that label’s values. sort\_by=score (the default) requires a search term — omitting TERM falls back to sort\_by=alpha, and an explicit –sort-by=score without TERM is rejected. –metric-regex is used exactly as given — PromQL anchors =~ at ^…$, so “kube” matches only a metric literally named “kube”, not one containing it. Write “.*kube.*” for a contains search. Without –from/–to or –since, the server searches only the last hour; use –since (for example –since 7d) to look further back. This API is experimental and disabled by default on both self-hosted Prometheus (requires –enable-feature=search-api) and self-hosted Mimir (requires -querier.experimental-search-api-enabled). See also the sibling metric-name search and label-name search commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources prometheus search-label-values LABEL [TERM...] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List values of the "job" label (use datasource UID, not name) gcx datasources prometheus search-label-values job -d UID # Fuzzy search values of the "job" label gcx datasources prometheus search-label-values job pro -d UID # List "job" label values present on a specific metric gcx datasources prometheus search-label-values job -d UID --metric http_requests_total # List "job" label values present on a range of metrics gcx datasources prometheus search-label-values job -d UID --metric-regex '.*kube.*' # List "job" label values seen in the last 7 days (default: the last hour) gcx datasources prometheus search-label-values job -d UID --since 7d # Output as JSON gcx datasources prometheus search-label-values job pro -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --case-sensitive Case-sensitive search term matching (case-insensitive by default) -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --fuzz-alg string Fuzzy match algorithm: jarowinkler or subsequence (default "jarowinkler") --fuzz-threshold int Minimum fuzzy match score as a percentage, 0-100; scores are reported from 0 to 1. With jarowinkler the threshold applies only to fuzzy matches: substring matches are always kept, and 0 turns fuzzy matching off (default 70) -h, --help help for search-label-values --include-score Include each result's relevance score (0 to 1; higher is a closer match) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum results to return (0: unlimited on Mimir, subject to server-side caps; Prometheus requires a positive value) (default 50) --match stringArray PromQL series selector(s) restricting candidates; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) --metric string Only results from series of this metric name; mutually exclusive with --metric-regex --metric-regex string Only results from series whose metric name matches this regex. Used exactly as given. To match all metric names which contain "kube" use ".*kube.*". Mutually exclusive with --metric. -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --sort-by string Sort by: score (requires a search term) or alpha (default "score") --sort-dir string Sort direction for --sort-by alpha: asc (default) or dsc --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources prometheus`](#gcx-datasources-prometheus-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources prometheus search-metric-names` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Search metric names from a Prometheus/Mimir datasource. At least one TERM is required. This API allows for metric names to be discovered via a configurable fuzzy search. Multiple TERM values combine as OR. Search terms can be augmented with matchers for additional filtering of considered series. Without –from/–to or –since, the server searches only the last hour; use –since (for example –since 7d) to look further back. This API is experimental and disabled by default on both self-hosted Prometheus (requires –enable-feature=search-api) and self-hosted Mimir (requires -querier.experimental-search-api-enabled). See also the sibling label-name search and label-value search commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources prometheus search-metric-names TERM... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Fuzzy search metric names (use datasource UID, not name) gcx datasources prometheus search-metric-names http -d UID # Search metric names seen in the last 7 days (default: the last hour) gcx datasources prometheus search-metric-names http -d UID --since 7d # Refine fuzzy search algorithm gcx datasources prometheus search-metric-names http -d UID --fuzz-alg=subsequence --fuzz-threshold=85 # Limit result sets and control ordering gcx datasources prometheus search-metric-names http -d UID --limit=10 --sort-by=alpha # Include relevance score and metric metadata gcx datasources prometheus search-metric-names http -d UID --include-score --include-metadata # Output as JSON gcx datasources prometheus search-metric-names http -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --case-sensitive Case-sensitive search term matching (case-insensitive by default) -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --fuzz-alg string Fuzzy match algorithm: jarowinkler or subsequence (default "jarowinkler") --fuzz-threshold int Minimum fuzzy match score as a percentage, 0-100; scores are reported from 0 to 1. With jarowinkler the threshold applies only to fuzzy matches: substring matches are always kept, and 0 turns fuzzy matching off (default 70) -h, --help help for search-metric-names --include-metadata Include each result's metric type, help text, and unit (when available) --include-score Include each result's relevance score (0 to 1; higher is a closer match) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum results to return (0: unlimited on Mimir, subject to server-side caps; Prometheus requires a positive value) (default 50) --match stringArray PromQL series selector(s) restricting candidates; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --sort-by string Sort by: score (requires a search term) or alpha (default "score") --sort-dir string Sort direction for --sort-by alpha: asc (default) or dsc --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources prometheus`](#gcx-datasources-prometheus-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope` Query Pyroscope datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for pyroscope ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope data-range` Show the range of profiling data a Pyroscope datasource holds: whether any data was ever ingested, and the oldest and newest profile times. The range covers everything behind the datasource (the whole tenant), not any particular service or label selector. Use this to disambiguate empty query results: if no data was ever ingested, fix ingestion before adjusting selectors; otherwise the oldest/newest bounds show the currently queryable window. Note that data-ingested is a lifetime flag: it stays true even after all data has aged out of the retention period (31 days by default, tenant-configurable), in which case the bounds render as ‘-’ (0 in JSON). Older backends may also report an unknown oldest bound the same way. If gcx auto-discovers the datasource from your Grafana Cloud stack, the discovered datasource UID may be saved to your gcx configuration for future commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pyroscope data-range [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Check whether the datasource holds profiling data, and for what range gcx datasources pyroscope data-range -d UID # Output as JSON (times are milliseconds since epoch) gcx datasources pyroscope data-range -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) -h, --help help for data-range --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope exemplars` Query profile or span exemplars from a Pyroscope datasource. Exemplars link profile data to concrete samples or trace spans, enabling a pivot from “which service was slow” to “which exact profile” (profile exemplars) or “which trace span” (span exemplars). **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for exemplars ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope exemplars profile` List individual profile exemplars by calling SelectSeries with EXEMPLAR\_TYPE\_INDIVIDUAL. Each row is a concrete profile sample identified by Profile ID. When profiles are span-aware (e.g. via otelpyroscope), a Span ID column is included linking to the associated trace span. EXPR is the label selector (e.g. ‘{service\_name=“frontend”}’). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pyroscope exemplars profile [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Top profile exemplars in the last hour gcx datasources pyroscope exemplars profile '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # JSON output gcx datasources pyroscope exemplars profile '{}' --since 30m -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --expr string Label selector (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for profile --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-label-columns int Max label columns in table output (0 hides label columns) (default 3) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --profile-type string Profile type ID (default "process_cpu:cpu:nanoseconds:cpu:nanoseconds") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') --top-n int Maximum number of exemplars to return (default 100) ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope exemplars span` List span exemplars by calling SelectHeatmap with HEATMAP\_QUERY\_TYPE\_SPAN. Each row is a span-linked profile sample identified by Span ID. When supplied by the server, Trace ID is also included for direct correlation with Tempo. Requires span-aware instrumentation upstream (e.g. otelpyroscope); without it the query returns an empty list. EXPR is the label selector (e.g. ‘{service\_name=“frontend”}’). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pyroscope exemplars span [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Top span exemplars in the last hour gcx datasources pyroscope exemplars span '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # JSON output, more label context gcx datasources pyroscope exemplars span '{}' --since 30m --max-label-columns 5 -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --expr string Label selector (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for span --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-label-columns int Max label columns in table output (0 hides label columns) (default 3) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --profile-type string Profile type ID (default "process_cpu:cpu:nanoseconds:cpu:nanoseconds") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') --top-n int Maximum number of exemplars to return (default 100) ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope labels` List all labels or get values for a specific label from a Pyroscope datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pyroscope labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all labels (use datasource UID, not name) gcx datasources pyroscope labels -d UID # Get values for a specific label gcx datasources pyroscope labels -d UID --label service_name # Search a wider window than the default last hour gcx datasources pyroscope labels -d UID --since 24h # Output as JSON gcx datasources pyroscope labels -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label string Get values for this label (omit to list all labels) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope list-profile-types` List available profile types from a Pyroscope datasource. If gcx auto-discovers the datasource from your Grafana Cloud stack, the discovered datasource UID may be saved to your gcx configuration for future commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pyroscope list-profile-types [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List profile types (use datasource UID, not name) gcx datasources pyroscope list-profile-types -d UID # Search a wider window than the default last hour gcx datasources pyroscope list-profile-types -d UID --since 24h # Output as JSON gcx datasources pyroscope list-profile-types -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for list-profile-types --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope metrics` Query profile time-series data via SelectSeries from a Pyroscope datasource. Shows how a profile metric (e.g., CPU, memory) changes over time. Useful for identifying performance regressions and trends before diving into flamegraphs. Use –top to aggregate the time range into a ranked leaderboard of the heaviest consumers (equivalent to profilecli query top). Without –top, returns raw time-series data points for trend analysis. EXPR is the label selector (e.g., ‘{service\_name=“frontend”}’). Datasource is resolved from -d flag or datasources.pyroscope in your context. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pyroscope metrics [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Top services by CPU usage (ranked leaderboard) gcx datasources pyroscope metrics '{}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds \ --since 1h --top # Top 20 services by memory, grouped by namespace gcx datasources pyroscope metrics '{}' \ --profile-type memory:inuse_space:bytes:space:bytes \ --since 1h --top --group-by namespace --limit 20 # CPU usage over the last hour with 1-minute resolution gcx datasources pyroscope metrics -d pyro-001 '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds \ --since 1h --step 1m # Line chart output gcx datasources pyroscope metrics '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds \ --since 1h --step 1m -o graph ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --aggregation string Aggregation type: 'sum' or 'average' -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --group-by strings Group series by label (repeatable, defaults to service_name) -h, --help help for metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of series to return (default 10) -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --profile-type string Profile type ID (e.g., 'process_cpu:cpu:nanoseconds:cpu:nanoseconds') (required) --since string Duration before --to (or now if omitted); mutually exclusive with --from --step string Query step (e.g., '15s', '1m'); defaults to the Pyroscope datasource minStep (or 15s) when omitted --to string End time (RFC3339, Unix timestamp, or relative like 'now') --top Aggregate into a ranked leaderboard (equivalent to profilecli query top) ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope query` Execute a profiling query against a Pyroscope datasource. EXPR is the label selector (e.g., ‘{service\_name=“frontend”}’). Datasource is resolved from -d flag or datasources.pyroscope in your context. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pyroscope query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Profile query with explicit datasource UID gcx datasources pyroscope query -d UID '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # Using configured default datasource gcx datasources pyroscope query '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # Output as JSON gcx datasources pyroscope query -d UID '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds -o json # Drill into one or more specific profiles found via exemplars # (--profile-id is repeatable; pass it once per UUID) gcx datasources pyroscope query '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h \ --profile-id 550e8400-e29b-41d4-a716-446655440000 \ --profile-id 7c9e6679-7425-40de-944b-e07fc1f90ae7 # Restrict the query to one or more trace spans gcx datasources pyroscope query '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h \ --span-id 00f067aa0ba902b7 # Restrict the query to samples from one or more traces gcx datasources pyroscope query '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h \ --trace-id 4bf92f3577b34da6a3ce929d0e0e4736 # Restrict the flamegraph to stacks rooted at a specific call site # (--stacktrace-selector is repeatable; pass it once per frame, root first) gcx datasources pyroscope query '{service_name="my-go-service"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h \ --stacktrace-selector 'github.com/prometheus/client_golang/prometheus.(*Registry).Gather.func1' # Download as pprof binary (for use with go tool pprof) gcx datasources pyroscope query -d UID '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds -o pprof # Download as pprof binary to a specific path gcx datasources pyroscope query -d UID '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds -o pprof --pprof-path ./cpu.pb.gz # Caller-callee call graph as Graphviz DOT text (function names, file:line, # self/cumulative values) — the most readable format for LLM analysis. # Requires a pure-v2 backend (-architecture.storage=v2); other backends # fall back to the table. Dotted edges mean intermediate frames were # elided by the 100-node default — raise --max-nodes for fuller chains. gcx datasources pyroscope query -d UID '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds -o dot --max-nodes 250 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-nodes int Maximum nodes in the result (defaults: pprof 0/unlimited, dot 100-node call graph rendered server-side, 50000 for all other formats) -o, --output string Output format. One of: agents, dot, graph, json, pprof, table, wide, yaml (default "table") --pprof-overwrite Overwrite the output file if it already exists (only with -o pprof) --pprof-path string Destination path for pprof binary output (only with -o pprof; default: profile-YYYY-MM-DD-HHMMSS.pb.gz) --profile-id strings Drill down to specific profile UUIDs from exemplar queries (repeatable) --profile-type string Profile type ID (e.g., 'process_cpu:cpu:nanoseconds:cpu:nanoseconds'); use 'gcx profiles list-profile-types' to list available (required) --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --span-id strings Only query profiles with these 16-character hex span IDs (repeatable; unavailable with -o pprof and -o dot) --stacktrace-selector strings Only query locations with these function names, starting from the root (repeatable) --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') --trace-id strings Only query samples with these 32-character hex trace IDs (repeatable) ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources pyroscope series` List unique profile label sets from a Pyroscope datasource. The command uses Pyroscope’s Series endpoint and does not require a profile type. SELECTOR is optional; use –match for repeatable selectors. Multiple selectors are combined as a union. By default, the response includes every label. Use –label-name to request only the labels needed for discovery. This reduces the response size and can significantly speed up queries with high-cardinality labels. For example, use –label-name service\_name –label-name namespace to discover services and namespaces without fetching pod, instance, or custom labels. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources pyroscope series [SELECTOR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List service and workload combinations from the last hour gcx datasources pyroscope series -d UID --since 1h # Faster discovery: request only the labels needed gcx datasources pyroscope series -d UID '{service_name="checkout"}' \ --label-name service_name --label-name namespace --label-name pod --since 7d # Use multiple selectors and JSON output gcx datasources pyroscope series -d UID \ --match '{namespace="payments"}' --match '{namespace="checkout"}' \ --since 24h -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for series --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --label-name strings Label name to return (repeatable; limit labels to reduce response size and speed up discovery) --match stringArray Profile label selector (repeatable; selectors are combined as a union) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources pyroscope`](#gcx-datasources-pyroscope-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources query` Execute a query against any datasource, automatically detecting the datasource type. DATASOURCE\_UID is always required (no default resolution for generic). EXPR is the query expression appropriate for the datasource type. The datasource type is detected via the Grafana API and the appropriate query client is used automatically. This is the escape hatch for datasource types that do not have a dedicated subcommand. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources query DATASOURCE_UID [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Auto-detect and query any supported datasource gcx datasources query ds-001 'up{job="grafana"}' --from now-1h --to now # Loki via auto-detect (with limit) gcx datasources query loki-001 '{job="varlogs"}' --from now-1h --to now --limit 200 # Pyroscope via auto-detect gcx datasources query pyro-001 '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --from now-1h --to now ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum log lines for loki, or max rows for pinot (0 means no limit). Pinot uses 100 when --limit is omitted; stderr notes when PinotQL is adjusted (default 50) --max-nodes int Maximum nodes in flame graph (pyroscope only) (default 1024) -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --profile-type string Profile type ID for pyroscope queries (e.g., 'process_cpu:cpu:nanoseconds:cpu:nanoseconds') --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --table string StarTree table name for pinot queries when the SQL has no extractable FROM --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources schemas` Inspect the configuration schema of a datasource plugin type, to author manifests correctly. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for schemas ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources schemas get` Get the configuration schema for a datasource plugin type. The schema lists the configuration fields available for a plugin, derived from the server’s OpenAPI document. Use it to author create/update manifests. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources schemas get [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Show a plugin's configuration schema gcx datasources schemas get --type grafana-sentry-datasource # As JSON gcx datasources schemas get --type grafana-sentry-datasource -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --kind string Schema kind: config (query is not yet supported) (default "config") -o, --output string Output format. One of: agents, json, yaml (default "yaml") -t, --type string Datasource plugin id (e.g. grafana-sentry-datasource) ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources schemas list` List the datasource plugin types installed on the Grafana instance. The TYPE column is the plugin id — pass it to ‘schemas get –type’, and use it as spec.type when authoring a datasource manifest. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources schemas list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List available datasource plugin types gcx datasources schemas list # As JSON gcx datasources schemas list -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources tempo` Query Tempo datasources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for tempo ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources tempo baseline` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Find unranked candidates when you have a seed trace (TRACE\_ID) but need a useful comparison; if you already have both trace IDs, use ‘gcx traces diff’ directly. Retrieval fetches the seed, matches its root service/operation, requires root status != error (including unset), retains downstream errors, and pins up to three busiest downstream services; these heuristics do not prove health or comparable work. Apply verified environment, tenant, or operation constraints with –filter from the first request, then fetch a small batch of plausible candidates with ‘gcx traces get –llm’ when their summaries lack enough context. Use candidate bodies and exploratory diffs to accept or reject controls for the actual symptom, rather than requiring exact workload filters before the first diff or treating the first result as healthy. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources tempo baseline TRACE_ID [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Find a small shortlist; COHORT is an already-verified TraceQL spanset gcx traces baseline --context prod -d UID --filter "$COHORT" --limit 5 # With no additional known scope, use the seed-derived defaults gcx traces baseline --context prod -d UID --limit 5 # Inspect selected candidates; repeat for a small batch, not every result gcx traces get --context prod -d UID --llm -o agents # Assess a candidate with an exploratory diff (seed minus candidate) gcx traces diff --context prod -d UID # Set the candidate window; this does not bound the seed trace lookup gcx traces baseline --context prod -d UID --filter "$COHORT" --limit 5 \ --from 2026-01-15T08:00:00Z --to 2026-01-15T09:00:00Z ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --filter stringArray Raw TraceQL spanset expression to constrain candidates (repeatable; ANDed server-side with the generated query) --from string Absolute start time override (RFC3339, Unix timestamp, or relative like 'now-1h'); requires --to -h, --help help for baseline --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of candidates to return; must be at least 1 (default 20) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --to string Absolute end time override (RFC3339, Unix timestamp, or relative like 'now'); requires --from --window string Search window padding applied before and after the seed trace's time range, so candidates from before or after the seed are eligible (e.g., 30m, 6h, 7d). Ignored when --from/--to are set (default "30m") ``` Inherits `--config` from [`gcx datasources tempo`](#gcx-datasources-tempo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources tempo diff` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Compare two known trace IDs using the Grafana Cloud-only trace-diff API; use ‘gcx traces baseline’ first only when you need candidate IDs. TRACE\_A is the prospective baseline and TRACE\_B is the comparison, with deltas B - A: positive duration means B is slower and negative means faster, not automatically a regression or improvement (a request can fail early). Use candidate bodies and exploratory diffs to assess comparability, rejecting obvious context mismatches first and interpreting timing at the affected request boundary; a diff localizes execution changes but does not establish their cause. Keep the same context/datasource and make –from/–to (or –since) cover both executions; without time bounds the lookup uses the full lookback, and if the endpoint is unavailable, use ‘gcx traces get –llm’ to compare both bodies manually instead. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources tempo diff TRACE_A TRACE_B [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Compare an already-known pair directly; baseline search is not required gcx traces diff --context prod -d UID # Inspect a plausible candidate before using a diff to assess it gcx traces get --context prod -d UID --llm -o agents # Assess selected candidates against the seed; repeat only as useful gcx traces diff --context prod -d UID # Bound BOTH trace lookups, including an older candidate, and allow spilling gcx traces diff --context prod -d UID \ --from 2026-01-15T08:00:00Z --to 2026-01-15T10:00:00Z -o agents ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for diff --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources tempo`](#gcx-datasources-tempo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources tempo get` Retrieve a single trace by its trace ID from a Tempo datasource. TRACE\_ID is the hex-encoded trace identifier to retrieve. Datasource is resolved from -d flag or datasources.tempo in your context. Pass –since or –from/–to (e.g. the search’s time range) to make the lookup much faster. Omit them when the time range is unknown; a range that misses the trace returns not found. Use –share-link to print a Grafana Explore URL for the trace, or –open to open it in your browser after retrieval succeeds. Share links require an explicit time range via –since or –from/–to. Experimental: –llm requests the trace in a new LLM-friendly JSON format by sending the “Accept: application/vnd.grafana.llm” header. Datasources that do not support this format return the standard response. Experimental: for large traces, –filter narrows the response to spans matching a TraceQL spanset filter (V2 only). –keep-hierarchy, –match-depth, and –ancestor-depth shape how much context around each match is kept, and are ignored without –filter. Experimental: –prune collapses repeated sibling spans (for example, a fan-out of identical DB calls) into a single aggregated span. Off unless set. –prune-group-by, –prune-min-spans, and –prune-max-parent-depth tune the pruning behavior and apply only when –prune enables pruning. If the trace is too large for -o agents, the response is spilled to a file with a hint to read it directly or re-run narrower (e.g. with –filter or –prune). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources tempo get TRACE_ID [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Get LLM-friendly output for agent analysis gcx datasources tempo get abc123def456 --llm -o json # Get LLM-friendly output with explicit datasource UID gcx datasources tempo get -d tempo-001 abc123def456 --llm -o json # Print a Grafana Explore share link for the trace gcx datasources tempo get abc123def456 --share-link # Get a human-readable trace table gcx datasources tempo get abc123def456 # Get LLM-friendly output within a time range gcx datasources tempo get abc123def456 --since 1h --llm -o json # Narrow a large trace to error spans and their ancestor path gcx datasources tempo get abc123def456 --filter '{ status = error }' --keep-hierarchy # Collapse repeated sibling spans to shrink a huge trace before analysis gcx datasources tempo get abc123def456 --prune --llm -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --ancestor-depth int [experimental] Levels of ancestors to keep above each matched span: -1 = all (default), 0 = none, n = n levels (ignored without --filter or --keep-hierarchy) (default -1) -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --filter string [experimental] TraceQL spanset filter; only matching spans are returned (V2 only) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --keep-hierarchy [experimental] Include each matched span's ancestor path to the root (ignored without --filter) --llm [experimental] Request LLM-friendly trace format by sending the 'Accept: application/vnd.grafana.llm' header. Falls back to default JSON --match-depth int [experimental] Levels of descendants to keep below each matched span: -1 = all, 0 = matched spans only, n = n levels (ignored without --filter) --open Open the retrieved trace in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --prune [experimental] Collapse repeated sibling spans (e.g. a fan-out of identical DB calls) into a single aggregated span to shrink large traces. Off unless set --prune-group-by string [experimental] Comma-separated attribute glob patterns siblings must match to be grouped for pruning, e.g. 'db.*,http.method'. Applies only when --prune enables pruning --prune-max-parent-depth int [experimental] Ancestor levels above pruned leaves that may also be pruned; Tempo defaults to 1. Applies only when --prune enables pruning --prune-min-spans int [experimental] Minimum sibling span count required before a group is pruned; Tempo defaults to 5. Applies only when --prune enables pruning --share-link Print the Grafana Explore URL for the retrieved trace to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources tempo`](#gcx-datasources-tempo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources tempo labels` List all trace labels or get values for a specific label from a Tempo datasource. When -l/–label is provided, returns values for that label. When -l is omitted, returns all label names. Datasource is resolved from -d flag or datasources.tempo in your context. Experimental: –llm requests label values in a new LLM-friendly JSON format by sending the “Accept: application/vnd.grafana.llm” header. Datasources that do not support this format return the standard response. **Aliases:** `tags` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources tempo labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all labels gcx datasources tempo labels -d UID # Get values for a specific label gcx datasources tempo labels -d UID -l service.name # Get LLM-friendly values for a specific label gcx datasources tempo labels -d UID -l service.name --llm -o json # Using the tags alias gcx datasources tempo tags -d UID -l service.name # Filter by scope gcx datasources tempo labels -d UID -l service.name --scope span # Filter with a TraceQL query gcx datasources tempo labels -d UID -q '{ span.http.status_code >= 500 }' # Output as JSON gcx datasources tempo labels -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label string Get values for this label (omit to list all labels) --llm [experimental] Request LLM-friendly label values format by sending the 'Accept: application/vnd.grafana.llm' header. Falls back to default JSON (requires --label) -o, --output string Output format. One of: agents, json, table, yaml (default "table") -q, --query string TraceQL query to filter labels --scope string Tag scope filter (resource, span, event, link, instrumentation) ``` Inherits `--config` from [`gcx datasources tempo`](#gcx-datasources-tempo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources tempo metrics` Execute a TraceQL metrics query against a Tempo datasource. TRACEQL is the TraceQL metrics expression to evaluate. Datasource is resolved from -d flag or datasources.tempo in your context. Instant vs range is deduced from time flags: no time flags = instant query, –since or –from/–to = range query. Use –instant to force an instant query even when a time range is provided. If no time flags are set, gcx queries the last hour by default. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources tempo metrics [TRACEQL] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Instant query over the last hour (default, no time flags) gcx datasources tempo metrics '{ } | rate()' # Range query with relative window gcx datasources tempo metrics -d tempo-001 '{ } | rate()' --since 1h # Print a Grafana Explore share link for the query gcx datasources tempo metrics '{ } | rate()' --share-link # Instant query with explicit time range gcx datasources tempo metrics '{ } | rate()' --instant --since 1h # Range query with explicit time range and step gcx datasources tempo metrics '{ } | rate()' --from now-1h --to now --step 30s # Output as JSON gcx datasources tempo metrics -d tempo-001 '{ } | rate()' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for metrics --instant Run an instant query over the selected time range instead of a range query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources tempo`](#gcx-datasources-tempo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources tempo query` Search for traces using a TraceQL query against a Tempo datasource. TRACEQL is the TraceQL expression to evaluate. Datasource is resolved from -d flag or datasources.tempo in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. Share links require an explicit time range via –since or –from/–to. **Aliases:** `search` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources tempo query [TRACEQL] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Search traces using configured default datasource gcx datasources tempo query '{ span.http.status_code >= 500 }' # Search with explicit datasource UID and time range gcx datasources tempo query -d UID '{ span.http.status_code >= 500 }' --since 1h # Print a Grafana Explore share link for the query gcx datasources tempo query '{ span.http.status_code >= 500 }' --share-link # With custom limit gcx datasources tempo query -d UID '{ span.http.status_code >= 500 }' --since 1h --limit 50 # Output as JSON gcx datasources tempo query -d UID '{ span.http.status_code >= 500 }' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of traces to return (0 means no limit) (default 20) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx datasources tempo`](#gcx-datasources-tempo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx datasources update` Update an existing datasource instance from a declarative manifest file. This is a full replace: fields omitted from the manifest are reset. The current resourceVersion is fetched and applied automatically (optimistic concurrency). Secret values are updated via the top-level secure block. update does not prompt; use –dry-run to preview the change. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx datasources update UID [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Update a datasource from a YAML manifest gcx datasources update my-ds-uid -f sentry.yaml # Preview the change gcx datasources update my-ds-uid -f sentry.yaml --dry-run ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use --dry-run Preview the change without applying it -f, --filename string File containing the datasource manifest (use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") --secrets-file string File containing secret values to merge into the secure block ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dbo11y` Inspect Grafana Database Observability instances and query performance **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for dbo11y ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dbo11y instances` Inspect Database Observability instances discovered from telemetry **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for instances ``` Inherits `--config` from [`gcx dbo11y`](#gcx-dbo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dbo11y instances get` Show exporter health and a query-performance snapshot for one database instance. The argument is the instance’s service\_name (the identifier “gcx dbo11y instances list” reports as NAME). What’s available depends on the instance’s engine (from “gcx dbo11y instances list”): - Health (up/down) is engine-agnostic, from the standard Prometheus scrape target gauge. - Postgres additionally reports exporter self-scrape health, per-state connection counts, active wait events, and the longest running transaction, all from postgres\_exporter’s pg\_stat\_activity collector. - MySQL reports a single current-connections count (mysql\_global\_status\_threads\_connected); wait events and exporter self-scrape health have no confirmed live metric for MySQL and are omitted rather than guessed. - Top queries (both engines) are ranked by time share (seconds of database time spent per second) over –since (default 5m): pg\_stat\_statements for Postgres, mysqld\_exporter’s Performance Schema eventsstatements collector for MySQL. –filter only scopes the connections/query-performance queries — health and inventory metadata don’t carry a datname/schema label and are unaffected. When no telemetry is found for the instance, this command checks whether Database Observability has been activated for the stack and, if not, exits non-zero with a hint to activate it in Grafana Cloud instead of a generic “no telemetry” message. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dbo11y instances get [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Health, connections, and top queries for one instance (Postgres or MySQL) gcx dbo11y instances get quickpizza-db # Widen the query window and show more top queries gcx dbo11y instances get quickpizza-db --since 1h --top 20 # Scope connections/queries to a single database on a multi-database instance gcx dbo11y instances get quickpizza-db --filter datname=payments # JSON for scripting gcx dbo11y instances get quickpizza-db -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Prometheus datasource UID (defaults to datasources.prometheus in config or auto-discovery) --filter stringArray Scope the connections/query-performance queries to series matching a label matcher, e.g. --filter datname=payments for Postgres or --filter schema=payments for MySQL (repeatable). Does not affect health/inventory metrics, which don't carry that label -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --since string Rate window applied to pg_stat_statements (e.g. 1m, 5m, 1h) — PromQL duration syntax (default "5m") --top int Limit the number of top queries returned, ranked by time share (0 = unlimited) (default 10) ``` Inherits `--config` from [`gcx dbo11y`](#gcx-dbo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dbo11y instances list` List the database instances Grafana Cloud Database Observability has discovered. Discovery uses the database\_observability\_connection\_info inventory metric emitted by the database\_observability.postgres Alloy component (job “integrations/db-o11y”): one row per monitored database instance, with engine and cloud-provider metadata. Related: “gcx dbo11y instances get ” drills into one instance’s health, connections, wait events, and top queries by time share. When no instances are found, this command checks whether Database Observability has been activated for the stack and, if not, exits non-zero with a hint to activate it in Grafana Cloud instead of a generic empty result. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dbo11y instances list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all database instances in the current stack gcx dbo11y instances list # Filter to Postgres instances gcx dbo11y instances list --filter engine=postgres # Pin a datasource and output JSON gcx dbo11y instances list -d grafanacloud-prom -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Prometheus datasource UID (defaults to datasources.prometheus in config or auto-discovery) --filter stringArray Restrict to instances matching a label matcher, e.g. --filter engine=postgres (repeatable) -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Limit the number of instances returned (0 = unlimited) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx dbo11y`](#gcx-dbo11y-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev` Tools for managing Grafana resources as code: scaffold new projects, import existing resources from Grafana, generate typed Go stubs for new resources, lint resources, and serve resources locally. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for dev ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev generate` Generate typed Go code stubs using grafana-foundation-sdk builder types. The resource type is inferred from the immediate parent directory name: dashboards/ → dashboard alerts/ → alertrule alertrules/ → alertrule The resource name is inferred from the filename (without .go extension). Use –type to override type inference when the directory name does not match. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dev generate [FILE_PATH]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Generate a dashboard stub gcx dev generate dashboards/my-service-overview.go # Generate an alert rule stub gcx dev generate alerts/high-cpu-usage.go # Generate multiple stubs at once gcx dev generate dashboards/a.go dashboards/b.go alerts/c.go # Override type inference with --type gcx dev generate internal/monitoring/cpu-alert.go --type alertrule ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for generate --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") -t, --type string Resource type to generate (dashboard, alertrule). Overrides directory-based inference. ``` Inherits `--config`, `--context` from [`gcx dev`](#gcx-dev-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev import` Import resources from a Grafana instance and convert them into Go files using the grafana-foundation-sdk builder pattern. Each imported resource is written as a function returning \*resource.ManifestBuilder. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dev import [RESOURCE_SELECTOR]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Import all dashboards into the default path (imported/): gcx dev import dashboards # Import a specific dashboard by name: gcx dev import dashboards/my-dashboard # Import multiple resource types: gcx dev import dashboards folders # Import into a custom directory: gcx dev import dashboards --path src/grafana ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use -h, --help help for import --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") -p, --path string Import path. (default "imported") ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev lint` Lint Grafana resources. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for lint ``` Inherits `--config`, `--context` from [`gcx dev`](#gcx-dev-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev lint list-rules` List all built-in and custom linter rules with their name, description, resource type, and category. Use –rules to include custom rules from a directory. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dev lint list-rules [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List built-in rules: gcx dev lint list-rules # List built-in and custom rules: gcx dev lint list-rules -r ./custom-rules ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-rules --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") -r, --rules stringArray Path to custom rules. ``` Inherits `--config`, `--context` from [`gcx dev`](#gcx-dev-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev lint new` Scaffold a new Rego-based linter rule with a starter template, test fixture, and expected output file. Creates files in the current directory or the path specified by –output. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dev lint new RESOURCE_TYPE NAME [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Creates a new dashboard linter rule in the current directory: gcx dev lint new dashboard test-linter # Creates a new dashboard linter rule in another directory: gcx dev lint new dashboard test-linter -o custom-rules ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -c, --category string Rule category (default "idiomatic") -h, --help help for new -o, --output string Output directory ``` Inherits `--config`, `--context` from [`gcx dev`](#gcx-dev-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev lint run` Lint Grafana resources against Rego-based rules. Checks dashboards and other resource types for best practices, naming conventions, and configuration issues. Use –rules to load custom rules alongside built-in ones. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dev lint run PATH... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Lint Grafana resources using builtin rules: gcx dev lint run ./resources # Lint specific files: gcx dev lint run ./resources/file.json ./resources/other.yaml # Display compact results: gcx dev lint run ./resources -o compact # Use custom rules: gcx dev lint run --rules ./custom-rules ./resources # Disable all rules for a resource type: gcx dev lint run --disable-resource dashboard ./resources # Disable all rules in a category: gcx dev lint run --disable-category idiomatic ./resources # Disable specific rules: gcx dev lint run --disable uneditable-dashboard --disable panel-title-description ./resources # Enable rules for specific resource types: gcx dev lint run --disable-all --enable-resource dashboard ./resources # Enable only some categories: gcx dev lint run --disable-all --enable-category idiomatic ./resources # Enable only specific rules: gcx dev lint run --disable-all --enable uneditable-dashboard ./resources ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --debug Enable debug mode --disable stringArray Disable a rule --disable-all Disable all rules --disable-category stringArray Disable all rules in a category --disable-resource stringArray Disable all rules for a resource type --enable stringArray Enable a rule --enable-all Enable all rules --enable-category stringArray Enable all rules in a category --enable-resource stringArray Enable all rules for a resource type -h, --help help for run --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-concurrent int Maximum number of concurrent operations (default 10) -o, --output string Output format. One of: agents, compact, json, pretty, yaml (default "pretty") -r, --rules stringArray Path to custom rules ``` Inherits `--config`, `--context` from [`gcx dev`](#gcx-dev-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev lint test` Run test suites for linter rules. Each rule directory should contain test fixtures and expected output files. Reports pass/fail for each test case. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dev lint test PATH... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Run all tests in a directory: gcx dev lint test ./internal/linter/bundle/gcx/ ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --bundle Enable bundle mode --coverage Report coverage --debug Enable debug mode -h, --help help for test --ignore strings File and directory names to ignore during loading (e.g., '.*' excludes hidden files) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, pretty, yaml (default "pretty") --run string Run only test cases matching the regular expression --timeout duration Set test timeout ``` Inherits `--config`, `--context` from [`gcx dev`](#gcx-dev-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev scaffold` Scaffold a new Go project pre-configured for managing Grafana resources as code. Generates a module with example dashboards, a deploy workflow, and gcx configuration. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dev scaffold [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Interactive scaffolding (prompts for project name and Go module path): gcx dev scaffold # Non-interactive with flags: gcx dev scaffold --project my-dashboards --go-module-path github.com/example/my-dashboards ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --go-module-path string Go module path. -h, --help help for scaffold -p, --project string Project name. ``` Inherits `--config`, `--context` from [`gcx dev`](#gcx-dev-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx dev serve` Serve Grafana resources locally. The server started by this command makes it easy to explore and review resources locally. While resources are loaded from disk, the server will use the Grafana instance described in the current context to access some data (example: to run queries when previewing dashboards). The local proxy supports token, Basic, and mTLS contexts. OAuth contexts fail before the server starts because this long-running process cannot yet persist rotated refresh-token generations safely; use a service-account token for local preview. Note on NFS/SMB and watch mode: fsnotify requires support from underlying OS to work. The current NFS and SMB protocols does not provide network level support for file notifications. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx dev serve [RESOURCE_DIR]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Serve resources from a directory: gcx dev serve ./resources # Serve resources from a directory but don't watch for changes: gcx dev serve ./resources --no-watch # Serve resources from a script that outputs a YAML resource and watch for changes: # Note: the Grafana Foundation SDK can be used to generate dashboards (https://grafana.github.io/grafana-foundation-sdk/) gcx dev serve --script 'go run dashboard-generator/*.go' --watch ./dashboard-generator --script-format yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --address string Address to bind (default loopback; use 0.0.0.0 to expose on all interfaces) (default "127.0.0.1") -h, --help help for serve --max-concurrent int Maximum number of concurrent operations (default 10) --no-watch Do not watch for changes --port int Port on which the server will listen (default 8080) -S, --script string Script to execute to generate a resource -f, --script-format string Format of the data returned by the script (default "json") -w, --watch stringArray Paths to watch for changes ``` Inherits `--config`, `--context` from [`gcx dev`](#gcx-dev-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet` Manage Grafana Fleet Management pipelines and collectors **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for fleet ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet collectors` Manage Fleet Management collectors. **Aliases:** `collector` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for collectors ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet collectors create` Create a collector from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet collectors create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the collector manifest (use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet collectors delete` Delete a collector. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet collectors delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet collectors get` Get one Fleet Management collector by ID or name. Structured output includes local and remote attributes plus the timestamps that the Fleet API reports. Use table or wide output for a human-readable health view. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet collectors get [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Get the full collector resource gcx fleet collectors get # Show the collector health fields as a table gcx fleet collectors get -o wide # Select attributes and update time gcx fleet collectors get --json spec.local_attributes,spec.remote_attributes,spec.updated_at ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "yaml") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet collectors list` List Fleet Management collectors and their reported health attributes. Use –limit 0 for a complete fleet audit. Structured output includes local and remote attributes plus the timestamps that the Fleet API reports. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet collectors list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List a bounded collector summary gcx fleet collectors list # Audit versions and operating systems across the complete fleet gcx fleet collectors list --limit 0 --json spec.id,spec.local_attributes,spec.updated_at # Build a compact version inventory gcx fleet collectors list --limit 0 --jq '[.[] | {id: .spec.id, version: .spec.local_attributes["collector.version"], os: (.spec.local_attributes["collector.os"] // .spec.local_attributes["os.type"]), updated_at: .spec.updated_at}]' ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of collectors to return. 0 means all results are returned (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet collectors update` Update a collector from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet collectors update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the collector manifest (use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet pipelines` Manage Fleet Management pipelines. **Aliases:** `pipeline` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for pipelines ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet pipelines create` Create a pipeline from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet pipelines create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the pipeline manifest (use - for stdin) --force Override protection guard for instrumentation-managed pipelines -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet pipelines delete` Delete a pipeline. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet pipelines delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Override protection guard for instrumentation-managed pipelines -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet pipelines get` Get a pipeline by ID or name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet pipelines get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet pipelines list` List pipelines. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet pipelines list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet pipelines update` Update a pipeline from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet pipelines update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the pipeline manifest (use - for stdin) --force Override protection guard for instrumentation-managed pipelines -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet tenant` Fleet Management tenant settings. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for tenant ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx fleet tenant get-limits` Get tenant limits. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx fleet tenant get-limits [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get-limits --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx fleet`](#gcx-fleet-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend` Manage Grafana Frontend Observability resources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for frontend ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend apps` Manage Frontend Observability apps. **Aliases:** `app` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for apps ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend apps apply-sourcemap` Upload a sourcemap for a Frontend Observability app. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx frontend apps apply-sourcemap [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Upload a sourcemap bundle. gcx frontend apps apply-sourcemap my-web-app-42 -f bundle.js.map ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --bundle-id string Bundle ID (auto-generated if not set) -f, --filename string Path to the sourcemap file to upload -h, --help help for apply-sourcemap --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend apps create` Create a Frontend Observability app from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx frontend apps create [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Create an app from a YAML file. gcx frontend apps create -f app.yaml # Create from stdin. cat app.yaml | gcx frontend apps create -f - ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the Frontend Observability app manifest (use - for stdin) -h, --help help for 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`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend apps delete` Delete a Frontend Observability app. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx frontend apps delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend apps delete-sourcemap` Delete sourcemap bundles from a Frontend Observability app. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx frontend apps delete-sourcemap [bundle-id...] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Delete a single sourcemap bundle. gcx frontend apps delete-sourcemap my-web-app-42 1234567890-abc12 # Delete multiple bundles at once. gcx frontend apps delete-sourcemap my-web-app-42 bundle-1 bundle-2 bundle-3 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for delete-sourcemap --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend apps get` Get a Frontend Observability app by slug-id or name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx frontend apps get [slug-id] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Get by slug-id. gcx frontend apps get my-web-app-42 # Get by name. gcx frontend apps get --name "My Web App" ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Get Frontend Observability app by name instead of slug-id -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend apps list` List Frontend Observability apps. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx frontend apps list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for unlimited) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend apps list-sourcemaps` List sourcemaps for a Frontend Observability app. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx frontend apps list-sourcemaps [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all sourcemaps for an app. gcx frontend apps list-sourcemaps my-web-app-42 # List the first 10 sourcemaps. gcx frontend apps list-sourcemaps my-web-app-42 --limit 10 # Output as JSON. gcx frontend apps list-sourcemaps my-web-app-42 -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-sourcemaps --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of sourcemaps to return (0 for all) -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend apps update` Update a Frontend Observability app from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx frontend apps update [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Update an app using its slug-id. gcx frontend apps update my-web-app-42 -f app.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the Frontend Observability app manifest (use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend sessions` Inspect Frontend Observability sessions. **Aliases:** `session` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for sessions ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx frontend sessions get` Fetch one Frontend Observability session and write it as plain text. Two labeled blocks are produced: session metadata (once) and events (the user journey). Metadata is named fields once (sdk, app, user, os, geo, browser, device, session times), empty values omitted. Pinot events are TSV; Loki events are timestamp then the log line with those envelope keys stripped. –save writes that same dump. Default -o is text; -o json/yaml, –json, and –jq are rejected. Use –save so agents receive a small artifact receipt on stdout and then read the file. Pinot events use faro\_pinot\_events\_v2 on grafana-ops hosts and faro\_pinot\_events\_v1 everywhere else, matching Frontend Observability. -d/–datasource is the Grafana datasource UID (required). gcx fetches the datasource and infers Loki vs Pinot from its type. Each Loki query times out after 60s so a slow scan cannot hang; try a Pinot datasource UID or a narrower window. Faro apps do not store web vs mobile on the app resource. Omit –app-type and gcx infers it from sdkName / osName on the session (so mobile journeys exclude app\_memory / app\_cpu\_usage). Pass –app-type to override. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx frontend sessions get [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Pinot on stdout (metadata fields, journey TSV) gcx frontend sessions get 7TiMbCCvby --app 66 -d grafanacloud-pinot --since 7d # Pinot dump to a file; app type inferred from telemetry gcx frontend sessions get 7TiMbCCvby --app 66 -d grafanacloud-pinot --since 7d \ --save /tmp/session-7TiMbCCvby.txt # Loki dump gcx frontend sessions get 7TiMbCCvby --app 66 -d grafanacloud-logs --since 7d \ --save /tmp/session-7TiMbCCvby.txt # Force mobile SQL (app_memory / app_cpu_usage excluded) gcx frontend sessions get kwwAkkXwas --app 96 --app-type mobile \ -d grafanacloud-pinot --since 7d --save /tmp/session-kwwAkkXwas.txt ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --app string Frontend Observability app slug-id or numeric id (required) --app-type string web or mobile (case-insensitive). Optional: inferred from sdkName/osName when omitted -d, --datasource string Grafana datasource UID (required). Type is inferred (loki or pinot) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for get -o, --output string Output format. One of: text (default "text") --save string Write the session dump to this path instead of stdout --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx frontend`](#gcx-frontend-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx help` Help provides help for any command in the application. Simply type gcx help \[path to command] for full details. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx help [command] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for help ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx help-tree` Outputs a token-efficient text tree of the CLI hierarchy with inline args, flags, and agent hints. Designed for injecting into agent context windows. Use positional arguments to show only a subtree (e.g., “gcx help-tree resources get”). Use –depth to limit nesting depth. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx help-tree [COMMAND...] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --depth int Maximum nesting depth (1 = root + direct children, 0 = unlimited) -h, --help help for help-tree --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation` Manage Grafana Instrumentation Hub using action-verb commands. The instrumentation command tree provides: setup Guided onboarding wizard: configures a cluster end-to-end and prints a runnable helm install command. status Cross-cutting observed state for clusters and namespaces (RunK8sMonitoring + ListPipelines merge). check Validate OpenTelemetry instrumentation for an application running locally (env vars, SDK, collector, Beyla, Alloy, Grafana Cloud connectivity). explain Show a markdown explanation for an otel-checker finding by its explain ID. list-explanations Enumerate every registered otel-checker explain ID with its title and severity. clusters Declared and observed state per K8s cluster: list, get, configure, remove, wait. Sub-group “apps” manages namespace-level Beyla configuration. services Workload-level observed state and per-workload inclusion overrides across the fleet: list, get, include, exclude, clear. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for instrumentation ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation check` Validate OpenTelemetry instrumentation configuration for an application running locally. Checks performed: - Common OTEL\_* environment variables (resource attributes, exporter, etc.) - SDK setup and dependencies for the chosen language - OpenTelemetry Collector config file (YAML schema, pipelines, exporters) - Grafana Beyla configuration - Grafana Alloy configuration - Grafana Cloud connectivity (uses env vars for endpoint and credentials) Components is an optional comma-separated list — defaults to all when omitted. Supported components: sdk, beyla, alloy, collector, grafana-cloud. Add –fix-plan=local for a deterministic aggregation of the explanation docs (offline, no billing), or –fix-plan=assistant for a prioritized plan synthesized by Grafana Assistant (BILLABLE, requires a Grafana Cloud context — see [https://grafana.com/docs/grafana-cloud/machine-learning/assistant/pricing.md)](/docs/grafana-cloud/machine-learning/assistant/pricing.md%29). Powered by github.com/grafana/otel-checker. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation check [components] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --collector-config-path string Path to the OpenTelemetry Collector config file. --debug Print additional diagnostic output from the checker. --fix-plan string Synthesize one fix plan for every finding. Values: local - deterministic aggregation of the explanation docs (offline, no billing). assistant - prioritized plan from Grafana Assistant (BILLABLE, requires a Grafana Cloud context). See https://grafana.com/docs/grafana-cloud/machine-learning/assistant/pricing.md. Empty (flag omitted) skips the fix plan. -h, --help help for check --instrumentation-file string Path to the JS instrumentation file. Required when --language=js and --manual-instrumentation. --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --language string Application language. Required for sdk, beyla, alloy, grafana-cloud. Possible values: dotnet, go, java, js, python, ruby, php --manual-instrumentation Application is using manual instrumentation (JS only). -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --package-json-path string Path to package.json for JS dependency checks. ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters` Manage K8s monitoring configuration for clusters. Subcommands: list List all clusters with their instrumentation status get Show declared config and observed status for a single cluster configure Configure K8s monitoring flags (RMW or apply defaults) remove Remove K8s monitoring from a cluster wait Wait until a cluster reaches INSTRUMENTED status apps Manage namespace-level Beyla instrumentation for a cluster **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for clusters ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters apps` Manage namespace-level Beyla auto-instrumentation configuration for a cluster. Commands operate on the declared state stored in Grafana Cloud’s instrumentation service (GetAppInstrumentation / SetAppInstrumentation). The wait command reads observed state from RunK8sDiscovery. Identity is positional: configure and remove take and as the first two positional arguments. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for apps ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters apps configure` Configure Beyla auto-instrumentation for a namespace within the given cluster. Two mutually exclusive modes: –use-defaults –yes Apply all-on canonical defaults, overwriting current state. Requires –yes. Defaults: autoinstrument=true, all signals enabled. –\[=true|false] (one or more) Set listed features; unspecified features preserve their current value (RMW). Idempotent. No confirmation required. Combining –use-defaults with any – flag is an error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters apps configure [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --extended-metrics Set extended Beyla metrics collection. Pass --extended-metrics=false to disable. -h, --help help for configure --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --logging Set log collection. Pass --logging=false to disable. -o, --output string Output format. One of: agents, json, text, yaml (default "text") --process-metrics Set process-level metrics collection. Pass --process-metrics=false to disable. --profiling Set continuous profiling collection. Pass --profiling=false to disable. --tracing Set distributed tracing collection. Pass --tracing=false to disable. --use-defaults Apply all-on canonical defaults. Requires --yes. --yes Confirm the --use-defaults operation (required with --use-defaults) ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters apps get` Get the declared Beyla instrumentation configuration for a single namespace within the given cluster. Reads declared state from GetAppInstrumentation and filters client-side to the requested namespace. Exits non-zero with a not-found error when the namespace has no declared configuration. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters apps get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, wide, yaml (default "text") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters apps list` List all namespace-level Beyla instrumentation entries for the given cluster. Reads declared state from GetAppInstrumentation (a single RPC call). The output reflects the configuration stored in Grafana Cloud, not the live observed state. Use “gcx instrumentation status” for observed-state status. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters apps list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, wide, yaml (default "text") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters apps remove` Remove Beyla auto-instrumentation for a namespace by removing its entry from the cluster’s app instrumentation configuration. The namespace entry is removed from namespaces\[] via a whole-list replacement (SetAppInstrumentation). When no namespace entries remain with included content, the backend deletes the app pipeline entirely. This command requires –yes to proceed. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters apps remove [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for remove --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --yes Confirm removal of namespace app instrumentation ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters apps wait` Wait for the namespace Beyla instrumentation to transition out of a pending state by polling RunK8sDiscovery at 5-second intervals. Exit 0 when the namespace’s workloads reach a stable non-pending state (INSTRUMENTED, NOT\_INSTRUMENTED, EXCLUDED, or any terminal non-error state). Exit non-zero when: - INSTRUMENTATION\_ERROR is observed for any workload. - The –timeout duration elapses while still in a pending state. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters apps wait [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for wait --timeout duration Maximum time to wait (e.g. 5m, 10m, 1h) (default 5m0s) ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters configure` Configure K8s monitoring feature flags on a cluster. Two mutually exclusive modes: –use-defaults –yes Apply canonical defaults, overwriting current state. Requires –yes. Defaults: costMetrics=true, clusterEvents=true, energyMetrics=false, nodeLogs=false. –\[=true|false] (one or more) Set listed features; unspecified features preserve their current value (RMW). Idempotent. No confirmation required. Combining –use-defaults with any – flag is an error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters configure [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Apply defaults to cluster "prod-eu" gcx instrumentation clusters configure prod-eu --use-defaults --yes # Enable cost metrics, preserving other flags (RMW) gcx instrumentation clusters configure prod-eu --cost-metrics # Disable node logs (RMW) gcx instrumentation clusters configure prod-eu --node-logs=false ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --cluster-events Set clusterEvents. Pass --cluster-events=false to disable. --cost-metrics Set costMetrics. Pass --cost-metrics=false to disable. Omit to preserve current value. --energy-metrics Set energyMetrics. Pass --energy-metrics=false to disable. -h, --help help for configure --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --node-logs Set nodeLogs. Pass --node-logs=false to disable. -o, --output string Output format. One of: agents, json, text, yaml (default "text") --use-defaults Apply canonical defaults (costMetrics=true, clusterEvents=true, energyMetrics=false, nodeLogs=false). Requires --yes. --yes Confirm the --use-defaults operation (required with --use-defaults) ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters get` Show the declared K8s monitoring configuration and observed instrumentation status for a single cluster. The declared configuration is fetched via GetK8SInstrumentation. The observed status is cross-referenced with RunK8sMonitoring. If the cluster is absent from RunK8sMonitoring, ListPipelines is checked: a K8s monitoring pipeline present means PENDING\_INSTRUMENTATION; absent means NOT\_INSTRUMENTED. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters get [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Get cluster "prod-eu" in table format gcx instrumentation clusters get prod-eu # Get in JSON format gcx instrumentation clusters get prod-eu -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters list` List all clusters with their K8s monitoring configuration and observed status. Merges RunK8sMonitoring with ListPipelines to surface clusters that have been configured but whose Alloy collector has not yet started reporting (pre-Alloy clusters appear with PENDING\_INSTRUMENTATION status). For each cluster, the declared configuration is fetched concurrently via GetK8SInstrumentation (up to 10 concurrent requests). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all clusters (table output) gcx instrumentation clusters list # List in wide format (shows all flag columns) gcx instrumentation clusters list -o wide # Output as JSON gcx instrumentation clusters list -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters remove` Remove K8s monitoring from a cluster. Calls SetK8SInstrumentation with Selection=SELECTION\_EXCLUDED. The backend interprets this as a request to delete the K8s monitoring pipeline for the cluster. IMPORTANT: After removing, the cluster’s status takes approximately 5 minutes to transition from INSTRUMENTED to NOT\_INSTRUMENTED. During this decay window, the cluster may still appear as INSTRUMENTED in status output. This is expected behaviour — the Alloy collector drains its in-flight telemetry before stopping. Requires –yes to confirm the destructive operation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters remove [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Remove K8s monitoring for cluster "prod-eu" gcx instrumentation clusters remove prod-eu --yes ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for remove --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --yes Confirm the remove operation (required) ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation clusters wait` Poll until the specified cluster reaches INSTRUMENTED status. The command polls RunK8sMonitoring every 5 seconds. Before starting the polling loop, it performs a pre-flight check to verify the cluster has been declared (via gcx instrumentation setup) — if not configured, it returns an error immediately with a remediation hint. Exit codes: 0 Cluster reached INSTRUMENTED status (or a non-error terminal state) 1 Timeout reached before INSTRUMENTED status 1 INSTRUMENTATION\_ERROR status observed 1 Pre-flight check failed (cluster not declared) shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation clusters wait [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Wait with default 5-minute timeout gcx instrumentation clusters wait prod-eu # Wait with a custom timeout gcx instrumentation clusters wait prod-eu --timeout 10m ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for wait --timeout duration Maximum time to wait for INSTRUMENTED status (default 5m0s) ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation explain` Show a markdown explanation document for an otel-checker finding. Each finding emitted by `gcx instrumentation check` may carry an explain ID (e.g. env.otel-service-name.unset). Passing that ID here prints the full explanation — what the finding means, why it matters, and how to fix it. To see every available ID, run `gcx instrumentation list-explanations`. Powered by github.com/grafana/otel-checker. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation explain [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for explain --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation list-explanations` List every registered otel-checker explain ID with its title and severity. Use one of the IDs with `gcx instrumentation explain ` to see the full explanation for a specific finding. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation list-explanations [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-explanations --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation services` Manage workload-level observed state and per-workload inclusion overrides across the fleet. Subcommands: list List all discovered workloads, with optional filtering. get Get a single workload by (cluster, namespace, service). include Include a workload for instrumentation (DWIM, idempotent). exclude Exclude a workload from instrumentation (DWIM, idempotent). clear Remove a per-workload override, inheriting namespace default. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for services ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation services clear` Remove any per-workload inclusion or exclusion override for a workload. After clearing, the workload inherits the namespace autoinstrument default. The operation is idempotent: if no override exists for the workload, the command exits 0 without making any backend calls. The write uses an optimistic-lock guard (rmw.Update) when a change is needed: if the namespace list changes between the initial read and the pre-write re-check, the command returns a conflict error and must be retried. Examples: gcx instrumentation services clear prod-1 checkout frontend shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation services clear [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for clear --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation services exclude` Exclude a specific workload from instrumentation using DWIM semantics. DWIM logic: - Removes any existing INCLUDED override for the workload. - Adds an EXCLUDED override iff the namespace autoinstrument is explicitly true (i.e. the namespace default is on, so an explicit opt-out is needed). - If the namespace autoinstrument is false/nil, no override is added (the namespace default is already off — adding EXCLUDED would be redundant). The operation is idempotent: running it twice with the same args exits 0 and the second call is a no-op against the backend. The write uses an optimistic-lock guard (rmw.Update): if the namespace list changes between the initial read and the pre-write re-check, the command returns a conflict error and must be retried. Examples: gcx instrumentation services exclude prod-1 checkout payment-svc shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation services exclude [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for exclude --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation services get` Get a single workload discovered by the Beyla survey collector. Calls RunK8sDiscovery() (fleet-wide RPC) and filters to the requested workload. Returns an error if the workload is not found. Examples: gcx instrumentation services get prod-1 checkout frontend gcx instrumentation services get prod-1 checkout frontend -o json Workload-level Selection / override state is not surfaced on this command. To inspect a workload’s override, run “gcx instrumentation clusters apps list –cluster= –namespace=”. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation services get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, wide, yaml (default "text") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation services include` Include a specific workload for instrumentation using DWIM semantics. DWIM logic: - Removes any existing EXCLUDED override for the workload. - Adds an INCLUDED override iff the namespace autoinstrument is NOT explicitly true (i.e. the namespace default is off, so an explicit opt-in is needed). - If the namespace autoinstrument is true, no override is added (namespace default is already on — adding INCLUDED would be redundant). The operation is idempotent: running it twice with the same args exits 0 and the second call is a no-op against the backend. The write uses an optimistic-lock guard (rmw.Update): if the namespace list changes between the initial read and the pre-write re-check, the command returns a conflict error and must be retried. Examples: gcx instrumentation services include prod-1 checkout frontend shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation services include [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for include --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation services list` List all workloads discovered by the Beyla survey collector. Calls RunK8sDiscovery() (fleet-wide RPC) and applies client-side filters. Examples: # 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=”. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation services list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -A, --all Show services from all namespaces (fleet-wide) --cluster string Filter by cluster name -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -n, --namespace string Filter by Kubernetes namespace -o, --output string Output format. One of: agents, json, text, wide, yaml (default "text") --status string Filter by instrumentation status (e.g. ERROR, INSTRUMENTED) ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation setup` Onboard a Kubernetes cluster end-to-end by configuring K8s monitoring and printing a runnable helm install command. Steps performed: 1. Calls SetupK8sDiscovery — idempotent, safe to re-run. 2. Reads the cluster’s current K8s monitoring configuration. 3. Resolves desired flag values: prompts interactively (when stdin is a TTY and –use-defaults is absent) or applies defaults under –use-defaults: costMetrics=true clusterEvents=true energyMetrics=false nodeLogs=false Per-flag overrides (–cost-metrics\[=true|false], –cluster-events\[=true|false], –energy-metrics\[=true|false], –node-logs\[=true|false]) take precedence over defaults. 4. Calls SetK8SInstrumentation only when at least one flag changed. 5. Emits a mutation summary to stderr. 6. Prints a parameterized helm command to stdout. Re-running with unchanged inputs is safe and idempotent. The helm command installs grafana-cloud-onboarding and connects the cluster to Grafana Cloud via Fleet Management. Replace <YOUR\_CLOUD\_ACCESS\_TOKEN> with a Cloud Access Policy token scoped to metrics:read and set:alloy-data-write. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation setup [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --cluster-events Set clusterEvents under --use-defaults. Pass --cluster-events=false to disable. Omit to use default (true). --cost-metrics Set costMetrics under --use-defaults. Pass --cost-metrics=false to disable. Omit to use default (true). --energy-metrics Set energyMetrics under --use-defaults. Pass --energy-metrics=false to disable. Omit to use default (false). -h, --help help for setup --node-logs Set nodeLogs under --use-defaults. Pass --node-logs=false to disable. Omit to use default (false). --print-helm-only Print the helm command and exit; no server calls are made --use-defaults Apply defaults without prompting (required when stdin is not a TTY) ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx instrumentation status` Show observed instrumentation state across all clusters, or narrow to a specific cluster or namespace. Without flags, lists all clusters including pre-Alloy clusters that have been configured but whose Alloy collector has not yet started reporting (shown as PENDING\_INSTRUMENTATION). Use –cluster to filter to a single cluster. Add –namespace to drill down to workload-level status for a specific namespace, powered by RunK8sDiscovery. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx instrumentation status [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --cluster string Filter output to a specific cluster -h, --help help for status --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --namespace string Filter to a specific namespace; switches to workload-level view -o, --output string Output format. One of: agents, json, yaml (default "table") ``` Inherits `--config` from [`gcx instrumentation`](#gcx-instrumentation-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm` Manage Grafana IRM (OnCall + Incidents). Note: Grafana IRM is billed per monthly active user. Actions such as being on an OnCall schedule or escalation chain, changing alert group status, or creating and editing incidents count a user as active. See [https://grafana.com/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/irm-invoice.md](/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/irm-invoice.md). **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for irm ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents` Manage incidents. **Aliases:** `incident`, `inc` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for incidents ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents activity` Manage incident activity timeline. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for activity ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents activity add` Add a note to an incident’s activity timeline. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents activity add [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --body string Note body to add -h, --help help for add --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents close` Close (resolve) an incident. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents close [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for close --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents create` Create a new incident from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents create [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Create an incident from a YAML manifest: cat < [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents get-pir` Resolve the post-incident review (PIR) document URL for an incident. The URL is not carried in the incident payload. PIRs are optional and only the Google Workspace integration creates them, so the link exists only where that integration ran. It is recorded on the hook run that copied the PIR template, which this command reads and resolves. An incident can have more than one PIR document if the template was copied again; the most recently created one is reported. An incident without a PIR document prints nothing and exits 0. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents get-pir [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get-pir --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents list` List incidents, most recent first. –status and –severity are applied server-side. –labels and –from/–to are applied client-side, one page at a time, so a highly selective –labels filter can page through the full incident history before collecting –limit incidents. –query is a raw query-string escape hatch and cannot be combined with the structured –labels, –status, or –severity filters. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start of time range (RFC3339, unix timestamp, or relative e.g. now-7d) -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --labels strings Filter by label text or key:value, e.g. squad:mimir (may be repeated) --limit int Maximum number of incidents to return (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --query string Raw incident query string, e.g. "isdrill:true"; cannot be combined with --labels, --status, or --severity --severity string Filter by severity label, e.g. major (see: gcx irm incidents severities list) --status strings Filter by status (active|resolved; repeatable, comma-separated) --to string End of time range (RFC3339, unix timestamp, or relative e.g. now) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents list-activity` List activity items for an incident. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents list-activity [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-activity --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of activity items to return (default 50) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents list-contexts` List contexts attached to an incident. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents list-contexts [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --alert-group-id string Filter by linked alert group ID -h, --help help for list-contexts --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of contexts to return (0 = server default) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --status string Filter by context status --type string Filter by context type (e.g. genericURL, grafana.dashboard, code.github.pr). Note: alert-group links are encoded as genericURL contexts with alertGroupID set — use --alert-group-id to filter those. ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents open` Open an incident in the browser. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents open [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for open ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents severities` Manage incident severity levels. **Aliases:** `severity` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for severities ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents severities list` List severity levels for the organization. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents severities list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm incidents update` Update the severity or the title of an incident. The severity is the display label, not the identifier. Run `gcx irm incidents severities list` for the labels of your organization. gcx reads the incident first, so a value that already matches causes no write. The command prints one line that names the fields it changed. Use -o json or -o yaml for a structured update result. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm incidents update [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Raise the severity of an incident: gcx irm incidents update 4 --severity Critical # Correct the title: gcx irm incidents update 4 --title "Checkout latency above the objective" ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --severity string New severity label (run 'gcx irm incidents severities list' for the valid values) --title string New title ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall` Manage Grafana OnCall resources. **Aliases:** `oc` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for oncall ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups` Manage alert groups. **Aliases:** `alert-group`, `ag` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for alert-groups ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups acknowledge` Acknowledge alert groups. Two forms are supported: - Single-target: pass a positional . - Bulk-by-filter: omit the positional and pass one or more filter flags (–team, –state, –integration, –max-age, –mine, –all). Bulk-by-filter prompts for confirmation in TTY mode when the matched count exceeds 1; pass –force to skip the prompt. Agent mode requires –force explicitly when count > 1 (auto-confirm of destructive bulk operations is disabled by design). Idempotent: re-running on an already-acknowledged group reports changed:false (single-target) or summary.skipped++ (bulk) — not an error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups acknowledge [] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all Bypass the default status and is_root filters --force Skip the count-confirmation prompt and proceed without interactive confirmation -h, --help help for acknowledge --integration strings Filter: integration PK (repeatable) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-age string Filter: alert groups started within this duration (e.g. 1h, 24h, 7d) --mine Filter: limit to alert groups for the authenticated user -o, --output string Output format. One of: agents, json, text, yaml (default "text") --state strings Filter: state (firing|acknowledged|resolved|silenced; repeatable) --team strings Filter: team PK (repeatable) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups delete` Delete alert groups. Two forms are supported: - Single-target: pass a positional . - Bulk-by-filter: omit the positional and pass one or more filter flags (–team, –state, –integration, –max-age, –mine, –all). Bulk-by-filter prompts for confirmation in TTY mode when the matched count exceeds 1; pass –force to skip the prompt. Agent mode requires –force explicitly when count > 1 (auto-confirm of destructive bulk operations is disabled by design). Destructive: delete removes the alert group; there is no idempotent skip path. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups delete [] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all Bypass the default status and is_root filters --force Skip the count-confirmation prompt and proceed without interactive confirmation -h, --help help for delete --integration strings Filter: integration PK (repeatable) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-age string Filter: alert groups started within this duration (e.g. 1h, 24h, 7d) --mine Filter: limit to alert groups for the authenticated user -o, --output string Output format. One of: agents, json, text, yaml (default "text") --state strings Filter: state (firing|acknowledged|resolved|silenced; repeatable) --team strings Filter: team PK (repeatable) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups get` Get an alert group by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --include-raw Include the unprocessed Alertmanager-shape payload under status.raw (hidden by default; the curated status.{target,links,...} blocks are the promoted view of the same data) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups list` List alert groups. By default, lists root alert groups (excluding child groups merged into parents) in firing, acknowledged, or silenced state. Resolved groups are excluded. Use –all to bypass these defaults entirely (returns resolved and child groups too). Use –state to override the status filter (e.g. –state firing,acknowledged). Use –include-child-groups to keep the status default but include child groups. Alert group records carry no escalation chain field, so –escalation-chain is the only way to attribute alert load to the rotation that was actually paged. It is not interchangeable with –integration: one integration routes to several chains. –max-age anchors to now; use –from/–to for a historical started-at window, and –resolved-from/–resolved-to for a resolved-at window. They accept RFC3339, a unix timestamp, or a relative expression like now-30d. –max-age and –from/–to cannot be combined. –limit 0 returns every matching alert group, walking the endpoint’s pages until they are exhausted. Over a wide window on a busy stack that is many sequential requests, so narrow the window or the filters when a partial answer will do. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List firing, acknowledged, and silenced root groups gcx irm oncall alert-groups list # Narrow to one team, most recent day gcx irm oncall alert-groups list --team --max-age 24h # Attribute load to a rotation (chain IDs: gcx irm oncall escalation-chains list) gcx irm oncall alert-groups list --escalation-chain --all # Historical window, including resolved groups gcx irm oncall alert-groups list --from now-30d --to now-7d --all # Groups resolved last week by a given user gcx irm oncall alert-groups list --resolved-by --resolved-from now-7d --all ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --acknowledged-by strings Filter by acknowledging user ID (repeatable, comma-separated; see: gcx irm oncall users list) --all Bypass the default status and is_root filters (returns resolved groups and child groups too) --escalation-chain strings Filter by escalation chain ID (repeatable, comma-separated; see: gcx irm oncall escalation-chains list) --from string Start of the started-at window (RFC3339, unix timestamp, or relative e.g. now-30d); cannot be combined with --max-age --has-related-incident Limit to alert groups linked to an incident -h, --help help for list --include-child-groups Include child groups (drops the is_root filter while keeping the status default) --integration strings Filter by integration PK (repeatable, comma-separated) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of alert groups to return. 0 means all results are returned (default 50) --max-age string Exclude groups older than this duration (e.g. 1h, 24h, 7d) --mine Limit to alert groups for the authenticated user -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --resolved-by strings Filter by resolving user ID (repeatable, comma-separated; see: gcx irm oncall users list) --resolved-from string Start of the resolved-at window (RFC3339, unix timestamp, or relative e.g. now-30d) --resolved-to string End of the resolved-at window (RFC3339, unix timestamp, or relative e.g. now-7d); defaults to now --state strings Filter by state (firing|acknowledged|resolved|silenced; repeatable, comma-separated). Default: firing,acknowledged,silenced --team strings Filter by team PK (repeatable, comma-separated) --to string End of the started-at window (RFC3339, unix timestamp, or relative e.g. now-7d); defaults to now --with-resolution-note Limit to alert groups that have a resolution note ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups list-alerts` List individual alerts for an alert group. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups list-alerts [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-alerts --history Opt out of collapse: emit every stored Alert as its own row with status.occurrences=1 (default behaviour collapses re-fires by alert label set) --include-raw Include the unprocessed Alertmanager-shape payload under status.raw on each alert (hidden by default; status.{dimensions,links,...} are the promoted view of the same data) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Cap on number of alerts retrieved (0 = no cap) (default 100) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --slim Skip per-alert retrieval; emit only metadata + alert-group back-pointer ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups resolve` Resolve alert groups. Two forms are supported: - Single-target: pass a positional . - Bulk-by-filter: omit the positional and pass one or more filter flags (–team, –state, –integration, –max-age, –mine, –all). Bulk-by-filter prompts for confirmation in TTY mode when the matched count exceeds 1; pass –force to skip the prompt. Agent mode requires –force explicitly when count > 1 (auto-confirm of destructive bulk operations is disabled by design). Idempotent: re-running on an already-resolved group reports changed:false (single-target) or summary.skipped++ (bulk) — not an error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups resolve [] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all Bypass the default status and is_root filters --force Skip the count-confirmation prompt and proceed without interactive confirmation -h, --help help for resolve --integration strings Filter: integration PK (repeatable) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-age string Filter: alert groups started within this duration (e.g. 1h, 24h, 7d) --mine Filter: limit to alert groups for the authenticated user -o, --output string Output format. One of: agents, json, text, yaml (default "text") --state strings Filter: state (firing|acknowledged|resolved|silenced; repeatable) --team strings Filter: team PK (repeatable) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups silence` Silence alert groups. Two forms are supported: - Single-target: pass a positional . - Bulk-by-filter: omit the positional and pass one or more filter flags (–team, –state, –integration, –max-age, –mine, –all). Bulk-by-filter prompts for confirmation in TTY mode when the matched count exceeds 1; pass –force to skip the prompt. Agent mode requires –force explicitly when count > 1 (auto-confirm of destructive bulk operations is disabled by design). Idempotent: re-running on an already-silenced group reports changed:false (single-target) or summary.skipped++ (bulk) — not an error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups silence [] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all Bypass the default status and is_root filters --duration int Silence duration in seconds (default 3600) --force Skip the count-confirmation prompt and proceed without interactive confirmation -h, --help help for silence --integration strings Filter: integration PK (repeatable) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-age string Filter: alert groups started within this duration (e.g. 1h, 24h, 7d) --mine Filter: limit to alert groups for the authenticated user -o, --output string Output format. One of: agents, json, text, yaml (default "text") --state strings Filter: state (firing|acknowledged|resolved|silenced; repeatable) --team strings Filter: team PK (repeatable) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups unacknowledge` Unacknowledge alert groups. Two forms are supported: - Single-target: pass a positional . - Bulk-by-filter: omit the positional and pass one or more filter flags (–team, –state, –integration, –max-age, –mine, –all). Bulk-by-filter prompts for confirmation in TTY mode when the matched count exceeds 1; pass –force to skip the prompt. Agent mode requires –force explicitly when count > 1 (auto-confirm of destructive bulk operations is disabled by design). Idempotent: re-running on an already-unacknowledged group reports changed:false (single-target) or summary.skipped++ (bulk) — not an error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups unacknowledge [] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all Bypass the default status and is_root filters --force Skip the count-confirmation prompt and proceed without interactive confirmation -h, --help help for unacknowledge --integration strings Filter: integration PK (repeatable) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-age string Filter: alert groups started within this duration (e.g. 1h, 24h, 7d) --mine Filter: limit to alert groups for the authenticated user -o, --output string Output format. One of: agents, json, text, yaml (default "text") --state strings Filter: state (firing|acknowledged|resolved|silenced; repeatable) --team strings Filter: team PK (repeatable) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups unresolve` Unresolve alert groups. Two forms are supported: - Single-target: pass a positional . - Bulk-by-filter: omit the positional and pass one or more filter flags (–team, –state, –integration, –max-age, –mine, –all). Bulk-by-filter prompts for confirmation in TTY mode when the matched count exceeds 1; pass –force to skip the prompt. Agent mode requires –force explicitly when count > 1 (auto-confirm of destructive bulk operations is disabled by design). Idempotent: re-running on an already-unresolved group reports changed:false (single-target) or summary.skipped++ (bulk) — not an error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups unresolve [] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all Bypass the default status and is_root filters --force Skip the count-confirmation prompt and proceed without interactive confirmation -h, --help help for unresolve --integration strings Filter: integration PK (repeatable) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-age string Filter: alert groups started within this duration (e.g. 1h, 24h, 7d) --mine Filter: limit to alert groups for the authenticated user -o, --output string Output format. One of: agents, json, text, yaml (default "text") --state strings Filter: state (firing|acknowledged|resolved|silenced; repeatable) --team strings Filter: team PK (repeatable) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall alert-groups unsilence` Unsilence alert groups. Two forms are supported: - Single-target: pass a positional . - Bulk-by-filter: omit the positional and pass one or more filter flags (–team, –state, –integration, –max-age, –mine, –all). Bulk-by-filter prompts for confirmation in TTY mode when the matched count exceeds 1; pass –force to skip the prompt. Agent mode requires –force explicitly when count > 1 (auto-confirm of destructive bulk operations is disabled by design). Idempotent: re-running on an already-unsilenced group reports changed:false (single-target) or summary.skipped++ (bulk) — not an error. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall alert-groups unsilence [] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all Bypass the default status and is_root filters --force Skip the count-confirmation prompt and proceed without interactive confirmation -h, --help help for unsilence --integration strings Filter: integration PK (repeatable) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-age string Filter: alert groups started within this duration (e.g. 1h, 24h, 7d) --mine Filter: limit to alert groups for the authenticated user -o, --output string Output format. One of: agents, json, text, yaml (default "text") --state strings Filter: state (firing|acknowledged|resolved|silenced; repeatable) --team strings Filter: team PK (repeatable) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalate` Create a direct escalation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalate [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for escalate --important Mark as important --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --message string Message for the escalation -o, --output string Output format. One of: agents, json, text, yaml (default "text") --team string Team ID --title string Title of the escalation (required) --user-ids strings User IDs (comma-separated) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-chains` Manage escalation chains. **Aliases:** `escalation-chain`, `ec` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for escalation-chains ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-chains create` Create an escalation chain. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-chains create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-chains delete` Delete an escalation chain by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-chains delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-chains get` Get an escalation chain by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-chains get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-chains list` List escalation chains. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-chains list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-chains update` Update an escalation chain by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-chains update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-policies` Manage escalation policies. **Aliases:** `escalation-policy`, `ep` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for escalation-policies ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-policies create` Create an escalation policy. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-policies create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-policies delete` Delete an escalation policy by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-policies delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-policies get` Get an escalation policy by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-policies get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-policies list` List escalation policies. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-policies list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-policies list-step-types` List the step types that an escalation policy accepts. The command reads the catalog from the Incident Response and Management backend, so the values match your stack. Put the numeric value in the step field of an escalation policy manifest. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-policies list-step-types [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List the step types that an escalation policy accepts gcx irm oncall escalation-policies list-step-types # Read the numeric value of one step type gcx irm oncall escalation-policies list-step-types -o json | jq -r '.[] | select(.display_name == "") | .value' # Put that value in the step field of policy.yaml, then create the policy gcx irm oncall escalation-policies create -f policy.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-step-types --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-policies steps` Discover allowed escalation policy step types. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for steps ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-policies steps list` List the step types that an escalation policy accepts. The command reads the catalog from the Incident Response and Management backend, so the values match your stack. Put the numeric value in the step field of an escalation policy manifest. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-policies steps list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List the step types that an escalation policy accepts gcx irm oncall escalation-policies list-step-types # Read the numeric value of one step type gcx irm oncall escalation-policies list-step-types -o json | jq -r '.[] | select(.display_name == "") | .value' # Put that value in the step field of policy.yaml, then create the policy gcx irm oncall escalation-policies create -f policy.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall escalation-policies update` Update an escalation policy by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall escalation-policies update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations` Manage OnCall integrations. **Aliases:** `integration` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for integrations ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations create` Create an integration. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall integrations create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations delete` Delete an integration by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall integrations delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations get` Get an integration by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall integrations get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations get-templates` Get the alert templates of an integration. The templates decide what a responder reads and hears: the alert title, the message, the grouping identifier, the resolve condition, and a separate rendering for each channel (web, phone call, Short Message Service, email, Slack, and Microsoft Teams). The command emits the whole template document. Edit that document, then pass it back through update-templates. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall integrations get-templates [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get-templates --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations list` List OnCall integrations. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall integrations list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations start-maintenance` Start maintenance on an integration. Maintenance suppresses escalation during planned work. Mode “maintenance” groups every alert of the integration into one alert group and pages nobody. Mode “debug” routes each alert to its author only. The backend accepts these durations only: 3600, 10800, 21600, 43200, 86400 seconds. These values are 1, 3, 6, 12, and 24 hours. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall integrations start-maintenance [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --duration int Maintenance duration in seconds (3600, 10800, 21600, 43200, 86400) (default 3600) -h, --help help for start-maintenance --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --mode string Maintenance mode (debug, maintenance) (default "maintenance") -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations stop-maintenance` Stop maintenance on an integration. Use this to end maintenance before its scheduled end. Escalation resumes at once. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall integrations stop-maintenance [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for stop-maintenance --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations update` Update an integration by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall integrations update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall integrations update-templates` Replace the alert templates of an integration. The file holds the template document as get-templates emits it. Every field travels to the backend unchanged, so a field that this build does not know about still survives a get, an edit, and an update. The command emits the stored document. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall integrations update-templates [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update-templates --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall organizations` View organization info. **Aliases:** `organization`, `org` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for organizations ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall organizations get` Get organization info. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall organizations get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall resolution-notes` Manage resolution notes. **Aliases:** `resolution-note`, `rn` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for resolution-notes ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall resolution-notes create` Create a resolution note. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall resolution-notes create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall resolution-notes delete` Delete a resolution note by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall resolution-notes delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall resolution-notes get` Get a resolution note by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall resolution-notes get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall resolution-notes list` List resolution notes. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall resolution-notes list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall resolution-notes update` Update a resolution note by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall resolution-notes update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall routes` Manage OnCall routes. **Aliases:** `route` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for routes ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall routes create` Create a route. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall routes create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall routes delete` Delete a route by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall routes delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall routes filter-types` Discover route filtering term types. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for filter-types ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall routes filter-types list` List the filter types that a route accepts. The command reads the catalog from the Incident Response and Management backend, so the values match your stack. Put the numeric value in the filtering\_term\_type field of a route manifest. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall routes filter-types list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List the filter types that a route accepts gcx irm oncall routes list-filter-types # Read the numeric value of one filter type gcx irm oncall routes list-filter-types -o json | jq -r '.[] | select(.display_name == "") | .value' # Put that value in the filtering_term_type field of route.yaml, then create the route gcx irm oncall routes create -f route.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall routes get` Get a route by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall routes get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall routes list` List OnCall routes. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall routes list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall routes list-filter-types` List the filter types that a route accepts. The command reads the catalog from the Incident Response and Management backend, so the values match your stack. Put the numeric value in the filtering\_term\_type field of a route manifest. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall routes list-filter-types [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List the filter types that a route accepts gcx irm oncall routes list-filter-types # Read the numeric value of one filter type gcx irm oncall routes list-filter-types -o json | jq -r '.[] | select(.display_name == "") | .value' # Put that value in the filtering_term_type field of route.yaml, then create the route gcx irm oncall routes create -f route.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-filter-types --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall routes update` Update a route by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall routes update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall schedules` Manage OnCall schedules. **Aliases:** `schedule` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for schedules ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall schedules create` Create a schedule. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall schedules create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall schedules delete` Delete a schedule by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall schedules delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall schedules get` Get a schedule by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall schedules get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall schedules list` List OnCall schedules. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall schedules list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall schedules list-final-shifts` List final shifts for a schedule. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall schedules list-final-shifts [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --end string End date (YYYY-MM-DD) (default "YYYY-MM-DD") -h, --help help for list-final-shifts --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --start string Start date (YYYY-MM-DD) (default "YYYY-MM-DD") --timezone string IANA timezone for the shift boundaries (default: the timezone of the schedule, else UTC) ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall schedules update` Update a schedule by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall schedules update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shift-swaps` Manage shift swaps. **Aliases:** `shift-swap`, `ss` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for shift-swaps ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shift-swaps create` Create a shift swap. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shift-swaps create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shift-swaps delete` Delete a shift swap by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shift-swaps delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shift-swaps get` Get a shift swap by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shift-swaps get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shift-swaps list` List shift swaps. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shift-swaps list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shift-swaps update` Update a shift swap by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shift-swaps update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shifts` Manage OnCall shifts. **Aliases:** `shift` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for shifts ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shifts create` Create a shift. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shifts create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shifts delete` Delete a shift by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shifts delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shifts get` Get a shift by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shifts get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shifts list` List OnCall shifts. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shifts list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall shifts update` Update a shift by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall shifts update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall slack-channels` List Slack channels. **Aliases:** `slack-channel` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for slack-channels ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall slack-channels list` List Slack channels. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall slack-channels list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall teams` Manage OnCall teams. **Aliases:** `team` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for teams ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall teams get` Get a team by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall teams get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall teams list` List OnCall teams. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall teams list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall user-groups` List user groups. **Aliases:** `user-group` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for user-groups ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall user-groups list` List user groups. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall user-groups list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall users` Manage OnCall users. **Aliases:** `user` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for users ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall users current` Get the current user. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall users current [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for current --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall users get` Get a user by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall users get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall users list` List OnCall users. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall users list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks` Manage outgoing webhooks. **Aliases:** `webhook` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for webhooks ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks create` Create an outgoing webhook. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall webhooks create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks delete` Delete an outgoing webhook by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall webhooks delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks get` Get an outgoing webhook by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall webhooks get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks list` List outgoing webhooks. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall webhooks list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks list-presets` List the presets that an outgoing webhook accepts. A preset fills a group of webhook fields, and it limits the trigger types of the webhook. Put the preset ID in the preset field of a webhook manifest. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall webhooks list-presets [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List the webhook presets gcx irm oncall webhooks list-presets # Read the trigger types that one preset allows gcx irm oncall webhooks list-presets -o json | jq -r '.[] | select(.id == "grafana_assistant") | .trigger_types' # Put the preset ID in the preset field of webhook.yaml, then create the webhook gcx irm oncall webhooks create -f webhook.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-presets --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks list-triggers` List the trigger types that an outgoing webhook accepts. The command reads the catalog from the Incident Response and Management backend, so the values match your stack. Put the numeric value in the trigger\_type field of a webhook manifest. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall webhooks list-triggers [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List the trigger types that a webhook accepts gcx irm oncall webhooks list-triggers # Read the numeric value of one trigger type gcx irm oncall webhooks list-triggers -o json | jq -r '.[] | select(.display_name == "") | .value' # Put that value in the trigger_type field of webhook.yaml, then create the webhook gcx irm oncall webhooks create -f webhook.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-triggers --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks presets` Discover webhook configuration presets. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for presets ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks presets list` List the presets that an outgoing webhook accepts. A preset fills a group of webhook fields, and it limits the trigger types of the webhook. Put the preset ID in the preset field of a webhook manifest. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall webhooks presets list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List the webhook presets gcx irm oncall webhooks list-presets # Read the trigger types that one preset allows gcx irm oncall webhooks list-presets -o json | jq -r '.[] | select(.id == "grafana_assistant") | .trigger_types' # Put the preset ID in the preset field of webhook.yaml, then create the webhook gcx irm oncall webhooks create -f webhook.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks triggers` Discover allowed webhook trigger types. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for triggers ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks triggers list` List the trigger types that an outgoing webhook accepts. The command reads the catalog from the Incident Response and Management backend, so the values match your stack. Put the numeric value in the trigger\_type field of a webhook manifest. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall webhooks triggers list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List the trigger types that a webhook accepts gcx irm oncall webhooks list-triggers # Read the numeric value of one trigger type gcx irm oncall webhooks list-triggers -o json | jq -r '.[] | select(.display_name == "") | .value' # Put that value in the trigger_type field of webhook.yaml, then create the webhook gcx irm oncall webhooks create -f webhook.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx irm oncall webhooks update` Update an outgoing webhook by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx irm oncall webhooks update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the resource definition (JSON/YAML, use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx irm`](#gcx-irm-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6` Manage Grafana k6 Cloud projects, load tests, and schedules **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for k6 ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 auth` k6 authentication commands. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for auth ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 auth token` Print the authenticated k6 API token. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 auth token [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for token ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 env-vars` Manage k6 Cloud environment variables. **Aliases:** `envvars`, `envvar`, `env` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for env-vars ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 env-vars create` Create a k6 environment variable from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 env-vars create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the env var JSON (use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 env-vars delete` Delete a k6 environment variable. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 env-vars delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 env-vars list` List k6 environment variables. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 env-vars list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 env-vars update` Update a k6 environment variable. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 env-vars update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the env var JSON (use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-tests` Manage k6 Cloud load tests. **Aliases:** `tests`, `test` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for load-tests ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-tests create` Create a new k6 load test. Note: running the created test in Grafana Cloud consumes billable Virtual User Hours (VUh). See [https://grafana.com/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/performance-testing-invoice.md](/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/performance-testing-invoice.md). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-tests create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the test definition (JSON/YAML) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Test name (required when --filename not used) -o, --output string Output format. One of: agents, json, yaml (default "yaml") --project-id int Project ID (required when --filename not used) --script string Path to k6 script file (required when --filename not used) ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-tests delete` Delete a k6 load test. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-tests delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-tests delete-schedule` Delete the schedule for a k6 load test. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-tests delete-schedule [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for delete-schedule --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-tests get` Get a single k6 load test by ID or name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-tests get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") --project-id int Project ID (required when looking up by name) ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-tests list` List k6 Cloud load tests. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-tests list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --project-id int Filter by project ID ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-tests update` Update a k6 load test from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-tests update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the test definition (JSON/YAML) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-tests update-script` Update the script of a k6 load test from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-tests update-script [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string k6 script file to upload -h, --help help for update-script --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-zones` Manage k6 private load zones. **Aliases:** `load-zone`, `lz` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for load-zones ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-zones create` Register a Private Load Zone. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-zones create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --cpu string CPU limit for load zone pods (default "2") -h, --help help for create --image string k6 runner image (default "grafana/k6:latest") --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --memory string Memory limit for load zone pods (default "1Gi") --name string Load zone name (must be unique in your org) -o, --output string Output format. One of: agents, json, text, yaml (default "text") --provider-id string Provider ID for the load zone ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-zones delete` Deregister a Private Load Zone. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-zones delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-zones list` List all k6 load zones. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-zones list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-zones list-allowed-projects` List projects allowed to use a load zone. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-zones list-allowed-projects [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-allowed-projects --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 load-zones update-allowed-projects` Replace the set of projects allowed to use a load zone. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 load-zones update-allowed-projects [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the complete replacement set of project IDs (JSON array) -h, --help help for update-allowed-projects --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 projects` Manage k6 Cloud projects. **Aliases:** `project`, `proj` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for projects ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 projects create` Create a new k6 project from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 projects create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the project manifest (use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 projects delete` Delete a k6 project. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 projects delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 projects get` Get a single k6 project by ID or name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 projects get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 projects list` List k6 Cloud projects. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 projects list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 projects list-allowed-load-zones` List load zones allowed for a project. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 projects list-allowed-load-zones [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-allowed-load-zones --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 projects update` Update a k6 project. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 projects update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the project manifest (use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 projects update-allowed-load-zones` Replace the set of load zones allowed for a project. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 projects update-allowed-load-zones [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the complete replacement set of load zone IDs (JSON array) -h, --help help for update-allowed-load-zones --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 runs` Manage k6 test runs. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for runs ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 runs list` List test runs for a load test. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 runs list [id-or-name] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --id int Load test ID (skip name lookup) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --project-id int Project ID (required when looking up by name) ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 schedules` Manage k6 Cloud schedules. **Aliases:** `schedule` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for schedules ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 schedules create` Create a k6 schedule from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 schedules create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the schedule request (JSON/YAML) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --load-test-id int Load test ID (required) -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 schedules get` Get a single k6 schedule by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 schedules get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 schedules list` List all k6 schedules. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 schedules list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 schedules update` Update a k6 schedule from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 schedules update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the schedule request (JSON/YAML) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 test-run` Manage k6 TestRun CRD manifests. **Aliases:** `testrun` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for test-run ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 test-run emit` Fetch a k6 Cloud test and emit Kubernetes TestRun CRD manifests. Note: applying the manifests (–apply) starts a test run that consumes billable Virtual User Hours (VUh). See [https://grafana.com/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/performance-testing-invoice.md](/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/performance-testing-invoice.md). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 test-run emit [test-name] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --apply Apply ConfigMap and TestRun manifests via kubectl --emit-secret Include Secret manifest stub in output -h, --help help for emit --id int Load test ID (skip name lookup) --namespace string Kubernetes namespace for emitted manifests (default "k6-tests") --parallelism int Number of parallel k6 runner pods (default 1) --project-id int k6 Cloud project ID --token-secret string Secret name for the Grafana Cloud token (default "grafana-k6-token") ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 test-run runs` Query k6 Cloud test run history. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for runs ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 test-run runs list` List all test runs for a k6 load test. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 test-run runs list [test-name] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --id int Load test ID (skip name lookup) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --project-id int k6 Cloud project ID (required when using name lookup) ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx k6 test-run status` Show the most recent test run status for a k6 load test. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx k6 test-run status [test-name] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for status --id int Load test ID (skip name lookup) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --project-id int k6 Cloud project ID (required when using name lookup) ``` Inherits `--config` from [`gcx k6`](#gcx-k6-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg` Manage Grafana Knowledge Graph rules, entities, and insights **Aliases:** `knowledge-graph` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for kg ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg diagnose` Run diagnostic checks to verify the Knowledge Graph is healthy. Checks stack status, sanity results, entity counts, scope values, telemetry drilldown configuration, and recording rule metrics in Mimir. Use –env to scope checks to a specific environment. Metric checks require a Prometheus datasource. The datasource UID is resolved from –datasource, the datasources.prometheus config key, or auto-discovery. If unavailable, metric checks are skipped. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg diagnose [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg diagnose gcx kg diagnose --env production gcx kg diagnose --env staging --output json gcx kg diagnose --datasource grafanacloud-prom ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Prometheus datasource UID (auto-discovered if omitted) --env string Environment scope -h, --help help for diagnose --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --namespace string Namespace scope -o, --output string Output format. One of: agents, json, table, yaml (default "table") --site string Site scope ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg diagnose labels` Check that deployment\_environment values in raw metrics are correctly mapped to asserts\_env in recording rule outputs. Identifies unmapped environments (services that won’t appear in Entity Graph) and orphaned asserts\_env values with no deployment\_environment source. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg diagnose labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg diagnose labels gcx kg diagnose labels --datasource grafanacloud-prom gcx kg diagnose labels -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Prometheus datasource UID (auto-discovered if omitted) -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg diagnose service` Deep diagnosis for a specific service: entity lookup, relationship analysis, per-service recording rule checks, and interpreted diagnosis with suggested next steps. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg diagnose service NAME [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg diagnose service api-gateway gcx kg diagnose service payment-service --env production gcx kg diagnose service checkout --env production --namespace default -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Prometheus datasource UID (auto-discovered if omitted) --env string Environment scope -h, --help help for service --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --namespace string Namespace scope -o, --output string Output format. One of: agents, json, table, yaml (default "table") --site string Site scope ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg entities` Manage Knowledge Graph entities. Prefer ’list’ for listing and for basic lookups (an entity’s identity and properties — the labels used to build PromQL/Loki queries); it is cheap and is the right choice even when you already know the exact entity. Use ‘inspect’ only for root-cause analysis — it is heavy and can return large output, so don’t reach for it just to read properties. Pick the read verb by what you start with: list Default for listing and basic lookups: an entity’s identity, scope, and properties. Filter to one known entity with ‘–property name=’. Cheap — use this for plain lookups. correlate You have a firing alert (its labels) but not the entity → find which entity the alert hangs off. The “I have an alert, which entity is it?” entry point. inspect Root-cause analysis only — heavy: insight timeline + related entities. Don’t use it just to read an entity’s properties (use ’list’); reach for it only when you need the RCA view. query Arbitrary Cypher over the graph. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for entities ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg entities correlate` Resolve the affected Knowledge Graph entities for one or more firing alerts. Give it an alert’s labels and a time window; it returns the entities the alert hangs off, using the same correlation the product uses to attach alerts to entities. This is the “I have an alert, which entity is it?” entry point — no entity type/name or Cypher required. Provide alerts as inline label sets, from an Alertmanager webhook file, or both: –alert-labels ‘k=v,k=v’ one firing alert per flag (repeatable) -f/–file / stdin Alertmanager JSON — an envelope {“alerts”:\[…]} or a bare array \[{“labels”:{…}}], auto-detected At least one of –alert-labels or -f is required. When nothing correlates the command prints a notice and exits 0 (an empty result is not an error). Note: correlation from a PromQL alert expression (–query) is not yet supported here — the backend fallback is unreliable today; use alert labels instead. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities correlate [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities correlate --alert-labels 'alertname=ErrorRatioBreach,job=cart' --since 1h gcx kg entities correlate -f am-webhook.json --since 1h cat am-webhook.json | gcx kg entities correlate -f - --since 6h ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --alert-labels stringArray Firing alert label set as comma-separated key=value pairs; one flag per alert (repeatable) -f, --file string Alertmanager webhook JSON file, or '-' for stdin (envelope {"alerts":[...]} or bare array [{"labels":...}]) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for correlate --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to (or now); mutually exclusive with --from/--to (default 1h; e.g. 1h, 30m, 7d) --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg entities delete` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Delete an API-origin entity. Scope is part of the entity’s identity, so it must match the value used at upsert — omitting it targets the scope-less entity, and a mismatch returns 404 (not found). This command uses the Knowledge Graph write API, which is gated server-side. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities delete [Type--Name] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --domain string Writable domain slug — a specific application domain such as 'irm' (required) --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Entity name (or use positional Type--Name) -o, --output string Output format. One of: agents, json, text, yaml (default "text") --scope stringToString Scope as key=value (repeatable or comma-separated; must match upsert-time scope) (default []) --type string Entity type (or use positional Type--Name) ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg entities inspect` Show detailed root-cause-analysis context for a single entity, including a link to the RCA Workbench. Use this only when you need the detail: the entity’s insight/assertion timeline and the related entities to investigate next. It calls a heavier endpoint and can return large output. Do not use ‘inspect’ just to read an entity’s identity or properties — for that, use ‘gcx kg entities list’ (optionally with ‘–property name=’ to narrow to one entity), which is cheaper and returns those fields directly. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities inspect [Type--Name] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --domain string Restrict scope auto-discovery to a single KG domain (only applies when scope is auto-discovered; no effect when --env/--namespace/--site is given) --env string Environment scope (run 'gcx kg meta scopes' to see valid values) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for inspect --insight-categories strings Filter insights by category (comma-separated, e.g. saturation,anomaly,failure,error,amend); empty = all categories --insight-hide-chronic-above int Hide insights present more than this percent of the window (0-100); overrides --insight-hide-noise on this axis --insight-hide-noise Apply RCA Workbench noise filter: hide insights older than 48h or present >90% of the window --insight-hide-older-than duration Hide insights older than a whole number of hours (e.g. 24h); overrides --insight-hide-noise on this axis --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Entity name --namespace string Namespace scope (run 'gcx kg meta scopes' to see valid values) --open Open the entity in the RCA Workbench in your browser -o, --output string Output format. One of: agents, json, yaml (default "json") --share-link Print the RCA Workbench URL for this entity to stderr --since string Duration before --to (or now); mutually exclusive with --from/--to (e.g. 1h, 30m, 7d) --site string Site scope (run 'gcx kg meta scopes' to see valid values) --to string End time (RFC3339, Unix timestamp, or relative like 'now') --type string Entity type (run 'gcx kg meta schema' to see available types) ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg entities list` List Knowledge Graph entities for a given type, env, site, namespace. The cheap default for listing entities or looking up basic information about one: its identity (name, type, scope), properties (the labels used to build PromQL/Loki queries — job, namespace, container, image, etc.), and a small snapshot of its current insights. Filter to a single entity with ‘–property name=’. For an entity’s full insight timeline or related entities for root-cause analysis, use ‘gcx kg entities inspect’ instead. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities list --type Service --env --namespace --property name= gcx kg entities list --type Service --env --insight any gcx kg entities list --type Service --env --insight name=Saturation --insight severity=critical gcx kg entities list --type Service --env --property name=~api --insight severity=critical gcx kg entities list --type Service --env --insight severity=critical --json name,scope ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --env string Environment scope (run 'gcx kg meta scopes' to see valid values) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for list --insight stringArray Filter to entities with an active insight: 'any' (has any insight) or key=value (key=~value for substring; name only); valid keys: name, severity (critical|warning|info); repeatable — multiple predicates must match the same assertion --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all; the backend may still page results — use --page to paginate) (default 50) --namespace string Namespace scope (run 'gcx kg meta scopes' to see valid values) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --page int Page number (0-based) --property stringArray Filter by property: name=value (exact) or name=~value (contains); repeatable (run 'gcx kg meta schema' to list property names) --since string Duration before --to (or now); mutually exclusive with --from/--to (e.g. 1h, 30m, 7d) --site string Site scope (run 'gcx kg meta scopes' to see valid values) --to string End time (RFC3339, Unix timestamp, or relative like 'now') --type string Entity type to list (run 'gcx kg meta schema' to see available types) ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg entities query` Query entities by running a read-only Cypher query against the Knowledge Graph. Run ‘gcx kg meta schema’ to discover valid entity types, property names, and relationship names. Response shape (not raw Cypher rows — results are aggregated into this envelope): { “entities”: \[ { “type”, “name”, “scope”, “properties”, “insights” }, … ], “edges”: \[ { “type”, “sourceName”, “sourceType”, “sourceScope”, “destinationName”, “destinationType”, “destinationScope” }, … ], “pageNum”: , “lastPage”: } Tips: - Prefer whole-entity projections like ‘RETURN s, d’ over scalar projections like ‘RETURN d.name’. Whole entities populate the ’entities’ array with full type/name/scope/properties; scalar projections do not round-trip through this envelope. - The –json flag selects keys from the envelope above (entities, edges, pageNum, lastPage) — it does NOT filter properties inside each entity. Use ‘–json list’ to see the envelope keys, then ‘–json entities’ and pipe to jq/python for per-entity field shaping. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities query [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities query "MATCH (s:Service) RETURN s LIMIT 10" gcx kg entities query "MATCH (s:Service)-[:CALLS]->(d:Service) RETURN s, d" --since 1h gcx kg entities query "MATCH (s:Service {namespace: 'prod'}) RETURN s" --since 1h ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --insights-only Return only entities with active insights --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --page int Page number (0-based) --since string Duration before --to (or now); mutually exclusive with --from/--to (e.g. 1h, 30m, 7d) --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg entities upsert` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Create or update an API-origin entity in a writable domain. This command uses the Knowledge Graph write API, which is gated server-side. If the write API is not enabled on your stack, the server returns an error explaining how to request access. Identity is (type, name, scope) + domain; re-running with the same identity updates the entity. Scope is optional but identity-significant. With -f, the input may be a single object or a YAML/JSON array. Array entries are processed in order as independent upserts: the operation is not atomic, and entries already written stay written if a later entry fails. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities upsert [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg entities upsert --domain myapp --type Service --name checkout --scope env=prod --ttl 1h gcx kg entities upsert -f entity.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --domain string Writable domain slug — a specific application domain such as 'irm' (required; 'kg' is reserved) -f, --file string Input file (YAML/JSON), or '-' for stdin; mutually exclusive with flags -h, --help help for upsert --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Entity name (required) -o, --output string Output format. One of: agents, json, table, yaml (default "json") --property stringToString Property as key=value (repeatable or comma-separated) (default []) --scope stringToString Scope as key=value (repeatable or comma-separated; identity-significant) (default []) --ttl string Time-to-live duration (e.g. 1h, 7d); omitted = never expire --type string Entity type (identifier; required) ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg insights` Fetch chart data and source metrics for an active insight. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for insights ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg insights chart` Get chart data (series + thresholds) for a specific insight on an entity. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg insights chart [Type--Name] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --env string Environment scope -f, --file string Input file (YAML) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for chart --insight string Insight name (e.g. LatencyAverageBreach, ResourceRateAnomaly) — sets the 'alertname' label --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --label stringArray Extra assertion label as key=value (repeatable; e.g. asserts_resource_type=jvm:live_threads to narrow ResourceRateAnomaly to a specific resource) --name string Entity name --namespace string Namespace scope -o, --output string Output format. One of: agents, json, yaml (default "json") --since string Duration before --to (or now); mutually exclusive with --from/--to (e.g. 1h, 30m, 7d) --site string Site scope --to string End time (RFC3339, Unix timestamp, or relative like 'now') --type string Entity type ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg insights sources` List the underlying metrics (name + label matchers) that source a specific insight. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg insights sources [Type--Name] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --env string Environment scope -f, --file string Input file (YAML) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for sources --insight string Insight name (e.g. LatencyAverageBreach, ResourceRateAnomaly) — sets the 'alertname' label --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --label stringArray Assertion label as key=value (repeatable; typically copied from 'kg entities inspect' timeLines[].labels) --name string Entity name --namespace string Namespace scope -o, --output string Output format. One of: agents, json, yaml (default "json") --since string Duration before --to (or now); mutually exclusive with --from/--to (e.g. 1h, 30m, 7d) --site string Site scope --to string End time (RFC3339, Unix timestamp, or relative like 'now') --type string Entity type ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg meta` Show Knowledge Graph metadata: entity types, valid env/namespace/site values, and telemetry query configs. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for meta ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg meta all` Load all sections: schema, scopes, logs, traces, profiles, and metrics. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg meta all [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for all --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --since string Duration before --to (or now); mutually exclusive with --from/--to (e.g. 1h, 30m, 7d) --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg meta logs` Show Loki label mappings for log drilldown. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg meta logs [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for logs --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg meta metrics` Show the asserts:* KPI metrics (Knowledge Graph recording rules) and the entity-property → Prometheus label mapping for querying them. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg meta metrics [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg meta profiles` Show Pyroscope label mappings for profile drilldown. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg meta profiles [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for profiles --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg meta schema` Show entity types, properties, and relationships. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg meta schema [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for schema --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --since string Duration before --to (or now); mutually exclusive with --from/--to (e.g. 1h, 30m, 7d) --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg meta scopes` Show all valid env/namespace/site filter values. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg meta scopes [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for scopes --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --since string Duration before --to (or now); mutually exclusive with --from/--to (e.g. 1h, 30m, 7d) --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg meta traces` Show Tempo label mappings for trace drilldown. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg meta traces [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for traces --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg model-rules` Manage model rules in the Knowledge Graph. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for model-rules ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg model-rules delete` Delete a custom model rules configuration by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg model-rules delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg model-rules get` Get a custom model rules configuration by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg model-rules get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg model-rules list` List all custom model rules configurations. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg model-rules list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg model-rules schema` Fetches the JSON Schema (Draft 2020-12) that describes the ModelRules configuration shape, derived from the backend DTO tree. Pipe to a file and point your editor at it for autocomplete and deep validation when authoring model rules manifests. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg model-rules schema [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for schema --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg model-rules upsert` Upload model rules from a YAML file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg model-rules upsert [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg model-rules upsert -f model-rules.yaml # Validate against the backend and preview the diff without uploading: gcx kg model-rules upsert -f model-rules.yaml --dry-run ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dry-run Validate against the backend and show a diff without uploading. -f, --file string Input file (YAML), or '-' for stdin. -h, --help help for upsert --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg notifications` Manage alert notification configs (AlertConfig) in the Knowledge Graph. These govern how matched alerts notify — the labels an alert must match, extra alert labels and annotations to attach, the “for” duration, and the silenced flag. Distinct from “gcx kg suppressions”, which manages disabled-alert configs. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for notifications ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg notifications delete` Delete an alert notification config by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg notifications delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg notifications get` Get an alert notification config by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg notifications get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg notifications list` List alert notification configs, optionally filtered by category. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg notifications list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --category string Filter by category: request, resource, health, or slo. -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg notifications upsert` Upsert (create or update) one or more alert notification configs from a YAML file or stdin. Applies the entries in the input file, creating each config when absent or updating it when present. Remote configs absent from the file are never deleted. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg notifications upsert [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg notifications upsert -f notifications.yaml echo 'alertConfigs: - name: api-server-latency matchLabels: asserts_slo_name: api-server-latency for: 5m silenced: false' | gcx kg notifications upsert ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --file string Input file (YAML), or '-' for stdin. Reads from stdin if omitted. -h, --help help for upsert --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg open` Open the Knowledge Graph app in the browser. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg open [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for open --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg prom-rules` Manage Knowledge Graph Custom Prometheus rules. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for prom-rules ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg prom-rules delete` Delete a Knowledge Graph Custom Prometheus rule by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg prom-rules delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg prom-rules get` Get a Knowledge Graph Custom Prometheus rule by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg prom-rules get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg prom-rules list` List Knowledge Graph Custom Prometheus rules. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg prom-rules list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg prom-rules schema` Fetches the JSON Schema (Draft 2020-12) that describes the Custom Prometheus rules configuration shape, derived from the backend DTO tree. Pipe to a file and point your editor at it for autocomplete and deep validation when authoring prom-rules manifests. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg prom-rules schema [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for schema --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg prom-rules upsert` Upload Knowledge Graph Custom Prometheus rules from a YAML file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg prom-rules upsert [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg prom-rules upsert -f rules.yaml # Validate against the backend and preview the diff without uploading: gcx kg prom-rules upsert -f rules.yaml --dry-run ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dry-run Validate against the backend and show a diff without uploading. -f, --file string Input file (YAML), or '-' for stdin. -h, --help help for upsert --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg quality` Inspect Knowledge Graph entity quality reports. Quality reports grade how well an entity is instrumented — each report is a set of checks (request metrics, service-map data, deployment environment, span cardinality, logs, profiles, …) with an overall quality percentage. Use ’list’ to rank entities by quality, and ‘get’ to see the failing checks and remediation links for one entity. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for quality ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg quality get` Get the full quality report for a single entity. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg quality get [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg quality get my-service --env gcx kg quality get my-service --env --namespace gcx kg quality get my-service --env --yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --env string Environment scope (required) -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --namespace string Namespace scope -o, --output string Output format. One of: agents, json, table, yaml (default "table") --site string Site scope --type string Entity type (default "Service") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg quality list` List entity quality reports, ranked by quality percent. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg quality list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg quality list --env gcx kg quality list --env --namespace --sort asc gcx kg quality list --env --failed-check span-metrics --failed-check service-graph-metrics gcx kg quality list --env --json entityName,qualityPercent,failedCheckIds ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --entity string Filter by entity name --env string Environment scope --failed-check stringArray Only report entities with these failed check IDs; repeatable -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --namespace string Namespace scope -o, --output string Output format. One of: agents, json, table, yaml (default "table") --page int Page number (0-based) --page-size int Page size (1-100) (default 25) --site string Site scope --sort string Sort by quality percent: asc (worst first) or desc (best first) (default "asc") --type string Entity type to filter by (default "Service") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg relabel-rules` Inspect Mimir relabel rules used by the Knowledge Graph. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for relabel-rules ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg relabel-rules get` Fetch a relabel rule group (prologue, epilogue, or generated). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg relabel-rules get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --type string Rule group to fetch: prologue, epilogue, or generated (default "generated") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg relationships` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Create, update, and delete API-origin edges between Knowledge Graph entities. **Aliases:** `relationship`, `rels` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for relationships ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg relationships delete` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Delete an API-origin edge of the given type between the from/to entities. The endpoint refs (incl. scope) must match the values used at upsert. This command uses the Knowledge Graph write API, which is gated server-side. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg relationships delete [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg relationships delete --type CALLS \ --from myapp/Service/checkout --to myapp/Service/cart --force ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt --from string Source entity ref as domain/Type/name (required) --from-scope stringToString Scope for --from as key=value (repeatable or comma-separated) (default []) -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --to string Target entity ref as domain/Type/name (required) --to-scope stringToString Scope for --to as key=value (repeatable or comma-separated) (default []) --type string Relationship type (identifier; required) ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg relationships upsert` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Create or update an API-origin edge between two existing entities. Both endpoints must already exist. This command uses the Knowledge Graph write API, which is gated server-side. With -f, the input may be a single object or a YAML/JSON array. Array entries are processed in order as independent upserts: the operation is not atomic, and entries already written stay written if a later entry fails. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg relationships upsert [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg relationships upsert --type CALLS --domain myapp \ --from myapp/Service/checkout --to myapp/Service/cart --to-scope env=prod --ttl 1h gcx kg relationships upsert -f rel.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --domain string Writable domain slug for the edge — a specific application domain such as 'irm' (required) -f, --file string Input file (YAML/JSON), or '-' for stdin; mutually exclusive with flags --from string Source entity ref as domain/Type/name (required) --from-scope stringToString Scope for --from as key=value (repeatable or comma-separated) (default []) -h, --help help for upsert --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "json") --property stringToString Property as key=value (repeatable or comma-separated) (default []) --to string Target entity ref as domain/Type/name (required) --to-scope stringToString Scope for --to as key=value (repeatable or comma-separated) (default []) --ttl string Time-to-live duration (e.g. 1h, 7d); omitted = never expire --type string Relationship type (identifier; required) ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg stats` Show entity and active-insight counts, broken down by type, severity, and insight name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg stats [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --env string Environment scope --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for stats --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --namespace string Namespace scope -o, --output string Output format. One of: agents, json, yaml (default "json") --since string Duration before --to (or now); mutually exclusive with --from/--to (e.g. 1h, 30m, 7d) --site string Site scope --to string End time (RFC3339, Unix timestamp, or relative like 'now') --type string Limit to a specific entity type ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg status` Show Knowledge Graph stack status. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg status [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for status --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg suppressions` Manage alert suppressions in the Knowledge Graph. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for suppressions ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg suppressions delete` Delete a suppression by name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg suppressions delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg suppressions list` List all alert suppressions. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg suppressions list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx kg suppressions upsert` Upsert (create or update) one or more suppressions from a YAML file or stdin. Applies the entries in the input file, creating each suppression when absent or updating it when present. Remote suppressions absent from the file are never deleted. Use –dry-run to validate against the backend and preview the diff, scoped to the entries in the input file, without uploading. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg suppressions upsert [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx kg suppressions upsert -f suppressions.yaml # Validate against the backend and preview the diff without uploading: gcx kg suppressions upsert -f suppressions.yaml --dry-run echo 'disabledAlertConfigs: - name: my-suppression matchLabels: alertname: ErrorRatioBreach job: my-service' | gcx kg suppressions upsert ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dry-run Validate against the backend and show a diff without uploading. -f, --file string Input file (YAML), or '-' for stdin. Reads from stdin if omitted. -h, --help help for upsert --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx kg`](#gcx-kg-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx login` Authenticate to a Grafana instance (Cloud or on-premises) and save the credentials to the selected config context. Pass CONTEXT\_NAME to target a specific context: - If the context exists, re-authenticate it (server and other fields preserved). - If it does not exist, create a new context with that name. Without CONTEXT\_NAME, re-authenticates the current context, or starts a first-time setup if no current context is configured. Auth sources (for non-interactive use): –oauth Browser-based OAuth (recommended for Grafana Cloud). Opens a browser for the user to approve; works in agent mode. –basic-auth Grafana username/password. Use –user or GRAFANA\_USER, and GRAFANA\_PASSWORD. –token Grafana service-account token (created inside the Grafana instance). See: [https://grafana.com/docs/grafana/latest/administration/service-accounts.md](/docs/grafana/latest/administration/service-accounts.md) –cloud-token Grafana Cloud access-policy token (created at grafana.com). See: [https://grafana.com/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-policies/create-access-policies.md](/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-policies/create-access-policies.md) shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx login [CONTEXT_NAME] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx login gcx login prod gcx login prod --server https://prod.grafana.net gcx login prod --server https://prod.grafana.net --oauth gcx login local --server https://grafana.example.com --basic-auth --user admin gcx login --yes prod --token glsa_xxx gcx login --yes --server https://localhost:3000 --token glsa_xxx ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --allow-server-override Allow re-pointing an existing context at a different server URL --basic-auth Authenticate with a Grafana username and password (GRAFANA_USER / GRAFANA_PASSWORD, or interactive prompts) --cloud Force Grafana Cloud target (skip auto-detection) --cloud-api-url string Override Grafana Cloud API URL --cloud-token string Grafana Cloud API token (enables Cloud management features) --config string Path to the configuration file to use --context string Name of the context to use -h, --help help for login --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --oauth Authenticate via browser-based OAuth (recommended for Grafana Cloud). Works non-interactively and in agent mode: opens a browser for the user to approve. --oauth-callback-port int Fixed local port for the OAuth callback server (default: auto-pick from 54321-54399). Useful when only specific ports are forwarded between a remote host and your browser --oauth-manual Complete browser OAuth without a local callback server: gcx prints the URL, then reads the redirect URL that you copy from the browser address bar. Use this when gcx runs on a remote host and the browser runs on your own computer. Implies --oauth --org-id int Grafana organization ID (defaults to 1 for on-prem) -o, --output string Output format. One of: agents, json, text, yaml (default "text") --server string Grafana server URL (e.g. https://my-stack.grafana.net) --token string Grafana service account token --user string Grafana username for --basic-auth (defaults to GRAFANA_USER) --yes Non-interactive: skip optional prompts and use defaults ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs` Query Loki datasources and manage Adaptive Logs **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for logs ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive` Manage Adaptive Logs resources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for adaptive ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive drop-rules` Manage adaptive log drop rules. Use `list` or `get` to read rules. `list` applies the **global** segment filter (same scope as create/update/delete). `gcx resources get droprules` lists all tenant rules without that filter when the resources command is available. Create and update load a rule from a file (`--filename` / `-f`). The file’s top-level “version” is the rule schema version (only 1); omit or set it to 1 — not the revision field in API JSON. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for drop-rules ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive drop-rules create` Create an adaptive log drop rule from a file. The file’s top-level “version” is the rule schema version (only 1 is supported). Omit it or set it to 1; do not confuse it with the rule revision in API responses. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive drop-rules create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the drop rule definition (use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive drop-rules delete` Delete an adaptive log drop rule. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive drop-rules delete ID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive drop-rules get` Fetch one adaptive log drop rule by ID. For the **global** segment scope, use `list` to enumerate rules first. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive drop-rules get ID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive drop-rules list` List adaptive log drop rules. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive drop-rules list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --expiration-filter string Filter by expiration: all, active, or expired (default "all") -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of drop rules to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive drop-rules update` Update an adaptive log drop rule by ID. The file’s top-level “version” is the rule schema version (only 1 is supported). Omit it or set it to 1; do not confuse it with the rule revision in API responses. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive drop-rules update ID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the drop rule definition (use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive exemptions` Manage adaptive log exemptions. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for exemptions ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive exemptions create` Create an adaptive log exemption. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive exemptions create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") --reason string Reason for the exemption --stream-selector string Log stream selector (required) ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive exemptions delete` Delete an adaptive log exemption. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive exemptions delete ID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive exemptions list` List adaptive log exemptions. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive exemptions list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of exemptions to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive exemptions update` Update an adaptive log exemption. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive exemptions update ID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") --reason string Reason for the exemption --stream-selector string Log stream selector ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive patterns` Manage adaptive log patterns. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for patterns ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive patterns list` List adaptive log pattern recommendations. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive patterns list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --segment string Only include patterns for this segment (ID column from patterns stats, or API map key / selector) --top int Table only: show top N patterns by volume; 0 shows all rows with no rollup (default 10) ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive patterns stats` Summarize pattern volume aggregated by segment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive patterns stats [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for stats --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive segments` Manage adaptive log segments. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for segments ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive segments create` Create an adaptive log segment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive segments create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --fallback-to-default Fall back to default segment -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Segment name (required) -o, --output string Output format. One of: agents, json, yaml (default "json") --selector string Log stream selector (required) ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive segments delete` Delete an adaptive log segment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive segments delete ID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive segments list` List adaptive log segments. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive segments list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of segments to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs adaptive segments update` Update an adaptive log segment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs adaptive segments update ID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --fallback-to-default Fall back to default segment -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Segment name -o, --output string Output format. One of: agents, json, yaml (default "json") --selector string Log stream selector ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs labels` List all labels or get values for a specific label from a Loki datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all labels (use datasource UID, not name) gcx logs labels -d UID # Get values for a specific label gcx logs labels -d UID --label job # Output as JSON gcx logs labels -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.loki is configured) -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label string Get values for this label (omit to list all labels) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs metrics` Execute a metric LogQL query and return time-series results. EXPR is a metric LogQL expression (e.g., rate, count\_over\_time, sum). Datasource is resolved from -d flag or datasources.loki in your context. Unlike ’logs query’ which returns log lines, ’logs metrics’ returns time-series data with proper table, graph, and JSON formatters. Instant vs range is deduced from time flags: no time flags = instant query, –since or –from/–to = range query. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs metrics [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Run a metric query over logs gcx logs metrics -d UID 'rate({job="grafana"}[5m])' --since 1h # Print a Grafana Explore share link for the query gcx logs metrics 'rate({job="grafana"}[5m])' --share-link # Output as JSON gcx logs metrics -d UID 'rate({job="grafana"}[5m])' --since 1h -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.loki is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs query` Execute a LogQL query against a Loki datasource. EXPR is the LogQL expression to evaluate. Datasource is resolved from -d flag or datasources.loki in your context. Default table output is optimized for humans. Use -o raw for original line bodies or -o json for the full structured response. Default –limit is 50; use –limit 0 for no cap. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Query logs using configured default datasource gcx logs query '{job="varlogs"}' # Query with explicit datasource UID gcx logs query -d abc123 '{job="varlogs"} |= "error"' # Print a Grafana Explore share link for the query gcx logs query '{job="varlogs"}' --share-link # Raw line bodies only gcx logs query -d abc123 '{job="varlogs"}' -o raw # Output as JSON gcx logs query -d abc123 '{job="varlogs"}' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.loki is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of log lines to return (0 means no limit) (default 50) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, raw, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx logs series` List log streams (series) from a Loki datasource using LogQL stream selectors. At least one –match selector is required. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx logs series [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List series matching a selector (use datasource UID, not name) gcx logs series -d UID --match '{job="varlogs"}' # Multiple matchers (OR logic) gcx logs series -d UID --match '{job="varlogs"}' --match '{namespace="default"}' # Output as JSON gcx logs series -d UID --match '{job="varlogs"}' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.loki is configured) -h, --help help for series --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -M, --match stringArray LogQL stream selector (required, e.g., '{job="varlogs"}') -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx logs`](#gcx-logs-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics` Query Prometheus datasources and manage Adaptive Metrics **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for metrics ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive` Manage Adaptive Metrics resources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for adaptive ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive exemptions` Manage Adaptive Metrics recommendation exemptions. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for exemptions ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive exemptions create` Create a recommendation exemption. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive exemptions create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --active-interval string Active interval (e.g. 30d, 1h) (default "30d") --disable-recommendations Disable all recommendations for matched metrics -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --keep-labels strings Labels to keep (comma-separated) --managed-by string Manager identifier --match-type string Match type: exact, prefix, or suffix (default "exact") --metric string Metric name or pattern -o, --output string Output format. One of: agents, json, yaml (default "json") --reason string Reason for the exemption --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive exemptions delete` Delete a recommendation exemption. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive exemptions delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive exemptions get` Get a recommendation exemption by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive exemptions get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "json") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive exemptions list` List Adaptive Metrics recommendation exemptions. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive exemptions list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all-segments List exemptions across all segments -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of exemptions to return (0 for no limit) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive exemptions update` Update a recommendation exemption. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive exemptions update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --active-interval string Active interval (e.g. 30d, 1h) --disable-recommendations Disable all recommendations for matched metrics -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --keep-labels strings Labels to keep (comma-separated) --managed-by string Manager identifier --match-type string Match type: exact, prefix, or suffix --metric string Metric name or pattern -o, --output string Output format. One of: agents, json, yaml (default "json") --reason string Reason for the exemption --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive recommendations` Manage metric recommendations. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for recommendations ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive recommendations apply` Apply specific or all recommendations as rules. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive recommendations apply [...|--all] [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --all Apply all recommendations (bulk) --dry-run Preview without applying --force Skip confirmation prompt -h, --help help for apply --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive recommendations diff` Show what applying recommendation(s) would change. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive recommendations diff ... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for diff --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive recommendations list` List metric recommendations. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive recommendations list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --action stringArray Filter by action: add, update, remove, keep (repeatable) -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --reverse Reverse the default sort order --segment string Segment ID --sort string Sort by: metric, savings, series-before, series-after, action (default "metric") --top int Limit to top N results (0 = all) ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive rules` Manage aggregation rules. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for rules ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive rules create` Create an aggregation rule. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive rules create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --aggregation-delay string Aggregation delay (e.g. 5m) --aggregation-interval string Aggregation interval (e.g. 1m) --aggregations strings Aggregation types: sum, count, min, max, sum:counter (comma-separated) --drop Drop the metric entirely --drop-labels strings Labels to drop (comma-separated) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --keep-labels strings Labels to keep (comma-separated) --match-type string Match type: exact, prefix, or suffix (default "exact") --metric string Metric name (required) -o, --output string Output format. One of: agents, json, yaml (default "json") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive rules delete` Delete an aggregation rule. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive rules delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive rules get` Get an aggregation rule by metric name. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive rules get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive rules list` List aggregation rules. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive rules list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of rules to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive rules update` Update an aggregation rule. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive rules update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --aggregation-delay string Aggregation delay (e.g. 5m) --aggregation-interval string Aggregation interval (e.g. 1m) --aggregations strings Aggregation types: sum, count, min, max, sum:counter (comma-separated) --drop Drop the metric entirely --drop-labels strings Labels to drop (comma-separated) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --keep-labels strings Labels to keep (comma-separated) --match-type string Match type: exact, prefix, or suffix -o, --output string Output format. One of: agents, json, yaml (default "json") --segment string Segment ID ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive segments` Manage Adaptive Metrics segments. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for segments ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive segments create` Create an Adaptive Metrics segment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive segments create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --auto-apply Automatically apply recommendations --fallback-to-default Fall back to default segment when no rules match -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Segment name (required) -o, --output string Output format. One of: agents, json, yaml (default "json") --selector string PromQL label selector (required) ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive segments delete` Delete an Adaptive Metrics segment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive segments delete [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive segments get` Get an Adaptive Metrics segment by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive segments get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "json") ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive segments list` List Adaptive Metrics segments. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive segments list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of segments to return (0 for no limit) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics adaptive segments update` Update an Adaptive Metrics segment. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics adaptive segments update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --auto-apply Automatically apply recommendations --fallback-to-default Fall back to default segment when no rules match -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --name string Segment name -o, --output string Output format. One of: agents, json, yaml (default "json") --selector string PromQL label selector ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics billing` Query Grafana Cloud billing metrics via the grafanacloud-usage datasource that ships pre-provisioned on every Grafana Cloud stack. These commands are thin conveniences over the generic metrics subcommands; the –datasource flag defaults to “grafanacloud-usage” but can be overridden. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for billing ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics billing labels` List all labels or get values for a specific label from a Prometheus datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics billing labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # All billing label names gcx metrics billing labels # Values for a single label gcx metrics billing labels --label product # Output as JSON gcx metrics billing labels -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label string Get values for this label (omit to list all labels) --match stringArray Series selector(s) to scope results; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) --metric string Only results from series of this metric (narrows every --match selector) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics billing query` Execute a PromQL query against a Prometheus datasource. EXPR is the PromQL expression to evaluate, passed as a positional argument or via –expr (familiar to promtool users). Datasource is resolved from -d flag or datasources.prometheus in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics billing query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Active series right now gcx metrics billing query 'grafanacloud_instance_active_series' # Active series over the last hour gcx metrics billing query 'grafanacloud_instance_active_series' --since 1h --step 1m # Print a Grafana Explore share link for the executed query gcx metrics billing query 'grafanacloud_instance_active_series' --share-link # Output as JSON gcx metrics billing query 'grafanacloud_instance_active_series' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --time string Evaluation time for an instant query (RFC3339, Unix timestamp, or relative like 'now-5m'). Mutually exclusive with --from/--to/--since --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics billing series` List time series matching one or more selectors via the Prometheus /api/v1/series endpoint. A selector can be passed as a positional argument and/or via –match (repeatable). Time range defaults to unbounded; pass –since, or –from/–to, to scope. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics billing series [SELECTOR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # All billing series gcx metrics billing series '{__name__=~"grafanacloud_.*"}' --since 1h # Filter to a specific product gcx metrics billing series '{__name__=~"grafanacloud_.*",product="metrics"}' --since 1h # Output as JSON gcx metrics billing series '{__name__=~"grafanacloud_.*"}' --since 1h -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for series --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --match stringArray Additional series selector(s); repeatable -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics cardinality` Analyze series cardinality by label names and values via the Mimir cardinality analysis API. These endpoints are available on Grafana Mimir (OSS) and Grafana Cloud; on self-hosted Mimir they require -querier.cardinality-analysis-enabled. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for cardinality ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics cardinality label-names` Show, for each label name, how many distinct values it has, via the Mimir cardinality analysis API. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics cardinality label-names [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Top label names by distinct value count (configured default datasource) gcx metrics cardinality label-names # Scope to a metric family and use active-series counting gcx metrics cardinality label-names -d UID --selector '{__name__=~"grafanacloud_.*"}' --count-method active # Output as JSON gcx metrics cardinality label-names -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --count-method string Series counting method: "inmemory" or "active" (default "inmemory") -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) -h, --help help for label-names --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0-500) (default 20) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --selector string PromQL series selector scoping the analysis ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics cardinality label-values` Show, for each requested label name, its distinct values and the number of series per value, via the Mimir cardinality analysis API. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics cardinality label-values [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Per-value series counts for one label gcx metrics cardinality label-values -d UID --label job # Multiple labels, capped and as JSON gcx metrics cardinality label-values -d UID --label job --label instance --limit 50 -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --count-method string Series counting method: "inmemory" or "active" (default "inmemory") -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) -h, --help help for label-values --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label stringArray Label name to analyze; repeatable (required) --limit int Maximum number of items to return per label (0-500) (default 20) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --selector string PromQL series selector scoping the analysis ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics labels` List all labels or get values for a specific label from a Prometheus datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all labels (use datasource UID, not name) gcx metrics labels -d UID # Get values for a specific label gcx metrics labels -d UID --label job # List labels present on a metric gcx metrics labels -d UID --metric http_requests_total # Get values a label takes on a metric gcx metrics labels -d UID --metric http_requests_total --label job # Scope with an arbitrary series selector gcx metrics labels -d UID --match '{job="api"}' # Output as JSON gcx metrics labels -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label string Get values for this label (omit to list all labels) --match stringArray Series selector(s) to scope results; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) --metric string Only results from series of this metric (narrows every --match selector) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics list-names` List metric names from a Prometheus datasource via the label values endpoint for `__name__`. Scope the server-side lookup with –match selectors; filter names client-side with –prefix, –suffix, and –contains, which combine with AND. Output is capped at 100 names by default; pass –limit 0 for the full list. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics list-names [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List metric names (first 100 by default; use datasource UID, not name) gcx metrics list-names -d UID # Find cart-related metrics gcx metrics list-names -d UID --contains cart # Counters only gcx metrics list-names -d UID --suffix _total # Metrics present on a job gcx metrics list-names -d UID --match '{job="api"}' # Output as JSON gcx metrics list-names -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --contains string Only include names containing this string (case-sensitive) -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) -h, --help help for list-names --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of metric names to return. 0 means all results are returned (default 100) --match stringArray Series selector(s) to scope results; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --prefix string Only include names starting with this string (case-sensitive) --suffix string Only include names ending with this string (case-sensitive) ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics metadata` Get metadata (type, help text) for metrics from a Prometheus datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics metadata [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Get all metric metadata (use datasource UID, not name) gcx metrics metadata -d UID # Get metadata for a specific metric gcx metrics metadata -d UID --metric http_requests_total # Output as JSON gcx metrics metadata -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) -h, --help help for metadata --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -m, --metric string Filter by metric name -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics query` Execute a PromQL query against a Prometheus datasource. EXPR is the PromQL expression to evaluate, passed as a positional argument or via –expr (familiar to promtool users). Datasource is resolved from -d flag or datasources.prometheus in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Instant query using configured default datasource gcx metrics query 'up{job="grafana"}' # Instant query at a specific time gcx metrics query 'rate(http_requests_total[5m])' --time 2026-01-15T10:30:00Z # Range query with explicit datasource UID gcx metrics query -d abc123 'rate(http_requests_total[5m])' --from now-1h --to now --step 1m # Query the last hour gcx metrics query 'up' --since 1h # Print a Grafana Explore share link for the executed query gcx metrics query 'up' --share-link # Output as JSON gcx metrics query -d abc123 'up' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --time string Evaluation time for an instant query (RFC3339, Unix timestamp, or relative like 'now-5m'). Mutually exclusive with --from/--to/--since --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics search` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Search for metric names, label names or label values via the experimental search API. This API is experimental and disabled by default on both self-hosted Prometheus (requires –enable-feature=search-api) and self-hosted Mimir (requires -querier.experimental-search-api-enabled). **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for search ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics search label-names` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Search label names from a Prometheus/Mimir datasource. Requires TERM (performs a fuzzy search; multiple TERM values combine as OR), or a scope instead: –metric, –metric-regex or –match. sort\_by=score (the default) requires a search term — omitting TERM in favor of a scope falls back to sort\_by=alpha, and an explicit –sort-by=score without TERM is rejected. –metric-regex is used exactly as given — PromQL anchors =~ at ^…$, so “kube” matches only a metric literally named “kube”, not one containing it. Write “.*kube.*” for a contains search. Without –from/–to or –since, the server searches only the last hour; use –since (for example –since 7d) to look further back. This API is experimental and disabled by default on both self-hosted Prometheus (requires –enable-feature=search-api) and self-hosted Mimir (requires -querier.experimental-search-api-enabled). See also the sibling metric-name search and label-value search commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics search label-names [TERM...] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Fuzzy search label names (configured default datasource) gcx metrics search label-names job # Show label names available on a given metric gcx metrics search label-names --metric http_requests_total # Show label names on series matching a selector gcx metrics search label-names --match '{job="api"}' # Search for label names on a given metric gcx metrics search label-names namespace --metric http_requests_total # Search for label names across a range of metrics gcx metrics search label-names namespace --metric-regex '.*kube.*' # Search label names seen in the last 7 days (default: the last hour) gcx metrics search label-names job --since 7d # Output as JSON gcx metrics search label-names job -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --case-sensitive Case-sensitive search term matching (case-insensitive by default) -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --fuzz-alg string Fuzzy match algorithm: jarowinkler or subsequence (default "jarowinkler") --fuzz-threshold int Minimum fuzzy match score as a percentage, 0-100; scores are reported from 0 to 1. With jarowinkler the threshold applies only to fuzzy matches: substring matches are always kept, and 0 turns fuzzy matching off (default 70) -h, --help help for label-names --include-score Include each result's relevance score (0 to 1; higher is a closer match) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum results to return (0: unlimited on Mimir, subject to server-side caps; Prometheus requires a positive value) (default 50) --match stringArray PromQL series selector(s) restricting candidates; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) --metric string Only results from series of this metric name; mutually exclusive with --metric-regex --metric-regex string Only results from series whose metric name matches this regex. Used exactly as given. To match all metric names which contain "kube" use ".*kube.*". Mutually exclusive with --metric. -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --sort-by string Sort by: score (requires a search term) or alpha (default "score") --sort-dir string Sort direction for --sort-by alpha: asc (default) or dsc --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics search label-values` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Search the values of a single label from a Prometheus/Mimir datasource. LABEL is always required; TERM (multiple values combine as OR), –metric, –metric-regex and –match are all optional and may be combined or omitted — LABEL alone lists that label’s values. sort\_by=score (the default) requires a search term — omitting TERM falls back to sort\_by=alpha, and an explicit –sort-by=score without TERM is rejected. –metric-regex is used exactly as given — PromQL anchors =~ at ^…$, so “kube” matches only a metric literally named “kube”, not one containing it. Write “.*kube.*” for a contains search. Without –from/–to or –since, the server searches only the last hour; use –since (for example –since 7d) to look further back. This API is experimental and disabled by default on both self-hosted Prometheus (requires –enable-feature=search-api) and self-hosted Mimir (requires -querier.experimental-search-api-enabled). See also the sibling metric-name search and label-name search commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics search label-values LABEL [TERM...] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List values of the "job" label (configured default datasource) gcx metrics search label-values job # Fuzzy search values of the "job" label gcx metrics search label-values job pro # List "job" label values present on a specific metric gcx metrics search label-values job --metric http_requests_total # List "job" label values present on a range of metrics gcx metrics search label-values job --metric-regex '.*kube.*' # List "job" label values seen in the last 7 days (default: the last hour) gcx metrics search label-values job --since 7d # Output as JSON gcx metrics search label-values job pro -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --case-sensitive Case-sensitive search term matching (case-insensitive by default) -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --fuzz-alg string Fuzzy match algorithm: jarowinkler or subsequence (default "jarowinkler") --fuzz-threshold int Minimum fuzzy match score as a percentage, 0-100; scores are reported from 0 to 1. With jarowinkler the threshold applies only to fuzzy matches: substring matches are always kept, and 0 turns fuzzy matching off (default 70) -h, --help help for label-values --include-score Include each result's relevance score (0 to 1; higher is a closer match) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum results to return (0: unlimited on Mimir, subject to server-side caps; Prometheus requires a positive value) (default 50) --match stringArray PromQL series selector(s) restricting candidates; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) --metric string Only results from series of this metric name; mutually exclusive with --metric-regex --metric-regex string Only results from series whose metric name matches this regex. Used exactly as given. To match all metric names which contain "kube" use ".*kube.*". Mutually exclusive with --metric. -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --sort-by string Sort by: score (requires a search term) or alpha (default "score") --sort-dir string Sort direction for --sort-by alpha: asc (default) or dsc --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics search metric-names` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Search metric names from a Prometheus/Mimir datasource. At least one TERM is required. This API allows for metric names to be discovered via a configurable fuzzy search. Multiple TERM values combine as OR. Search terms can be augmented with matchers for additional filtering of considered series. Without –from/–to or –since, the server searches only the last hour; use –since (for example –since 7d) to look further back. This API is experimental and disabled by default on both self-hosted Prometheus (requires –enable-feature=search-api) and self-hosted Mimir (requires -querier.experimental-search-api-enabled). See also the sibling label-name search and label-value search commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics search metric-names TERM... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Fuzzy search metric names (configured default datasource) gcx metrics search metric-names http # Search metric names seen in the last 7 days (default: the last hour) gcx metrics search metric-names http --since 7d # Refine fuzzy search algorithm gcx metrics search metric-names http --fuzz-alg=subsequence --fuzz-threshold=85 # Limit result sets and control ordering gcx metrics search metric-names http --limit=10 --sort-by=alpha # Include relevance score and metric metadata gcx metrics search metric-names http --include-score --include-metadata # Output as JSON gcx metrics search metric-names http -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --case-sensitive Case-sensitive search term matching (case-insensitive by default) -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --fuzz-alg string Fuzzy match algorithm: jarowinkler or subsequence (default "jarowinkler") --fuzz-threshold int Minimum fuzzy match score as a percentage, 0-100; scores are reported from 0 to 1. With jarowinkler the threshold applies only to fuzzy matches: substring matches are always kept, and 0 turns fuzzy matching off (default 70) -h, --help help for metric-names --include-metadata Include each result's metric type, help text, and unit (when available) --include-score Include each result's relevance score (0 to 1; higher is a closer match) --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum results to return (0: unlimited on Mimir, subject to server-side caps; Prometheus requires a positive value) (default 50) --match stringArray PromQL series selector(s) restricting candidates; repeatable (repeated selectors combine as a union, per the Prometheus match[] API) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --sort-by string Sort by: score (requires a search term) or alpha (default "score") --sort-dir string Sort direction for --sort-by alpha: asc (default) or dsc --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx metrics series` List time series matching one or more selectors via the Prometheus /api/v1/series endpoint. A selector can be passed as a positional argument and/or via –match (repeatable). Time range defaults to unbounded; pass –since, or –from/–to, to scope. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx metrics series [SELECTOR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Match a single metric family gcx metrics series -d '{__name__="up"}' # Match multiple selectors scoped to the last hour gcx metrics series -d --match '{job="grafana"}' --match '{job="loki"}' --since 1h # Output as JSON gcx metrics series -d '{__name__=~"grafanacloud_.*"}' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.prometheus is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for series --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --match stringArray Additional series selector(s); repeatable -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx metrics`](#gcx-metrics-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles` Query Pyroscope datasources and manage continuous profiling **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for profiles ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles adaptive` Manage Adaptive Profiles (not yet available) shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles adaptive [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for adaptive ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles data-range` Show the range of profiling data a Pyroscope datasource holds: whether any data was ever ingested, and the oldest and newest profile times. The range covers everything behind the datasource (the whole tenant), not any particular service or label selector. Use this to disambiguate empty query results: if no data was ever ingested, fix ingestion before adjusting selectors; otherwise the oldest/newest bounds show the currently queryable window. Note that data-ingested is a lifetime flag: it stays true even after all data has aged out of the retention period (31 days by default, tenant-configurable), in which case the bounds render as ‘-’ (0 in JSON). Older backends may also report an unknown oldest bound the same way. If gcx auto-discovers the datasource from your Grafana Cloud stack, the discovered datasource UID may be saved to your gcx configuration for future commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles data-range [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Check whether the datasource holds profiling data, and for what range gcx profiles data-range -d UID # Output as JSON (times are milliseconds since epoch) gcx profiles data-range -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) -h, --help help for data-range --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles exemplars` Query profile or span exemplars from a Pyroscope datasource. Exemplars link profile data to concrete samples or trace spans, enabling a pivot from “which service was slow” to “which exact profile” (profile exemplars) or “which trace span” (span exemplars). **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Top individual profile exemplars (Profile ID + Span ID if span-aware) gcx profiles exemplars profile '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # Top span exemplars (profiles linked to trace spans; needs otelpyroscope) gcx profiles exemplars span '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # Output as JSON for scripting gcx profiles exemplars profile '{}' --since 30m -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for exemplars ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles exemplars profile` List individual profile exemplars by calling SelectSeries with EXEMPLAR\_TYPE\_INDIVIDUAL. Each row is a concrete profile sample identified by Profile ID. When profiles are span-aware (e.g. via otelpyroscope), a Span ID column is included linking to the associated trace span. EXPR is the label selector (e.g. ‘{service\_name=“frontend”}’). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles exemplars profile [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Top profile exemplars in the last hour gcx datasources pyroscope exemplars profile '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # JSON output gcx datasources pyroscope exemplars profile '{}' --since 30m -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --expr string Label selector (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for profile --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-label-columns int Max label columns in table output (0 hides label columns) (default 3) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --profile-type string Profile type ID (default "process_cpu:cpu:nanoseconds:cpu:nanoseconds") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') --top-n int Maximum number of exemplars to return (default 100) ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles exemplars span` List span exemplars by calling SelectHeatmap with HEATMAP\_QUERY\_TYPE\_SPAN. Each row is a span-linked profile sample identified by Span ID. When supplied by the server, Trace ID is also included for direct correlation with Tempo. Requires span-aware instrumentation upstream (e.g. otelpyroscope); without it the query returns an empty list. EXPR is the label selector (e.g. ‘{service\_name=“frontend”}’). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles exemplars span [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Top span exemplars in the last hour gcx datasources pyroscope exemplars span '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # JSON output, more label context gcx datasources pyroscope exemplars span '{}' --since 30m --max-label-columns 5 -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --expr string Label selector (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for span --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-label-columns int Max label columns in table output (0 hides label columns) (default 3) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --profile-type string Profile type ID (default "process_cpu:cpu:nanoseconds:cpu:nanoseconds") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') --top-n int Maximum number of exemplars to return (default 100) ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles labels` List all labels or get values for a specific label from a Pyroscope datasource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all labels (use datasource UID, not name) gcx profiles labels -d UID # Get values for a specific label gcx profiles labels -d UID --label service_name # Output as JSON gcx profiles labels -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label string Get values for this label (omit to list all labels) -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles list-profile-types` List available profile types from a Pyroscope datasource. If gcx auto-discovers the datasource from your Grafana Cloud stack, the discovered datasource UID may be saved to your gcx configuration for future commands. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles list-profile-types [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List profile types (use datasource UID, not name) gcx profiles list-profile-types -d UID # Output as JSON gcx profiles list-profile-types -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for list-profile-types --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles metrics` Query profile time-series data via SelectSeries from a Pyroscope datasource. Shows how a profile metric (e.g., CPU, memory) changes over time. Useful for identifying performance regressions and trends before diving into flamegraphs. Use –top to aggregate the time range into a ranked leaderboard of the heaviest consumers (equivalent to profilecli query top). Without –top, returns raw time-series data points for trend analysis. EXPR is the label selector (e.g., ‘{service\_name=“frontend”}’). Datasource is resolved from -d flag or datasources.pyroscope in your context. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles metrics [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Top services by CPU usage (ranked leaderboard) gcx profiles metrics '{}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h --top # CPU usage over the last hour with 1-minute resolution gcx profiles metrics -d pyro-001 '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h --step 1m # Output as JSON gcx profiles metrics -d abc123 '{}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h --top -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --aggregation string Aggregation type: 'sum' or 'average' -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') --group-by strings Group series by label (repeatable, defaults to service_name) -h, --help help for metrics --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of series to return (default 10) -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --profile-type string Profile type ID (e.g., 'process_cpu:cpu:nanoseconds:cpu:nanoseconds') (required) --since string Duration before --to (or now if omitted); mutually exclusive with --from --step string Query step (e.g., '15s', '1m'); defaults to the Pyroscope datasource minStep (or 15s) when omitted --to string End time (RFC3339, Unix timestamp, or relative like 'now') --top Aggregate into a ranked leaderboard (equivalent to profilecli query top) ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles query` Execute a profiling query against a Pyroscope datasource. EXPR is the label selector (e.g., ‘{service\_name=“frontend”}’). Datasource is resolved from -d flag or datasources.pyroscope in your context. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles query [EXPR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Profile query with explicit datasource UID gcx profiles query -d abc123 '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # Using configured default datasource gcx profiles query '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h # Output as JSON gcx profiles query -d abc123 '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds -o json # Drill into one or more specific profiles found via 'gcx profiles exemplars' # (--profile-id is repeatable; pass it once per UUID) gcx profiles query '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h \ --profile-id 550e8400-e29b-41d4-a716-446655440000 \ --profile-id 7c9e6679-7425-40de-944b-e07fc1f90ae7 # Restrict the query to one or more trace spans gcx profiles query '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h \ --span-id 00f067aa0ba902b7 # Restrict the query to samples from one or more traces gcx profiles query '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h \ --trace-id 4bf92f3577b34da6a3ce929d0e0e4736 # Restrict the flamegraph to stacks rooted at a specific call site # (--stacktrace-selector is repeatable; pass it once per frame, root first) gcx profiles query '{service_name="my-go-service"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h \ --stacktrace-selector 'github.com/prometheus/client_golang/prometheus.(*Registry).Gather.func1' # Caller-callee call graph as Graphviz DOT text — the most readable format # for LLM analysis (requires a pure-v2 backend; others fall back to table). # Dotted edges mean frames were elided by the 100-node default; raise # --max-nodes for fuller call chains gcx profiles query '{service_name="frontend"}' \ --profile-type process_cpu:cpu:nanoseconds:cpu:nanoseconds --since 1h -o dot ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-nodes int Maximum nodes in the result (defaults: pprof 0/unlimited, dot 100-node call graph rendered server-side, 50000 for all other formats) -o, --output string Output format. One of: agents, dot, graph, json, pprof, table, wide, yaml (default "table") --pprof-overwrite Overwrite the output file if it already exists (only with -o pprof) --pprof-path string Destination path for pprof binary output (only with -o pprof; default: profile-YYYY-MM-DD-HHMMSS.pb.gz) --profile-id strings Drill down to specific profile UUIDs from exemplar queries (repeatable) --profile-type string Profile type ID (e.g., 'process_cpu:cpu:nanoseconds:cpu:nanoseconds'); use 'gcx profiles list-profile-types' to list available (required) --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --span-id strings Only query profiles with these 16-character hex span IDs (repeatable; unavailable with -o pprof and -o dot) --stacktrace-selector strings Only query locations with these function names, starting from the root (repeatable) --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') --trace-id strings Only query samples with these 32-character hex trace IDs (repeatable) ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx profiles series` List unique profile label sets from a Pyroscope datasource. The command uses Pyroscope’s Series endpoint and does not require a profile type. SELECTOR is optional; use –match for repeatable selectors. Multiple selectors are combined as a union. By default, the response includes every label. Use –label-name to request only the labels needed for discovery. This reduces the response size and can significantly speed up queries with high-cardinality labels. For example, use –label-name service\_name –label-name namespace to discover services and namespaces without fetching pod, instance, or custom labels. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx profiles series [SELECTOR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List unique profile label sets without a profile type gcx profiles series -d UID --since 1h # Scope to a service and return selected labels gcx profiles series -d UID '{service_name="frontend"}' \ --label-name service_name --label-name namespace --label-name pod --since 24h ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.pyroscope is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for series --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --label-name strings Label name to return (repeatable; limit labels to reduce response size and speed up discovery) --match stringArray Profile label selector (repeatable; selectors are combined as a union) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx profiles`](#gcx-profiles-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx providers` Manage registered providers **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for providers ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx providers list` List registered providers shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx providers list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx resources` Manipulate Grafana resources. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for resources ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use --context string Name of the context to use ``` Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx resources delete` Delete resources from Grafana by selector or from local files. Use –dry-run to preview changes. Named selectors delete without confirmation. Use –force to delete all resources of a given type (–yes also enables –force). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources delete [RESOURCE_SELECTOR]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Delete a single dashboard gcx resources delete dashboards/some-dashboard # Delete multiple dashboards gcx resources delete dashboards/some-dashboard,other-dashboard # Delete a dashboard and a folder gcx resources delete dashboards/some-dashboard folders/some-folder # Delete every dashboard gcx resources delete dashboards --force # Delete every resource defined in the given directory gcx resources delete -p ./unwanted-resources/ # Delete every dashboard defined in the given directory gcx resources delete -p ./unwanted-resources/ dashboard # Delete all dashboards with auto-approval gcx resources delete dashboards --yes # Delete all dashboards using environment variable GCX_AUTO_APPROVE=1 gcx resources delete dashboards # Provider-backed resource types (SLO, Synthetic Monitoring, Alerting): gcx resources delete slo/my-slo-uuid gcx resources delete checks/my-check-uuid gcx resources delete rules/my-rule-uuid ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --assume-server-dry-run strings Assert that the given resources honor server-side dry-run, augmenting the built-in allowlist. Repeatable or comma-separated, each value a GroupResource string (.), e.g. alertrules.rules.alerting.grafana.app --dry-run If set, the delete operation will be simulated --force Delete all resources of the specified resource types -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-concurrent int Maximum number of concurrent operations (default 10) --on-error string How to handle errors during resource operations: ignore — continue processing all resources and exit 0 fail — continue processing all resources and exit 4 (partial failure) if any failed (default) abort — stop on the first error and exit non-zero (default "fail") -o, --output string Output format. One of: agents, json, text, yaml (default "text") -p, --path strings Path on disk containing the resources to delete -y, --yes Auto-approve destructive operations (automatically enables --force) ``` Inherits `--config`, `--context` from [`gcx resources`](#gcx-resources-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx resources edit` Edit resources from Grafana using the default editor. This command allows the edition of any resource that can be accessed by this CLI tool. It will open the default editor as configured by the EDITOR environment variable, or fall back to ‘vi’ for Linux or ’notepad’ for Windows. The editor will be started in the shell set by the SHELL environment variable. If undefined, ‘/bin/bash’ is used for Linux or ‘cmd’ for Windows. The edition will be cancelled if no changes are written to the file or if the file after edition is empty. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources edit RESOURCE_SELECTOR [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Edit a dashboard gcx resources edit dashboard/foo # Edit a dashboard in JSON gcx resources edit -o json dashboard/foo # Using an alternative editor EDITOR=nvim gcx resources edit dashboard/foo ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for edit -o, --output string Output format. One of: json, yaml (default "json") ``` Inherits `--config`, `--context` from [`gcx resources`](#gcx-resources-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx resources get` Get resources from Grafana using a specific format. See examples below for more details. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources get [RESOURCE_SELECTOR]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Everything: gcx resources get dashboards/foo # All instances for a given kind(s): gcx resources get dashboards gcx resources get dashboards folders # Single resource kind, one or more resource instances: gcx resources get dashboards/foo gcx resources get dashboards/foo,bar # Single resource kind, long kind format: gcx resources get dashboard.dashboards/foo gcx resources get dashboard.dashboards/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, long kind format: gcx resources get dashboard.dashboards/foo folder.folders/qux gcx resources get dashboard.dashboards/foo,bar folder.folders/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 resource types (SLO, Synthetic Monitoring, Alerting): gcx resources get slo gcx resources get slo/my-slo-uuid gcx resources get checks gcx resources get rules # Discover available JSON fields for a resource type: gcx resources get dashboards --json list # Select specific fields (no external parsing needed): gcx resources get dashboards --json metadata.name,spec.title ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to fetch per resource type (0 for all) (default 50) --on-error string How to handle errors during resource operations: ignore — continue processing all resources and exit 0 fail — continue processing all resources and exit 4 (partial failure) if any failed (default) abort — stop on the first error and exit non-zero (default "fail") --open Open the resource in the default browser -o, --output string Output format. One of: agents, json, text, wide, yaml (default "text") ``` Inherits `--config`, `--context` from [`gcx resources`](#gcx-resources-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx resources list-examples` List example manifests for provider-backed resource types. Without arguments, lists all resources that have examples. With a selector, shows examples for matching resources. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources list-examples [RESOURCE_SELECTOR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources list-examples gcx resources list-examples -o wide gcx resources list-examples -o json gcx resources list-examples -o yaml gcx resources list-examples incidents gcx resources list-examples incidents -o json gcx resources list-examples slo -o yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-examples --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, wide, yaml (default "text") ``` Inherits `--config`, `--context` from [`gcx resources`](#gcx-resources-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx resources list-types` List available Grafana API resource types and their schemas by querying a live Grafana instance. Requires a connection to Grafana. Use –no-schema to skip OpenAPI spec fetching for faster results. Optionally filter by a resource selector. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources list-types [RESOURCE_SELECTOR] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources list-types gcx resources list-types -o wide gcx resources list-types -o json gcx resources list-types -o yaml gcx resources list-types -o json --no-schema gcx resources list-types incidents gcx resources list-types incidents.v1alpha1.incident.ext.grafana.app -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list-types --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --no-schema Skip fetching OpenAPI spec schemas (faster, omits schema info and unlistable resource types) -o, --output string Output format. One of: agents, json, text, wide, yaml (default "text") ``` Inherits `--config`, `--context` from [`gcx resources`](#gcx-resources-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx resources pull` Pull resources from Grafana using a specific format. See examples below for more details. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources pull [RESOURCE_SELECTOR]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Everything: gcx resources pull # All instances for a given kind(s): gcx resources pull dashboards gcx resources pull dashboards folders # Single resource kind, one or more resource instances: gcx resources pull dashboards/foo gcx resources pull dashboards/foo,bar # Single resource kind, long kind format: gcx resources pull dashboard.dashboards/foo gcx resources pull dashboard.dashboards/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, long kind format: gcx resources pull dashboard.dashboards/foo folder.folders/qux gcx resources pull dashboard.dashboards/foo,bar folder.folders/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 resource types (SLO, Synthetic Monitoring, Alerting): gcx resources pull slo -p ./slo-defs/ gcx resources pull checks -p ./checks/ gcx resources pull rules -p ./rules/ ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for pull --include-managed Include resources managed by tools other than gcx --on-error string How to handle errors during resource operations: ignore — continue processing all resources and exit 0 fail — continue processing all resources and exit 4 (partial failure) if any failed (default) abort — stop on the first error and exit non-zero (default "fail") -o, --output string Output format. One of: json, yaml (default "json") -p, --path string Path on disk in which the resources will be written (default "./resources") ``` Inherits `--config`, `--context` from [`gcx resources`](#gcx-resources-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx resources push` Push resources to Grafana using a specific format. See examples below for more details. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources push [RESOURCE_SELECTOR]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Everything: gcx resources push # All instances for a given kind(s): gcx resources push dashboards gcx resources push dashboards folders # Single resource kind, one or more resource instances: gcx resources push dashboards/foo gcx resources push dashboards/foo,bar # Single resource kind, long kind format: gcx resources push dashboard.dashboards/foo gcx resources push dashboard.dashboards/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, long kind format: gcx resources push dashboard.dashboards/foo folder.folders/qux gcx resources push dashboard.dashboards/foo,bar folder.folders/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 resource types (SLO, Synthetic Monitoring, Alerting): gcx resources push slo -p ./slo-defs/ gcx resources push checks -p ./checks/ gcx resources push rules -p ./rules/ # Mixed push: native and provider resources from the same directory # (types auto-detected from apiVersion/kind in YAML files): gcx resources push -p ./resources/ ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --assume-server-dry-run strings Assert that the given resources honor server-side dry-run, augmenting the built-in allowlist. Repeatable or comma-separated, each value a GroupResource string (.), e.g. alertrules.rules.alerting.grafana.app --dry-run If set, the push operation will be simulated, without actually creating or updating any resources -h, --help help for push --include-managed If set, resources managed by other tools will be included in the push operation --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-concurrent int Maximum number of concurrent operations (default 10) --omit-manager-fields If set, the manager fields will not be appended to the resources --on-error string How to handle errors during resource operations: ignore — continue processing all resources and exit 0 fail — continue processing all resources and exit 4 (partial failure) if any failed (default) abort — stop on the first error and exit non-zero (default "fail") -o, --output string Output format. One of: agents, json, text, yaml (default "text") -p, --path strings Paths on disk from which to read the resources to push (default [./resources]) ``` Inherits `--config`, `--context` from [`gcx resources`](#gcx-resources-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx resources validate` Validate local resource files against a remote Grafana instance. Requires a live connection to Grafana for server-side validation. Reads resources from disk and reports validation errors per resource. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx resources validate [RESOURCE_SELECTOR]... [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Validate all resources in the default directory gcx resources validate # Validate a single resource kind gcx resources validate dashboards # Validate a multiple resource kinds gcx resources validate dashboards folders # Displaying validation results as YAML gcx resources validate -o yaml # Displaying validation results as JSON gcx resources validate -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --assume-server-dry-run strings Assert that the given resources honor server-side dry-run, augmenting the built-in allowlist. Repeatable or comma-separated, each value a GroupResource string (.), e.g. alertrules.rules.alerting.grafana.app -h, --help help for validate --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --max-concurrent int Maximum number of concurrent operations (default 10) --on-error string How to handle errors during resource operations: ignore — continue processing all resources and exit 0 fail — continue processing all resources and exit 4 (partial failure) if any failed (default) abort — stop on the first error and exit non-zero (default "fail") -o, --output string Output format. One of: agents, json, text, yaml (default "text") -p, --path strings Paths on disk from which to read the resources. (default [./resources]) ``` Inherits `--config`, `--context` from [`gcx resources`](#gcx-resources-flags). Inherits `--agent`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx setup` Onboard and configure Grafana Cloud products. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for setup ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx setup status` Show aggregated setup status across all products. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx setup status [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for status --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx setup`](#gcx-setup-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo` Manage Grafana SLO definitions and reports **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for slo ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo definitions` Manage SLO definitions. **Aliases:** `def`, `defs` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for definitions ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo definitions delete` Delete SLO definitions. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo definitions delete UUID... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo definitions get` Get a single SLO definition. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo definitions get UUID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo definitions list` List SLO definitions. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo definitions list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return after fetch (0 for all; use a positive value to trim output only) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo definitions pull` Pull SLO definitions to disk. Deprecated: use gcx resources pull slos.v1alpha1.slo.ext.grafana.app -p PATH -o yaml instead. This compatibility command retains its Kind/name.yaml layout. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo definitions pull [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for pull -d, --output-dir string Directory to write SLO definitions to (default ".") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo definitions push` Push SLO from files. Deprecated: use gcx resources push slos.v1alpha1.slo.ext.grafana.app -p PATH instead. Writes update only an existing metadata.name UUID; an absent or unknown UUID creates a new resource. Manifests may omit apiVersion and kind; this command supplies its resource type. This compatibility command retains its file-at-a-time results and local-only –dry-run preview. The preview shows manifest identities only; it does not resolve the remote UUID or determine create versus update. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo definitions push FILE... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dry-run Preview changes without making them -h, --help help for push --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo definitions status` Show SLO definitions status by combining the SLO API with Prometheus metrics. Displays current SLI, error budget, and health status for each SLO definition. Requires that the SLO destination datasource has recording rules generating grafana\_slo\_* metrics. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo definitions status [UUID] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Show status of all SLO definitions. gcx slo definitions status # Show status of a specific SLO by UUID. gcx slo definitions status abc123def # Show extended status with 1h/1d SLI columns. gcx slo definitions status -o wide # Output status as JSON for scripting. gcx slo definitions status -o json # Render a compliance summary bar chart. gcx slo definitions status -o graph ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for status --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo definitions timeline` Render SLI values over time as a line chart by executing a range query against the Prometheus datasource associated with each SLO. Requires that the SLO destination datasource has recording rules generating grafana\_slo\_sli\_window metrics. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo definitions timeline [UUID] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Render SLI trend for all SLOs over the past 7 days. gcx slo definitions timeline # Render SLI trend for a specific SLO. gcx slo definitions timeline abc123def # Custom time range with explicit step. gcx slo definitions timeline --from now-24h --to now --step 5m # Use duration shorthand for the past 24 hours. gcx slo definitions timeline --since 24h # Output timeline data as a table. gcx slo definitions timeline -o table ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start of the time range (e.g. now-7d, now-24h, RFC3339, Unix timestamp) (default "now-7d") -h, --help help for timeline --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, graph, json, table, yaml (default "graph") --since string Duration before now (e.g. 1h, 7d). Equivalent to --from now- --to now. --step string Query step (e.g. 5m, 1h). Defaults to auto-computed value. --to string End of the time range (e.g. now, RFC3339, Unix timestamp) (default "now") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo reports` Manage SLO reports. **Aliases:** `report` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for reports ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo reports delete` Delete SLO reports. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo reports delete UUID... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo reports get` Get a single SLO report. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo reports get UUID [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo reports list` List SLO reports. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo reports list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo reports pull` Pull SLO reports to disk. Deprecated: use gcx resources pull reports.v1alpha1.slo.ext.grafana.app -p PATH -o yaml instead. This compatibility command retains its Kind/name.yaml layout. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo reports pull [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for pull -d, --output-dir string Directory to write SLO reports to (default ".") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo reports push` Push report from files. Deprecated: use gcx resources push reports.v1alpha1.slo.ext.grafana.app -p PATH instead. Writes update only an existing metadata.name UUID; an absent or unknown UUID creates a new resource. Manifests may omit apiVersion and kind; this command supplies its resource type. This compatibility command retains its file-at-a-time results and local-only –dry-run preview. The preview shows manifest identities only; it does not resolve the remote UUID or determine create versus update. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo reports push FILE... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dry-run Preview changes without making them -h, --help help for push --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo reports status` Show SLO report status by aggregating health data across all SLOs in each report. Fetches report definitions, resolves referenced SLO UUIDs, queries Prometheus metrics, and computes combined SLI and error budget per report. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo reports status [UUID] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Show status of all SLO reports. gcx slo reports status # Show status of a specific report by UUID. gcx slo reports status abc123def # Show extended status with per-SLO breakdown. gcx slo reports status -o wide # Output status as JSON for scripting. gcx slo reports status -o json # Render a combined SLI bar chart. gcx slo reports status -o graph ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for status --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx slo reports timeline` Render SLI values over time as line charts for each SLO report by executing range queries against the Prometheus datasource associated with each constituent SLO. Requires that SLO destination datasources have recording rules generating grafana\_slo\_sli\_window metrics. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx slo reports timeline [UUID] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Render SLI trend for all SLO reports over the past 7 days. gcx slo reports timeline # Render SLI trend for a specific report. gcx slo reports timeline abc123def # Custom time range with explicit step. gcx slo reports timeline --from now-24h --to now --step 5m # Use duration shorthand for the past 24 hours. gcx slo reports timeline --since 24h # Output timeline data as a table. gcx slo reports timeline -o table ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start of the time range (e.g. now-7d, now-24h, RFC3339, Unix timestamp) (default "now-7d") -h, --help help for timeline --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, graph, json, table, yaml (default "graph") --since string Duration before now (e.g. 1h, 7d). Equivalent to --from now- --to now. --step string Query step (e.g. 5m, 1h). Defaults to auto-computed value. --to string End of the time range (e.g. now, RFC3339, Unix timestamp) (default "now") ``` Inherits `--config` from [`gcx slo`](#gcx-slo-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring` Manage Grafana Synthetic Monitoring checks and probes **Aliases:** `sm`, `synth` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for synthetic-monitoring ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring checks` Manage Synthetic Monitoring checks. **Aliases:** `check` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for checks ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring checks create` Create a Synthetic Monitoring check from a file. Note: checks incur Grafana Cloud usage — each test execution is billed, and check results are stored as metrics and logs, which count toward your metrics and logs usage. See [https://grafana.com/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/synthetic-monitoring-invoice.md](/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/synthetic-monitoring-invoice.md). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring checks create [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Create a check from a YAML file. gcx synthetic-monitoring checks create -f check.yaml # Create and show resulting status. gcx synthetic-monitoring checks create -f check.yaml --show-status # Validate HTTP target before creating. gcx synthetic-monitoring checks create -f check.yaml --validate-targets ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the check manifest (YAML) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --show-status Query and display check status after creation --validate-targets Pre-flight HTTP HEAD request for HTTP check targets (warning only) ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring checks delete` Delete Synthetic Monitoring checks. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring checks delete NAME... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring checks get` Get a single Synthetic Monitoring check. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring checks get NAME [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Get check by resource name (from 'gcx synthetic-monitoring checks list'). gcx synthetic-monitoring checks get grafana-instance-health-5594 # Get check by numeric ID. gcx synthetic-monitoring checks get 5594 # Get check with current execution status. gcx synthetic-monitoring checks get grafana-instance-health-5594 --show-status # Get a scripted/browser check with a readable script, ready to edit and 'checks update'. gcx synthetic-monitoring checks get grafana-instance-health-5594 --decode-script -o yaml > check.yaml ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --decode-script Decode a scripted/browser check's base64 script to plaintext (yaml/json output only, for editing and 'checks update') -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --show-status Query and display the check's current execution status from Prometheus ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring checks list` List Synthetic Monitoring checks. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring checks list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all checks. gcx synthetic-monitoring checks list # Filter by job glob. gcx synthetic-monitoring checks list --job 'shopk8s-*' # Filter by label. gcx synthetic-monitoring checks list --label env=prod ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --job string Filter by job name glob pattern (e.g. --job 'shopk8s-*') --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --label stringArray Filter by label key=value (repeatable, e.g. --label env=prod) --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring checks status` Show pass/fail status by combining the SM API with Prometheus metrics. Displays current success rate, latency (from probe\_duration\_seconds), number of probes reporting, and health status for each check. Requires a Prometheus datasource containing SM metrics. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring checks status [ID] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Show status of all checks. gcx synthetic-monitoring checks status # Show status of a specific check by ID. gcx synthetic-monitoring checks status 42 # Filter by job name glob. gcx synthetic-monitoring checks status --job 'shopk8s-*' # Filter by label and status. gcx synthetic-monitoring checks status --label env=prod --status FAILING # Specify the Prometheus datasource to query. gcx synthetic-monitoring checks status --datasource-uid my-prometheus # Output as JSON for scripting. gcx synthetic-monitoring checks status -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --datasource-uid string UID of the Prometheus datasource to query -h, --help help for status --job string Filter by job name glob pattern (e.g. --job 'shopk8s-*') --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --label stringArray Filter by label key=value (repeatable, e.g. --label env=prod) -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --status string Filter results by status: OK, FAILING, or NODATA ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring checks test` Run a Synthetic Monitoring check once against its probes without persisting it — the check is never saved, and no schedule is created. Results are recovered by polling Loki for the log lines the probes emit for this execution (tagged type=“adhoc”), the same mechanism the Synthetic Monitoring app’s “Test” button uses. Requires a Loki datasource containing SM ad-hoc logs, and read access to it. Note: ad-hoc test executions are billed the same as scheduled check executions. See [https://grafana.com/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/synthetic-monitoring-invoice.md](/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/synthetic-monitoring-invoice.md). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring checks test [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Run a check once from a YAML file. gcx synthetic-monitoring checks test -f check.yaml # Specify the Loki datasource to poll for results. gcx synthetic-monitoring checks test -f check.yaml --logs-datasource-uid my-loki ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the check manifest (YAML) -h, --help help for test --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --logs-datasource-uid string UID of the Loki datasource to poll for ad-hoc results -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring checks timeline` Render probe\_success values over time as a line chart by executing a range query against the Prometheus datasource. Each probe reporting for the check is rendered as a separate series. Requires a Prometheus datasource containing SM metrics. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring checks timeline ID [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Render timeline for a check over the past 6 hours (default). gcx synthetic-monitoring checks timeline 42 # Custom duration. gcx synthetic-monitoring checks timeline 42 --since 24h # Explicit time range. gcx synthetic-monitoring checks timeline 42 --from now-24h --to now # Output timeline data as a table. gcx synthetic-monitoring checks timeline 42 -o table # Specify the Prometheus datasource. gcx synthetic-monitoring checks timeline 42 --datasource-uid my-prometheus ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --datasource-uid string UID of the Prometheus datasource to query --from string Start of the time range (e.g. now-6h, now-24h, RFC3339, Unix timestamp) -h, --help help for timeline --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, graph, json, table, yaml (default "graph") --since string Duration before now to display (e.g. 1h, 6h, 24h, 7d) (default "6h") --to string End of the time range (e.g. now, RFC3339, Unix timestamp) ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring checks update` Update a Synthetic Monitoring check from a file. Note: frequency and probe changes affect billable usage — each test execution is billed, and check results are stored as metrics and logs, which count toward your metrics and logs usage. See [https://grafana.com/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/synthetic-monitoring-invoice.md](/docs/grafana-cloud/cost-management-and-billing/manage-invoices/understand-your-invoice/synthetic-monitoring-invoice.md). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring checks update [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Update a check using its resource name. gcx synthetic-monitoring checks update web-check-1234 -f check.yaml # Update and show previous status. gcx synthetic-monitoring checks update web-check-1234 -f check.yaml --show-status ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the check manifest (YAML) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") --show-status Query and display the previous check status after update --validate-targets Pre-flight HTTP HEAD request for HTTP check targets (warning only) ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring probes` Manage Synthetic Monitoring probes. **Aliases:** `probe` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for probes ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring probes create` Create a Synthetic Monitoring probe. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring probes create [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Create a probe with a name and region. gcx synthetic-monitoring probes create --name my-probe --region eu # Create a probe with labels and coordinates. gcx synthetic-monitoring probes create --name my-probe --region us --labels env=prod,team=sre --latitude 37.7749 --longitude -122.4194 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --labels strings Labels in key=value format --latitude float Probe latitude --longitude float Probe longitude --name string Probe name (required) -o, --output string Output format. One of: agents, json, text, yaml (default "text") --region string Probe region ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring probes delete` Delete Synthetic Monitoring probes. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring probes delete ID... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring probes deploy` Generate a Namespace, Secret, and Deployment for a private Synthetic Monitoring probe. The Deployment reads the probe token from the Secret and sends it to the agent through a protected environment variable. The output contains the Secret, so store saved output securely. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring probes deploy [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Read the probe token from a file. gcx synthetic-monitoring probes deploy --probe-name my-probe --token-file ./probe-token --api-server-url synthetic-monitoring-grpc.grafana.net:443 # Read the probe token from an environment variable and apply the manifests. gcx synthetic-monitoring probes deploy --probe-name my-probe --token-env PROBE_TOKEN --api-server-url synthetic-monitoring-grpc.grafana.net:443 | kubectl apply -f - # Read the probe token from standard input. printf '%s' "$PROBE_TOKEN" | gcx synthetic-monitoring probes deploy --probe-name my-probe --token-file - --api-server-url synthetic-monitoring-grpc.grafana.net:443 ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --api-server-url string SM API gRPC address in host:port format (required) -h, --help help for deploy --image string SM agent container image (default "grafana/synthetic-monitoring-agent:latest") --namespace string Kubernetes namespace (default "synthetic-monitoring") --probe-name string Name for the Kubernetes resources (required) --token-env string Read the probe auth token from this environment variable --token-file string Read the probe auth token from a file (- for standard input) ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring probes list` List Synthetic Monitoring probes. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring probes list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of items to return (0 for all) (default 50) -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring probes reset-token` Reset the auth token of a Synthetic Monitoring probe. The command returns the new token once. Save the new token and update the probe deployment before you restart the agent. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring probes reset-token ID [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Reset a probe token and show it in the default text output. gcx synthetic-monitoring probes reset-token 123 # Reset a probe token and return a structured result. gcx synthetic-monitoring probes reset-token 123 -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for reset-token --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring queries` Discover Synthetic Monitoring named queries. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for queries ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring queries get` Show one named query’s description and full parameter schema, plus a ready-to-run ‘gcx synthetic-monitoring query’ invocation. Requires Synthetic Monitoring app v1.62.0 or later. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring queries get NAME [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring queries get checks_uptime ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring queries list` List the named queries this tenant’s Synthetic Monitoring datasource publishes. Each entry can be run with ‘gcx synthetic-monitoring query NAME’; use ‘gcx synthetic-monitoring queries get NAME’ for its full parameter schema. Requires Synthetic Monitoring app v1.62.0 or later – named-query discovery is not available on older deployments. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring queries list [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring queries list ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx synthetic-monitoring query` Run a query the Synthetic Monitoring backend knows by name. The backend owns the expression and picks the datasource that holds the data, so no PromQL or LogQL is sent or required. Parameters are passed with -p and are validated by the backend, which reports the expression it ran. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx synthetic-monitoring query NAME [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Uptime for a check, as the app computes it gcx synthetic-monitoring query checks_uptime \ -p job=my-check -p instance=https://example.com -p frequency=60000 # Execution rate per probe over the last day gcx synthetic-monitoring query probe_execution_rate \ -p job=my-check -p instance=https://example.com --from now-1d ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --from string Start of the time range (default "now-3h") -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, yaml (default "table") -p, --param stringArray Query parameter as key=value (repeatable), e.g. -p job=my-check --to string End of the time range (default "now") ``` Inherits `--config` from [`gcx synthetic-monitoring`](#gcx-synthetic-monitoring-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces` Query Tempo datasources and manage Adaptive Traces **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for traces ``` #### Shared flags text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --config string Path to the configuration file to use ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive` Manage Adaptive Traces resources **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for adaptive ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive policies` Manage Adaptive Traces sampling policies. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for policies ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive policies create` Create an Adaptive Traces sampling policy from a file. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces adaptive policies create [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the policy definition (use - for stdin) -h, --help help for create --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive policies delete` Delete one or more Adaptive Traces sampling policies. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces adaptive policies delete ... [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --force Skip confirmation prompt -h, --help help for delete --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive policies get` Get an Adaptive Traces sampling policy by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces adaptive policies get [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive policies list` List Adaptive Traces sampling policies. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces adaptive policies list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of policies to return (0 for no limit) (default 50) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive policies update` Update an Adaptive Traces sampling policy by ID. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces adaptive policies update [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -f, --filename string File containing the policy definition (use - for stdin) -h, --help help for update --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "yaml") ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive recommendations` Manage Adaptive Traces recommendations. **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for recommendations ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive recommendations apply` Apply an Adaptive Traces recommendation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces adaptive recommendations apply [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dry-run Preview what would be applied without making changes --force Skip confirmation prompt -h, --help help for apply --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive recommendations dismiss` Dismiss an Adaptive Traces recommendation. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces adaptive recommendations dismiss [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --dry-run Preview what would be dismissed without making changes --force Skip confirmation prompt -h, --help help for dismiss --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces adaptive recommendations list` List Adaptive Traces recommendations. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces adaptive recommendations list [flags] ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for list --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces baseline` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Find unranked candidates when you have a seed trace (TRACE\_ID) but need a useful comparison; if you already have both trace IDs, use ‘gcx traces diff’ directly. Retrieval fetches the seed, matches its root service/operation, requires root status != error (including unset), retains downstream errors, and pins up to three busiest downstream services; these heuristics do not prove health or comparable work. Apply verified environment, tenant, or operation constraints with –filter from the first request, then fetch a small batch of plausible candidates with ‘gcx traces get –llm’ when their summaries lack enough context. Use candidate bodies and exploratory diffs to accept or reject controls for the actual symptom, rather than requiring exact workload filters before the first diff or treating the first result as healthy. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces baseline TRACE_ID [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Find a small shortlist; COHORT is an already-verified TraceQL spanset gcx traces baseline --context prod -d UID --filter "$COHORT" --limit 5 # With no additional known scope, use the seed-derived defaults gcx traces baseline --context prod -d UID --limit 5 # Inspect selected candidates; repeat for a small batch, not every result gcx traces get --context prod -d UID --llm -o agents # Assess a candidate with an exploratory diff (seed minus candidate) gcx traces diff --context prod -d UID # Set the candidate window; this does not bound the seed trace lookup gcx traces baseline --context prod -d UID --filter "$COHORT" --limit 5 \ --from 2026-01-15T08:00:00Z --to 2026-01-15T09:00:00Z ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --filter stringArray Raw TraceQL spanset expression to constrain candidates (repeatable; ANDed server-side with the generated query) --from string Absolute start time override (RFC3339, Unix timestamp, or relative like 'now-1h'); requires --to -h, --help help for baseline --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of candidates to return; must be at least 1 (default 20) -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --to string Absolute end time override (RFC3339, Unix timestamp, or relative like 'now'); requires --from --window string Search window padding applied before and after the seed trace's time range, so candidates from before or after the seed are eligible (e.g., 30m, 6h, 7d). Ignored when --from/--to are set (default "30m") ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces diff` This command is experimental. It may be removed, or its subcommands, flags and responses may change without following the normal semantic versioning conventions. Compare two known trace IDs using the Grafana Cloud-only trace-diff API; use ‘gcx traces baseline’ first only when you need candidate IDs. TRACE\_A is the prospective baseline and TRACE\_B is the comparison, with deltas B - A: positive duration means B is slower and negative means faster, not automatically a regression or improvement (a request can fail early). Use candidate bodies and exploratory diffs to assess comparability, rejecting obvious context mismatches first and interpreting timing at the affected request boundary; a diff localizes execution changes but does not establish their cause. Keep the same context/datasource and make –from/–to (or –since) cover both executions; without time bounds the lookup uses the full lookback, and if the endpoint is unavailable, use ‘gcx traces get –llm’ to compare both bodies manually instead. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces diff TRACE_A TRACE_B [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Compare an already-known pair directly; baseline search is not required gcx traces diff --context prod -d UID # Inspect a plausible candidate before using a diff to assess it gcx traces get --context prod -d UID --llm -o agents # Assess selected candidates against the seed; repeat only as useful gcx traces diff --context prod -d UID # Bound BOTH trace lookups, including an older candidate, and allow spilling gcx traces diff --context prod -d UID \ --from 2026-01-15T08:00:00Z --to 2026-01-15T10:00:00Z -o agents ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for diff --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, yaml (default "json") --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces get` Retrieve a single trace by its trace ID from a Tempo datasource. TRACE\_ID is the hex-encoded trace identifier to retrieve. Datasource is resolved from -d flag or datasources.tempo in your context. Pass –since or –from/–to (e.g. the search’s time range) to make the lookup much faster. Omit them when the time range is unknown; a range that misses the trace returns not found. Use –share-link to print a Grafana Explore URL for the trace, or –open to open it in your browser after retrieval succeeds. Share links require an explicit time range via –since or –from/–to. Experimental: –llm requests the trace in a new LLM-friendly JSON format by sending the “Accept: application/vnd.grafana.llm” header. Datasources that do not support this format return the standard response. Experimental: for large traces, –filter narrows the response to spans matching a TraceQL spanset filter (V2 only). –keep-hierarchy, –match-depth, and –ancestor-depth shape how much context around each match is kept, and are ignored without –filter. Experimental: –prune collapses repeated sibling spans (for example, a fan-out of identical DB calls) into a single aggregated span. Off unless set. –prune-group-by, –prune-min-spans, and –prune-max-parent-depth tune the pruning behavior and apply only when –prune enables pruning. If the trace is too large for -o agents, the response is spilled to a file with a hint to read it directly or re-run narrower (e.g. with –filter or –prune). shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces get TRACE_ID [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Fetch a trace by ID for agent analysis gcx traces get -d UID --llm -o json # Print a Grafana Explore share link for the trace gcx traces get -d UID --share-link # Output raw OTLP-shaped JSON when explicitly needed gcx traces get -d UID -o json # Narrow a large trace to error spans and their ancestor path gcx traces get -d UID --filter '{ status = error }' --keep-hierarchy # Collapse repeated sibling spans to shrink a huge trace before analysis gcx traces get -d UID --prune --llm -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text --ancestor-depth int [experimental] Levels of ancestors to keep above each matched span: -1 = all (default), 0 = none, n = n levels (ignored without --filter or --keep-hierarchy) (default -1) -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --filter string [experimental] TraceQL spanset filter; only matching spans are returned (V2 only) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for get --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --keep-hierarchy [experimental] Include each matched span's ancestor path to the root (ignored without --filter) --llm [experimental] Request LLM-friendly trace format by sending the 'Accept: application/vnd.grafana.llm' header. Falls back to default JSON --match-depth int [experimental] Levels of descendants to keep below each matched span: -1 = all, 0 = matched spans only, n = n levels (ignored without --filter) --open Open the retrieved trace in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --prune [experimental] Collapse repeated sibling spans (e.g. a fan-out of identical DB calls) into a single aggregated span to shrink large traces. Off unless set --prune-group-by string [experimental] Comma-separated attribute glob patterns siblings must match to be grouped for pruning, e.g. 'db.*,http.method'. Applies only when --prune enables pruning --prune-max-parent-depth int [experimental] Ancestor levels above pruned leaves that may also be pruned; Tempo defaults to 1. Applies only when --prune enables pruning --prune-min-spans int [experimental] Minimum sibling span count required before a group is pruned; Tempo defaults to 5. Applies only when --prune enables pruning --share-link Print the Grafana Explore URL for the retrieved trace to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces labels` List all trace labels or get values for a specific label from a Tempo datasource. When -l/–label is provided, returns values for that label. When -l is omitted, returns all label names. Datasource is resolved from -d flag or datasources.tempo in your context. Experimental: –llm requests label values in a new LLM-friendly JSON format by sending the “Accept: application/vnd.grafana.llm” header. Datasources that do not support this format return the standard response. **Aliases:** `tags` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces labels [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # List all labels gcx traces labels -d UID # Get LLM-friendly values for a label gcx traces tags -d UID -l resource.service.name --llm -o json # Output as JSON gcx traces labels -d UID -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) -h, --help help for labels --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -l, --label string Get values for this label (omit to list all labels) --llm [experimental] Request LLM-friendly label values format by sending the 'Accept: application/vnd.grafana.llm' header. Falls back to default JSON (requires --label) -o, --output string Output format. One of: agents, json, table, yaml (default "table") -q, --query string TraceQL query to filter labels --scope string Tag scope filter (resource, span, event, link, instrumentation) ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces metrics` Execute a TraceQL metrics query against a Tempo datasource. TRACEQL is the TraceQL metrics expression to evaluate. Datasource is resolved from -d flag or datasources.tempo in your context. Instant vs range is deduced from time flags: no time flags = instant query, –since or –from/–to = range query. Use –instant to force an instant query even when a time range is provided. If no time flags are set, gcx queries the last hour by default. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces metrics [TRACEQL] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Run a TraceQL metrics query gcx traces metrics -d UID '{ } | rate()' --since 1h # Print a Grafana Explore share link for the query gcx traces metrics '{ } | rate()' --share-link # Output as JSON gcx traces metrics -d UID '{ } | rate()' --since 1h -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for metrics --instant Run an instant query over the selected time range instead of a range query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, graph, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx traces query` Search for traces using a TraceQL query against a Tempo datasource. TRACEQL is the TraceQL expression to evaluate. Datasource is resolved from -d flag or datasources.tempo in your context. Use –share-link to print the equivalent Grafana Explore URL, or –open to open it in your browser after the query succeeds. Share links require an explicit time range via –since or –from/–to. **Aliases:** `search` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx traces query [TRACEQL] [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Run a TraceQL query gcx traces query -d UID '{ span.http.status_code >= 500 }' # Print a Grafana Explore share link for the query gcx traces query '{ span.http.status_code >= 500 }' --share-link # Output as JSON gcx traces query -d UID '{ span.http.status_code >= 500 }' -o json ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -d, --datasource string Datasource UID (required unless datasources.tempo is configured) --error-on-empty Fail if the query returns no results --expr string Query expression (alternative to positional argument) --from string Start time (RFC3339, Unix timestamp, or relative like 'now-1h') -h, --help help for query --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields --limit int Maximum number of traces to return (0 means no limit) (default 20) --open Open the executed query in Grafana Explore -o, --output string Output format. One of: agents, json, table, wide, yaml (default "table") --share-link Print the Grafana Explore URL for the executed query to stderr --since string Duration before --to, or now if omitted (e.g., 30m, 6h, 7d); mutually exclusive with --from --step string Query step (e.g., '15s', '1m') --to string End time (RFC3339, Unix timestamp, or relative like 'now') ``` Inherits `--config` from [`gcx traces`](#gcx-traces-flags). Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ### `gcx version` Print version, commit, build date, Go version, OS, and architecture. Supports structured output via –output json/yaml. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell gcx version [flags] ``` **Examples** shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell # Human-readable version gcx version # JSON output for automation gcx version -o json # Select specific fields gcx version --json version,commit ``` **Flags** text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text -h, --help help for version --jq string jq expression to apply to JSON output. Mutually exclusive with --json. --json string Comma-separated list of fields to include in JSON output, or 'list' (or '?') to discover available fields -o, --output string Output format. One of: agents, json, text, yaml (default "text") ``` Inherits `--agent`, `--context`, `--insecure-log-http-payload`, `--no-color`, `--no-truncate`, `--verbose` from [`gcx`](#gcx-flags). ## Environment variables Environment variables override matching configuration values in the selected context for the current invocation; they do not implicitly update the configuration file. `--context` selects the context before these overrides are applied. Precedence depends on the setting (highest priority first): - **Configuration file selection:** `--config` > `GCX_CONFIG` > automatic discovery. An explicit file bypasses layering; otherwise, repository configuration takes precedence over user configuration, then system configuration. - **Agent mode:** explicit `--agent` or `--agent=false` > `GCX_AGENT_MODE` > agent detection variables. - **Telemetry:** non-empty `GCX_TELEMETRY` > `DO_NOT_TRACK=1` or `true` > `diagnostics.telemetry` in configuration > the built-in default. Blank `GRAFANA_TOKEN`, `GRAFANA_PASSWORD`, and `GRAFANA_CLOUD_TOKEN` values are ignored. Environment overrides still follow the [configuration source and credential restrictions](../configuration/#understand-the-gcx-configuration-file-in-use). ### `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_AUTO_APPROVE` AutoApprove automatically enables the –force flag on delete operations, enabling non-interactive operation in CI/CD pipelines. ### `GCX_KEYCHAIN` Keychain overrides trusted credentials.keychain configuration. “off” is the only value that disables the OS keychain and persists credentials in the mode-0600 config file. “on” is the default; an unrecognized value warns and resolves to “on”, so a typo cannot silently write plaintext. ### `GCX_NO_UPDATE_NOTIFIER` DisableUpdateNotifier disables the periodic notifier that reminds users when their installed gcx skills can be updated. Any non-empty value disables the notifier (NO\_COLOR convention). ### `GCX_TELEMETRY` Telemetry controls anonymous usage telemetry for this invocation: “enabled”, “disabled”, or “log” (print the event to stderr and send nothing). Telemetry is enabled by default. Any other non-empty value disables telemetry. Takes precedence over the `diagnostics.telemetry` config field. ### `GCX_TELEMETRY_ENDPOINT` Endpoint overrides the URL usage telemetry is sent to. ### `GRAFANA_CLOUD_API_URL` APIUrl is the base URL for all Grafana Cloud API (GCOM) resource calls (stacks, regions, access policies, etc.). Every client talking to GCOM uses it. It is materialized together with OAuthUrl so authentication and later API calls stay in the same Cloud environment. ### `GRAFANA_CLOUD_OAUTH_URL` OAuthUrl is the base URL for the OAuth login flow run by `gcx cloud login`. It is used only during login. Credential-bearing entries are materialized as a coherent OAuth/API pair: one explicit endpoint fills its missing peer; with neither set, gcx derives one unique referenced-stack Cloud environment or falls back to “[https://grafana.com](/)”. Incompatible referenced environments are rejected and require separate entries. ### `GRAFANA_CLOUD_TOKEN` Token is a Grafana Cloud access policy token used to authenticate against GCOM. ### `GRAFANA_ORG_ID` OrgID specifies the organization targeted by this config. Note: required when targeting an on-prem Grafana instance. See StackID for Grafana Cloud instances. ### `GRAFANA_PASSWORD` Password to use when using with basic authentication. Optional. ### `GRAFANA_PROXY_ENDPOINT` ProxyEndpoint is the assistant backend URL used as a reverse proxy for OAuth-authenticated requests. Set automatically by `gcx login`. This may differ from Server when cloud routing directs CLI traffic through a separate endpoint (e.g. the assistant app backend). ### `GRAFANA_SERVER` Server is the address of the Grafana server (https://hostname:port/path). Required. ### `GRAFANA_STACK_ID` StackID specifies the Grafana Cloud stack targeted by this config. Note: required when targeting a Grafana Cloud instance. See OrgID for on-prem Grafana instances. ### `GRAFANA_TLS_CA_FILE` CAFile is the path to a PEM-encoded CA certificate bundle file. When set, this CA is used to verify the server’s certificate. ### `GRAFANA_TLS_CERT_FILE` CertFile is the path to a PEM-encoded client certificate file. This enables mutual TLS (mTLS) authentication with the server. ### `GRAFANA_TLS_KEY_FILE` KeyFile is the path to a PEM-encoded client certificate key file. ### `GRAFANA_TOKEN` APIToken is a service account token. See [https://grafana.com/docs/grafana/latest/administration/service-accounts/#add-a-token-to-a-service-account-in-grafana](/docs/grafana/latest/administration/service-accounts/#add-a-token-to-a-service-account-in-grafana) Note: if defined, the API Token takes precedence over basic auth credentials. Optional. ### `GRAFANA_USER` User to authenticate as with basic authentication. Optional. ### `GRAFANA_CLOUD_STACK` Selected stack’s Grafana Cloud slug ### `GCX_CONFIG` Config file path override ### `NO_COLOR` Disable color output (no-color.org) ### `GRAFANA_PROVIDER_SLO_TOKEN` Overrides the slo provider’s token configuration. ### `GRAFANA_PROVIDER_SLO_ORG_ID` Overrides the slo provider’s org-id configuration. ### `GRAFANA_PROVIDER_SM_TOKEN` Overrides the sm provider’s token configuration. ### `GRAFANA_PROVIDER_SM_URL` Overrides the sm provider’s url configuration. ### `GCX_AGENT_MODE` `1`/`true`/`yes` enables agent mode; `0`/`false`/`no` disables (overrides all others) ### `GCX_AGENT_SPILL_BYTES` Spill threshold in bytes for the `agents` codec (default `102400` = 100 KiB). Payloads above this are written to a temp file; a summary is printed instead. Invalid values fall back to the default. See output.md § Agents Codec ### `CLAUDECODE` Truthy value activates agent mode ### `CLAUDE_CODE` Truthy value activates agent mode ### `CURSOR_AGENT` Truthy value activates agent mode ### `GITHUB_COPILOT` Truthy value activates agent mode ### `AMAZON_Q` Truthy value activates agent mode ### `OPENCODE` Truthy value activates agent mode ### `PI_CODING_AGENT` Truthy value activates agent mode