gcx v1.0.0: command renames, config file format changes, opt-out usage statistics

If you upgrade gcx from v0.4.x or earlier, there are breaking changes to be aware of:

1. Commands are renamed across many providers, with no aliases. Old spellings fail as unknown commands. Behaviour, flags, positional arguments, output schemas, and exit codes are unchanged, only the names moved. The aim is to make a more predictable and understandable command surface. Here are all the changes:

Six gcx assistant investigations subcommands are removed rather than renamed, because their backends do not exist for current investigations: approvals, todos, document, report, timeline, and regenerate-report.

For users of the bundled agent skills: the aio11y and aio11y-prod-setup skills are renamed to agento11y and agento11y-prod-setup, agento11y-eval-starter is renamed to agento11y-test-starter, and the explore-datasources skill is removed.

2. The configuration file format changes, with automatic migration. The config file is now versioned (version: 1) and splits into named stacks, named cloud entries, and contexts that reference them, so one Cloud token is stored once instead of repeated per context. Your existing config migrates automatically the first time the new binary loads it. The old config file is left in the same directory, for you to delete manually when you are ready.

3. Output for scripts and agents follows a strict contract. We are enforcing better consistency for output formats across all commands. When gcx detects it is being driven by an AI agent and no explicit format flag is given, every finite command now emits one JSON document on stdout (its result, or a structured error whose embedded exitCode matches the process exit code), streaming commands emit typed JSON Lines with a terminal success or error event, and stderr is advisory only. Explicit --output, --json, and --jq flags always take precedent. For humans, default output is the same as before, with a few exceptions: some success responses and dry-run notices have moved from stdout to stderr, partial failures in gcx resources get now exit 4 instead of 1, pull counts file-write failures instead of reporting success, and destructive logs adaptive, traces adaptive, and kg commands now prompt for confirmation, so scripts calling them need --force or --yes.

4. gcx reports anonymous usage statistics by default. gcx now reports the shape of usage: the command path, flag names, outcome, and duration. Identifiable information such as positional argument values, flag values, URLs, stack names, and query content are never sent. The only identifier is a random per-installation ID. gcx prints a notice about usage statistics on first run. Find out more by reading the docs.

Why we’re changing it

We want v1.0,0 of gcx to be stable and clean, so we needed to get any known breaking changes in before we cut v1.0.0. We think the command renames make every command name understandable and predictable. The config file refactor will make it more convenient to authenticate to multiple contexts. The opt-out usage statistics will help us understand how our users use gcx, so we can make the product better.

What is not changing

Any command that is not in the rename list above is unchanged.

What to check before you upgrade

• If you have scripts, continuous integration (CI) jobs, aliases, runbooks, or agent prompts that invoke gcx, grep them for the old spellings in the table above and update to the new names before upgrading the binary. Old paths fail immediately as unknown commands.
• If you call gcx alert templates create, update, or apply, switch to gcx alert templates upsert and be aware it always was create-or-update: it will overwrite an existing template with the same name.
• If you script gcx assistant investigations approvals, todos, document, report, timeline, or regenerate-report, remove those calls; they are gone and have no replacement.
• If you script destructive gcx logs adaptive, gcx traces adaptive, or gcx kg delete commands, add --force or --yes; they now prompt for confirmation.
• If a script parses gcx stdout, re-test it after upgrading: some success messages and dry-run notices moved to stderr, and partial failures in gcx resources get now exit 4 instead of 1.
• If you use gcx config set in automation, update the paths to the literal form, for example gcx config set stacks.<name>.grafana.server <url>; the old context-relative paths return an error with the new path.
• If external tooling reads or writes the gcx config file directly, update it for the version: 1 format (named stacks and cloud entries referenced by contexts) before upgrading. Interactive use needs nothing: migration is automatic and writes a backup first.
• If your organisation’s policy requires opting out of usage reporting, set GCX_TELEMETRY=disabled or DO_NOT_TRACK=1 in your environment or CI images before rolling out the new binary; run GCX_TELEMETRY=log gcx <command> to inspect exactly what would be sent. Details: https://grafana.com/docs/grafana-cloud/gcx/anonymous-usage-statistics/
• If you installed the bundled agent skills, run gcx skills update after upgrading so the renamed agento11y* skills and removed explore-datasources skill are reflected in your agent’s skill set.
• Do all of the above before upgrading past v0.4.x; if you pin gcx in CI, upgrade a dev pipeline first and run your scripts against it.

2026-07-22

AI Observability is now Agent Observability: Updated branding and migration guide

Kubernetes Monitoring, release to be confirmed

Kubernetes Monitoring will give AI agents access to its queries