How Should a CLI Distinguish Warnings from Errors?
From the earlier reference collection. Read the current software blog.
Separate recoverable conditions from failed operations in both wording and exit behavior, so people and scripts can respond sensibly.
Define the difference by outcome
An error means the command could not complete the requested operation or cannot trust its result. A warning means it completed, but noticed something the user may need to review. For example, an unreadable required input is an error; an optional metadata field that is absent may be a warning if the output remains valid without it.
Write down this distinction before adding messages. If the same condition is a warning in one code path and a fatal error in another, users will not know what the status means. The classification should follow the tool's promised behavior, not how alarming the message sounds.
Make messages visibly different
Label messages consistently, such as warning: and error:, and put diagnostics on standard error. Include the affected file or record and a useful next step when one is known. “Warning: 3 rows skipped in observations.csv because timestamp was empty” tells the reader more than “Some data was bad.”
Avoid a wall of warnings that hides the first actionable issue. Group repeated problems by type and show a count, while preserving enough row or identifier detail to investigate. If the user asks for quiet mode, suppress only messages that are safe to suppress; do not hide a fatal explanation.
Let exit status match completion
A command that completes with warnings can usually return success, while a command that cannot fulfill its request should return nonzero. Document any special policy, such as a strict mode that promotes selected warnings to errors. Then automation can choose whether warnings should block a pipeline without guessing from the text.
For instance, a data import might complete while skipping optional descriptive notes and return success with a warning. If it skips records required for a trustworthy total, it should fail or offer an explicit partial-results mode whose status and output make that limitation clear.
Check behavior in scripts
Exercise a clean run, a warning-only run, and a fatal run. Confirm the status code, standard output, and standard error for each. In a shell, if tool ...; then can branch on success, while logs retain the warning details for review. A warning that is printed to standard output may corrupt JSON or CSV intended for another command.
A clear message vocabulary and stable exit behavior make the CLI usable both interactively and unattended. Users can distinguish “look at this” from “the requested result was not produced,” then act accordingly.