Machine-readable command catalog

[apgiorgi]

Part of the Agentic UX spec series. See sibling issues for related buckets.

Motivation

Agents discover capabilities by parsing --help. That's brittle, verbose, and re-tokenized every session. A single canonical machine-readable catalog gives agents a stable surface to enumerate and lets us evolve help text freely.

Spec

Endpoint

• dci commands --json (or dci catalog) emits the entire command tree as one JSON document

Schema (sketch)

{
  "version": "1",
  "cli_version": "1.2.3",
  "commands": [
    {
      "path": ["anomalies", "recent"],
      "summary": "List anomalies in a recent window",
      "flags": [
        {"name": "--window", "type": "duration", "default": "24h", "description": "..."},
        {"name": "--severity", "type": "enum", "choices": ["low","medium","high"]}
      ],
      "output_shape": "AnomalyList",
      "destructive": false,
      "requires_auth": true,
      "agent_friendly": true
    }
  ],
  "shapes": {
    "AnomalyList": { "...JSON schema..." }
  }
}

Properties

• Stable schema versioned via top-level version
• Includes output shape references so agents can validate parsed responses
• Flags destructive and requires_auth per command (feeds Destructive-operation flagging #17)
• Generated from the same source as the actual flag parsing — never hand-maintained

References

• Grafana gcx CLI — machine-readable command catalog for agent runtime discovery: https://grafana.com/blog/get-observability-in-the-terminal-for-you-and-your-agents-with-the-gcx-cli-tool/
• kubectl explain / openapi: prior art for machine-readable command surfaces

Open questions

• Is JSON Schema the right shape language, or do we invent something lighter?
• Where does this live — top-level command, or hidden behind dci internal catalog?
• Do we ship the catalog as a static file for offline discovery too?

Acceptance criteria

• dci commands --json returns the full surface
• Output is generated from the parser, not hand-maintained
• destructive and requires_auth annotations present per command
• Schema versioning policy documented