Build a CLI people can recover from
Design command output and exit codes for people debugging a failure and scripts running unattended.
A command-line tool teaches people how to use it through its output. When a command fails, the output should identify the failed operation, the input involved, and a next step that the user can act on. “Could not read settings.toml. Check the path or pass –config with an existing file” gives someone a way forward.
Keep data and diagnostics apart
Write successful machine-readable output to standard output. Write progress and error messages to standard error. That distinction lets a script capture a JSON result without accidentally parsing a progress message. Use a nonzero exit code when the command fails, so automation can stop before it acts on incomplete output.
Test the unhappy path
Try the command with a missing file, an unreadable file, and malformed input. Verify the message and the exit code for each. Then pipe a successful response into the next command a user is likely to run. If recovery requires a command that can overwrite data, make the effect explicit before the tool makes changes. These checks catch interface problems that a clean run can hide.