Skip to content

CONCEPT Cited by 2 sources

Machine-readable command catalog

A machine-readable command catalog is a parseable inventory of a CLI's entire surface — every command, every flag, every type, and (in the agent-ergonomic generation) metadata like which commands are destructive. The catalog is a first-class artifact distinct from human-oriented --help text; agents load it once per session and plan against ground-truth capabilities rather than against the LLM's (possibly stale) training data.

The verbatim canonical statement

From the gcx launch post:

"It ships a machine-readable catalog of its own commands and flags, so agents can discover capabilities at runtime instead of guessing from stale training data. For example, it will find commands that result in destructive operations, which require explicit confirmation to reduce agent mistakes."

Two load-bearing specifics: 1. Runtime discovery over stale training data — the agent doesn't have to remember the tool's surface from its pretraining; it looks up the current surface. 2. Capability metadata, not just command names — the catalog tags destructive commands, informing the confirmation-on-destructive-ops guardrail.

What goes in the catalog

Entry Purpose
Command path (gcx slo define …) The verb-noun structure
Flag list with types Enables type-checked plan generation
Required vs optional Plan-time validation
Default values Agent can omit flags safely
Destructive tag Enables confirmation guardrail
Output schema per command Reinforces concepts/json-output-stability
Exit code list per command Reinforces concepts/exit-code-semantics
Deprecated / hidden commands Avoids planning against sunsetting surface

Why this is not just --help

--help text Machine-readable catalog
Human-oriented prose Structured (JSON / YAML / protobuf)
Formatted for terminals Formatted for parsers
One page per command One payload for the whole CLI
No destructive-tag metadata Metadata-rich
Stable shape not guaranteed Stable schema is the whole point
Drift over versions Versioned alongside the binary

A reasonable implementation emits a parseable --help also, but the machine-readable catalog is the contract.

Relationship to MCP tool-lists

The MCP tool-list that servers expose is structurally the same thing as a machine-readable command catalog — a parseable list of capabilities an agent can plan against. The CLI version just lives in the filesystem + the binary rather than over a JSON-RPC transport.

Cloudflare's unified CLI canonicalises the same principle from the developer-platform altitude; the Cloudflare canonical frames it as "MCP 'Code Mode' fits ~3,000 Cloudflare operations in <1,000 tokens" — Cloudflare generates their catalog from the same OpenAPI source as the CLI, so the two stay in sync.

Runtime discovery vs baked-in agent knowledge

Without a catalog, an agent has to guess from memory — which means guessing from whatever the base model was trained on. Problems:

  • Commands may have been renamed since training.
  • New commands may exist that the model doesn't know.
  • Flag shape may have changed in ways the model can't see.
  • Destructive tags are typically invisible to training- time documentation scraping.

The catalog fixes all four by being the authoritative runtime surface.

How it composes with the full agent-ergonomic-CLI stack

  1. Agent starts session → loads catalog.
  2. Plans against the catalog's command list.
  3. Calls a command → gets stable JSON.
  4. Branches on documented exit codes.
  5. If destructive, catalog flags it → agent prompts for confirmation or applies policy (patterns/destructive-operation-confirmation-as-agent-guardrail).
  6. On session end, discards the catalog; next session re-loads (handles tool upgrades automatically).

Seen in

Last updated · 433 distilled / 1,256 read