building-command-line-interfaces

Building Command-Line Interfaces

Command-Line Interface fixes the contract and its eight modules hold the rules. This skill covers the judgement of applying them, not the rules themselves.

Ask What the Caller May Conclude

Choosing an exit status is one question asked in one direction: what may a caller conclude from this number?

Work forward from the caller, never backward from the code path. A tempting status is usually a description of what went wrong internally, which is the body's job. The number answers only whether the result can be trusted, and the hardest case is the one worth slowing down for — deciding whether this path is a result the caller should act on, or a failure to produce one. When unsure, ask whether a script that treated this as a real answer would then do something wrong. If it would, the path is not a result.

Assume the Runtime Is Wrong

Every runtime and every command framework breaks part of this contract by default, in a different place and for a different reason. A tool is not conforming because nobody changed anything; it conforms because someone overrode a default and left a test behind proving it stayed overridden.

The defaults worth checking first, because they are the ones that silently look fine:

• What the process reports when it panics, throws, or aborts — commonly a status the contract reserves for a result.
• What happens when a reader closes the pipe, which is the single most common real defect.
• What a death by signal reports, which frameworks tend to collapse into a result status.
• Which stream the usage text reaches on a failed invocation, since a framework often writes it through a stream the calling program supplies.

Set each one explicitly at construction rather than relying on it. A default that happens to be right today is not a decision, and the next dependency upgrade is free to change it.