Agent-First CLI Design

Principles for building CLIs that AI agents can use reliably. Adapted from Justin Poehnelt's "Rewrite your CLI for AI Agents", based on patterns from the Google Workspace CLI.

Core tension: Human DX optimizes for discoverability and forgiveness. Agent DX optimizes for predictability and defense-in-depth. Great CLIs serve both.

1. Machine-Readable Output is Table Stakes

Every command must support structured output. Agents cannot reliably parse tables, colored text, or free-form prose.

Requirements:

• Support --output json (or make JSON the default)
• Use an environment variable fallback: OUTPUT_FORMAT=json
• Auto-detect: default to JSON when stdout is not a TTY
• Wrap responses in a stable envelope with consistent fields
• Use deterministic key ordering for reproducible output