19 hours ago
- A good CLI knows when to be silent; output is an interface, not decoration.
- The --quiet flag should mean print nothing on success unless there is something important; it should not just reduce messages.
- stdout is for data/results; stderr is for logs, warnings, and diagnostics. Never mix them.
- Color output must be controllable via --color=auto/always/never, with auto as default (color only when stdout is a terminal).
- Exit codes are part of the API and should be meaningful (e.g., 0 for success, 1 for diff found, 2 for failure).
- Human-readable output and machine-readable output (JSON) should be separate; JSON is a contract that should not change.
- Hints for next commands should be short and optional; they should not appear in quiet mode, JSON output, or when stdout contains data.
- Silence gives control back to the user, building trust in the tool.