cli-opslisted

# CLI Patterns for Agentic Workflows Patterns for building CLI tools that AI assistants and power users can chain, parse, and rely on. ## Philosophy Build CLIs for **agentic workflows** - AI assistants and power users who chain commands, parse output programmatically, and expect predictable behavior. ### Core Principles | Principle | Meaning | Why It Matters | |-----------|---------|----------------| | **Self-documenting** | `--help` is comprehensive and always current | LLMs discover capabilities without external docs | | **Predictable** | Same patterns across all commands | Learn once, use everywhere | | **Composable** | Unix philosophy - do one thing well | Tools chain together naturally | | **Parseable** | `--json` always available, always valid | Machine consumption without parsing hacks | | **Quiet by default** | Data only, no decoration unless requested | Scripts don't break on unexpected output | | **Fail fast** | Invalid input = immediate error | No silent failures or partial results | ### Design Axioms 1. **stdout is sacred** - Only data. Never progress, never logging, never decoration. 2. **stderr is for humans** - Progress bars, colors, tables, warnings live here. 3. **Exit codes have meaning** - Scripts can branch on failure mode. 4. **Help includes examples** - The fastest path to understanding. 5. **JSON shape is predictable** - Same structure across all commands. --- ## Command Architecture ### Structural Pattern ``` <tool> [global-options] <resourc