Agent-Aware CLI Design Guidelines

When tasked with building or improving a Command Line Interface (CLI), follow these architectural and design best practices to ensure it serves both human operators (with rich TUIs) and AI agents (with deterministic, machine-readable output).

Core Principles

1. The Dual-Experience Paradigm (DX & AX) This CLI must be designed as a "Dual-Mode" interface, treating both humans and AI agents as first-class users.

   • DX (Developer Experience): Ergonomics for human operators. Emphasizes discoverability, rich TUIs (e.g., Bubbletea, Lipgloss), semantic coloring, and intuitive aliases.
   • AX (Agent Experience): Ergonomics for autonomous AI agents. Emphasizes determinism, strict machine-readable output modes (e.g., --json), headless authentication, aggressive data scoping (limits/filtering), and mutative safety (--dry-run).
   • Environment Overrides: Respect NO_COLOR and [APP]_NO_TUI environment variables to automatically fall back to non-interactive, unstyled modes.

2. Headless-Friendly Authentication

   • Agents cannot complete interactive, browser-based OAuth flows. CLIs must either support headless auth methods (Service Accounts, API Keys via ENV vars, --token flags) OR immediately fail with a clear, machine-readable error instructing the human operator to authenticate manually first.

3. Sane Defaults & Aggressive Filtering

   • Never dump unpaginated or unfiltered lists to stdout. Default to sensible limits (e.g., top 10 items). Provide rich filtering flags (e.g., --status, --mine, --limit) so agents can surgically query exactly what they need without blowing out their token context.

4. Mutative Safety (--dry-run)