Skip to content

CONCEPT Cited by 1 source

Named contexts for multi-stack

Named contexts (kubectl-style) are a pattern for letting a single CLI address multiple target environments (stacks, clusters, accounts, regions) per-command without mutating any ambient / global state. The agent can juggle staging and prod — or team-a-cluster and team-b-cluster — in one session without risking the wrong stack being hit by an in-flight command.

The verbatim canonical statement

From the gcx launch post:

"kubectl-style named contexts let an agent juggle several stacks in one session without mutating global state."

The "without mutating global state" clause is load-bearing. The alternative — a kubectl config use-context … style toggle that edits ~/.kube/config — is exactly what makes agent sessions fragile under concurrent or interleaved plans.

Why this matters for agents specifically

Humans interacting with a CLI have one-at-a-time flow. Agents may:

  • Have multiple in-flight plans being executed concurrently by subagents or background jobs.
  • Interleave commands against different stacks (pull dashboards from staging, push to prod).
  • Spawn subprocesses that inherit ambient state from the parent — a global current-context toggle bleeds into every spawned agent.

A --context staging per-command flag (or equivalent positional gcx --context staging …) pins the target stack to the command, not to a shell session or config file. Agent A can run a prod-context command while Agent B runs a staging-context command without either mutating anything.

The kubectl analogy

kubectl canonicalised both modes:

Mode Mutation
kubectl config use-context prod then kubectl get pods Mutates ~/.kube/config (global state)
kubectl --context=prod get pods No mutation — context is per-command

The second mode is what the gcx commitment extends to the observability-CLI domain. An agent that uses the second mode exclusively never has a surprise-context incident.

What's in a context

A context typically bundles:

  • Stack / cluster / account identity (the which Grafana Cloud stack question).
  • Credentials (OIDC token path, API key, etc.).
  • Default namespace / project (scope within the stack).
  • Endpoint URL (for self-hosted vs cloud variants).

Each context has a name; the agent passes the name via a per-command flag and the CLI dereferences to the bundle at invocation time.

Anti-pattern: ambient current-context toggles

Toggle Problem
gcx switch prod then gcx dashboards push Concurrent agent races on the toggle
export GCX_CONTEXT=prod in a session Sub-shells inherit silently
Config-file current-context: field Cross-session contamination

All three "work" for single-threaded human flow and break under agent concurrency. Per-command named contexts sidestep the entire failure class.

Relationship to the broader agent-ergonomic-CLI stack

Named contexts complement the other commitments:

  • Without stable JSON, concurrent commands produce garbled agent parsing anyway.
  • Without destructive-op confirmation, a mis-routed command can still do damage.
  • Without named contexts, even a well-behaved destructive-op confirmation can apply to the wrong stack because the agent thought it was pointing at staging.

Seen in

Last updated · 433 distilled / 1,256 read