Exit with zero only when the command did everything it was asked

How to do it

Scripts, CI jobs and agents read the exit code, not the text. A tool that prints an error and exits 0 lets a broken deploy carry on. POSIX defines 0 as success and leaves 126, 127 and codes above 128 to the shell. Keep 2 for wrong usage, as many tools do. Give each failure a meaning a caller can act on, such as "not found" or "try again". Keep error types stable asks the same of APIs. On Ctrl+C, stop cleanly and exit 130. A partial success is a failure, with the details in the output.

Examples

Python example

import sys

EXIT_OK, EXIT_FAILED, EXIT_USAGE, EXIT_NOT_FOUND, EXIT_RETRY = 0, 1, 2, 3, 4

def main() -> int:
    try:
        invoice = client.fetch(args.invoice_id)
    except NotFound:
        print(f"invoice {args.invoice_id} not found", file=sys.stderr)
        return EXIT_NOT_FOUND
    except ServiceUnavailable:
        print("service unavailable, try again later", file=sys.stderr)
        return EXIT_RETRY
    print(invoice.number)
    return EXIT_OK

if __name__ == "__main__":
    sys.exit(main())

Go example

const (
	exitOK       = 0
	exitFailed   = 1
	exitUsage    = 2
	exitNotFound = 3
	exitRetry    = 4
)

func main() {
	invoice, err := client.Fetch(invoiceID)
	switch {
	case errors.Is(err, ErrNotFound):
		fmt.Fprintf(os.Stderr, "invoice %s not found\n", invoiceID)
		os.Exit(exitNotFound)
	case err != nil:
		fmt.Fprintln(os.Stderr, "service unavailable, try again later")
		os.Exit(exitRetry)
	}
	fmt.Println(invoice.Number)
}

How to check

A test runs each command with a missing file, a wrong flag and a server that answers 500. Each run exits with its documented non-zero code. A successful run exits 0, and the help text lists every code.

Sources

• POSIX.1-2024, Exit Status for Commands

Related rules

• API-17 Keep error types stable in API design