How Should a Tool Document Its Exit Codes?
From the earlier reference collection. Read the current software blog.
Define each meaningful exit status in terms of outcome, likely cause, and a useful next step.
Describe outcomes, not just numbers
An exit code is the compact result a command returns to its caller. Document the values users can encounter and what each means in practical terms. A table can map zero to successful completion and each nonzero code to a recognizable condition, but do not list values without explaining them. Shell scripts, schedulers, and other programs often use these results to decide whether to continue, retry, or alert someone.
Be precise about what success means. A command that validates input may return zero when the file is structurally valid even if it contains no records. A downloader may return zero only after it saves a complete file, not merely after it reaches a server. State the boundary so that operators do not infer a stronger guarantee than the tool provides.
Give each failure a next action
For every documented failure status, name a likely condition and a sensible next action. For example, a hypothetical code 2 might mean the command-line arguments were invalid; the next step is to check the usage text and correct the option. A code 3 might signal an unreadable input file; check the path and permissions before retrying. These examples should match the program's actual implementation, not a generic convention borrowed from another utility.
Avoid making one code cover unrelated situations if a caller needs to respond differently. If the same status means both “temporary network interruption” and “malformed response,” users cannot safely choose an automatic retry policy. Consider distinct statuses or a structured diagnostic message. If the program intentionally uses a single broad failure code, document the detail available through standard error or a log.
Explain how codes compose
Document whether the tool returns the first encountered error, the most severe error, or a summary status after processing several inputs. A batch command may read ten files, process eight, and fail on two. Does it return success because some work completed, or failure because the whole requested operation was incomplete? That policy matters when a script treats zero as permission to publish results.
Show a small invocation and its result. For instance, document that a validation command returns zero when all named files pass and a nonzero result when any file fails, then show where the failed file is identified. Avoid fabricated transcripts; use output produced by the current version or clearly marked illustrative output. Keep examples consistent with the documented statuses.
Keep reference and behavior aligned
Put a concise code table in the command's help output or manual, then explain less common cases in a longer reference. Specify whether codes are stable across releases and how changes will be announced. If a status is platform-dependent or inherited from a library, identify that boundary rather than promising identical values everywhere.
The useful ending is operational: a reader should know whether the task completed, what condition interrupted it, and what to try next. Review the mapping whenever error handling changes, and make sure examples and automated callers use the same definitions. Clear exit-code documentation turns a number into a decision a person or script can make.