CLI Error Message Best Practices: Code, Cause, and the Next Command

Write the failure as a stable code, a short title, a cause, and the next command. ERR_DOCKER_OOM is searchable. 'Something went wrong' is not. Link the code to a doc URL that stays valid across minor versions.

Put that text on stderr when the exit status is non-zero. stdout is for the data a script is allowed to parse. Mixing a JSON payload with a human apology breaks every caller that pipes you.

Name the subsystem. 'container auth-worker killed (exit 137)' tells a platform engineer where to look. 'Login failed' tells them to guess. If the next step is raising memory, logging in again, or passing a flag, print that command.

Do not print the stack on a normal TTY failure. Offer it behind a verbose flag, and keep a copy for the probe. People evaluating your CLI will screenshot the first screen. Make that screen the fix, not a Java-style dump.

Frameworks such as Cobra will print the returned error for you. If you also print it at the top of main, every failure appears twice. Silence the framework's printer and own the format, including the 'see --help' hint you just turned off.

Keep the code set small. Four or five codes that never change beat twenty that get renamed between releases. Scripts and agents branch on the code. Humans search it.

A good message helps the developer who is still in the terminal. It does not tell you they were stuck. Pair the message with a probe that stores the code, the command, and their one-line answer, then drafts the issue.

If the hint is wrong, you will see it. Ten people hitting the same code and answering 'I was trying to log in against staging' is a docs bug you can ship today.