better-cli

Better CLI: Build CLIs for Humans and AI Agents

Build command-line tools that are delightful for humans at a terminal AND reliable for AI agents in automation pipelines. These goals are orthogonal, not conflicting.

This skill targets command-based CLIs (think git, docker, gh, kubectl) — tools with subcommands, flags, and structured output. It is not about full-screen TUI applications or interactive dashboards.

When to Use

• Building a new CLI tool in any language
• Improving or refactoring an existing CLI to be more human- and agent-friendly
• Adding commands, flags, or output formats to an existing CLI
• Reviewing CLI code for usability, composability, or agent-readiness

NOT for: TUI/full-screen terminal apps, GUI applications, REST/GraphQL API design, shell scripting

Core Philosophy

Human DX optimizes for discoverability and forgiveness. Agent DX optimizes for predictability and defense-in-depth. A great CLI does both.

The Golden Rule: Output that tells you what to do next. Every command's output — success or failure — should give the user (human or AI agent) enough context to know what their next action should be. An agent reading your CLI's output should be able to continue its workflow without guessing.

flowchart LR
  H[Human at Terminal] --> TTY{stdout is TTY?}
  A[AI Agent] --> TTY
  TTY -->|Yes| RICH[Rich: colors, tables,\nprogress bars, prompts]
  TTY -->|No| CLEAN[Clean: JSON, no ANSI,\nno prompts, parseable]
  RICH --> CORE[Same data, same exit codes,\nsame semantics]
  CLEAN --> CORE

The Rules (Priority Order)

P0: Critical — Every CLI Must Do These

1. stdout for data, stderr for everything else

stdout  ->  primary output (results, JSON, file contents) — for piping
stderr  ->  errors, warnings, progress, diagnostics, prompts — for humans

This is the single most important rule. It enables piping, redirection, and agent parsing. Never mix.

2. Exit 0 on success, non-zero on failure