CLI output is an interface

A command-line tool has at least three audiences: a person at a terminal, a shell pipeline, and an automation system checking the exit code. Treating all three as one stream produces noisy tools.

Separate results from narration

Successful data goes to stdout. Progress, warnings, and diagnostics go to stderr. A quiet flag suppresses narration, while a structured output flag changes results deliberately rather than trying to parse decorative text.

• Use exit codes consistently.
• Keep default output stable and line-oriented.
• Disable color when output is not a terminal.
• Include the failed subject and the next useful action in errors.

Prefer boring defaults

The best small tools compose without configuration. They accept stdin where it makes sense, produce one record per line, and avoid interactive prompts unless explicitly requested.

A human-friendly interface does not need spinners everywhere. Clear verbs, predictable paths, and an error that says what remained unchanged are usually more valuable.