LLM-Friendly CLI Design Guide

15 rules for building CLIs that AI agents can use effectively, derived from research across clig.dev, the "Let Me Speak Freely?" paper (arXiv:2408.02442), the "How Do LLMs Fail In Agentic Scenarios?" paper (arXiv:2512.07497), and analysis of gh, kubectl, aws, docker CLI patterns.

Why CLIs Beat curl for LLMs

• "Let Me Speak Freely?" showed 10-15% reasoning degradation when forcing structured output (JSON) vs free-form generation — curl requires simultaneous URL/header/JSON/auth management
• 900-trace failure analysis found curl top failures: JSON escaping disasters, URL encoding errors, hallucinated endpoints, body/query param confusion
• CLIs are 20-50 tokens per command vs 100-300 for equivalent curl (up to 160x token reduction)
• "Human users adapt to CLI changes; AI agents fail catastrophically" — every output field, exit code, and flag is an API contract

The 15 Rules

1. Noun-verb subcommand structure

myctl resource action — turns discovery into deterministic tree search via --help. Follow gh pr list, kubectl get pods, aws s3 ls. Avoid flat verb-only (create-user, list-users) or mixed patterns.

2. --json flag on every data-producing command

JSON to stdout, all noise (progress, warnings, logs) to stderr. Keep JSON flat, consistent types. JSONL for streaming. --json field1,field2 with --jq for inline filtering (like gh).