How Should a CLI Handle an Unknown Option?
From the earlier reference collection. Read the current software blog.
Reject unrecognized options with concise guidance and a failing status, rather than silently proceeding under an unintended configuration.
Treat an unknown option as an input error
A command-line option can change the meaning of a run: which file is read, whether output is overwritten, or what time range is selected. If a user mistypes --formt json and the program ignores it, the tool may continue with a default format and produce output that looks plausible but is wrong for the next step. Rejecting the option makes the mistake visible at the point it occurs.
The command should stop before opening inputs or changing outputs. An unknown-option error is not a request to guess what the user intended.
Keep the message short and actionable
A useful response identifies the unrecognized token and points to help. For example: report: unrecognized option '--formt'. Try 'report --help'. Include a usage synopsis if it fits, but avoid dumping every option into the error. The full help page remains the right place for detailed descriptions and examples.
If the tool has subcommands, guide the user to the relevant help entry where practical. For example, report import --help can be more useful than a generic list of unrelated commands. Do not suggest a correction as fact unless the match is sufficiently clear; suggestions are hints, not permission to continue.
Use a nonzero status consistently
Return a nonzero exit status for the error so a shell script can detect it. A pipeline such as report --formt json | publish should not publish output from a command that failed to accept its requested configuration. The exact status convention can vary, but it should be documented and stable enough for callers to rely on.
Do not print a warning and then continue with guessed defaults. That turns a clear syntax problem into an ambiguous data problem later. Keep error text on standard error, especially when standard output may contain machine-readable results.
Check the behavior at the boundary
Test representative mistakes: an unknown long option, a misspelled short option, and an option placed after a subcommand. Verify that each case exits unsuccessfully, emits no normal result, and performs no side effect such as creating an output file. Also check that valid abbreviations are handled only if the interface intentionally supports them.
A strict response saves time for both interactive users and automation. It turns a typo into a small, local correction instead of a run that appears successful while using a different configuration.