English for Writing Clear Exit Codes and CLI Error Messages

A command-line tool’s error messages are often the only English a user reads before they either fix the problem or give up and file an issue. Writing them well is a specific skill: terse enough to fit a terminal, but specific enough to be actionable. This guide covers the phrasing conventions for CLI error messages, help text, and exit code documentation.

Key Vocabulary

Exit code — the numeric status a program returns when it finishes, conventionally 0 for success and nonzero for various failure categories, used by scripts to detect success or failure programmatically. “We return exit code 2 specifically for configuration errors, distinct from exit code 1 for general runtime errors, so CI scripts can handle each case differently.”

Actionable error message — an error message that tells the user not just what went wrong, but what to do about it. “Instead of ‘invalid input,’ the actionable version says ‘invalid input: expected a number for —timeout, got “abc”. Try —timeout 30.’”

Usage line — the short summary shown when a CLI is invoked incorrectly, showing the expected syntax. “When required arguments are missing, we print the usage line: ‘Usage: mytool deploy —env <staging|production> [—dry-run]’.”

Verbose / debug flag — a flag that enables additional diagnostic output, referenced in error messages to tell users how to get more detail. “The error message ends with ‘Run with —verbose for the full stack trace,’ so users know how to get more information without us dumping it by default.”

Silent failure — a program exiting without any output or a nonzero exit code despite something going wrong, which is a usability bug because the user has no idea what happened. “This was a silent failure — the script exited 0 even though the upload failed, because we weren’t checking the response status. That’s now fixed, and it exits 1 with a clear message.”

Common Phrases

• “Error: [specific problem]. [Specific suggested fix].”
• “Expected [X], got [Y].”
• “Run with —verbose for more detail.”
• “Exit code [N]: [category of failure].”
• “See [command] —help for usage.”

Example Sentences

Writing an actionable error instead of a vague one: “Error: could not connect to database at localhost:5432 (connection refused). Is the database running? Try ‘docker compose up db’ or check DATABASE_URL in your .env file.”

Documenting exit codes in a README or help output: “Exit codes: 0 = success, 1 = general error, 2 = invalid arguments, 3 = configuration file not found, 4 = network error. Scripts calling this tool can branch on these codes to handle failures differently.”

Writing a usage line that stays terse but complete: “Usage: backup-cli restore —snapshot [—target ] [—dry-run] Run ‘backup-cli restore —help’ for a full list of options.”

Fixing a silent failure and explaining the change in a changelog: “Fixed: the sync command previously exited with code 0 even when individual file uploads failed silently in the background. It now waits for all uploads to complete, reports failures explicitly, and exits with code 1 if any file failed to sync.”

Professional Tips

• Structure error messages as problem + specific fix, not just problem — “expected a number, got ‘abc’. Try —timeout 30” is dramatically more useful than “invalid input.”
• Document your exit code scheme somewhere findable (README, --help, man page) — scripts and CI pipelines depend on exit codes being stable and documented, not guessed at.
• Never let a program exit successfully after a partial failure — if anything went wrong, the exit code and message both need to say so, even if the overall operation “mostly” succeeded.
• Keep the first line of an error terse (it’s what appears in a scrollback buffer or a CI log summary), and put extended detail behind a --verbose flag rather than dumping everything by default.
• Use consistent phrasing across all your tool’s error messages — if you use “Expected X, got Y” in one place, use the same structure everywhere, so users learn to parse your errors quickly.

Practice Exercise

1. Rewrite a vague error message (“invalid config”) into an actionable one with a specific suggested fix.
2. Write a short exit code table for a hypothetical CLI tool with four failure categories.
3. Write a changelog entry describing a fix for a silent failure bug.

Bridging the Gap: Specific Language for Non-Native Speakers

Writing clear exit codes and CLI error messages is a cornerstone of good technical communication. It’s not just about stating what went wrong; it’s about guiding the user toward a solution. However, for developers whose first language isn’t English, navigating the nuances of professional phrasing can be particularly challenging. Often, literal translations or overly formal language can result in messages that are technically accurate but practically unhelpful – confusing and frustrating for anyone trying to quickly resolve an issue. Let’s consider how this applies when receiving a code review comment, for example. Imagine you’ve submitted a PR containing a new script designed to automate database backups. During the review, your senior engineer leaves a comment: “Exit code 13 indicates a permission denied error. This needs more context – why the user doesn’t have access.” A direct translation of “permission denied” might be perfectly understandable, but the added emphasis on “why” and the instruction to provide more context are crucial for someone learning English in a professional setting. It’s about understanding the expectation that you need to explain the root cause, not just report the symptom.

Another common scenario arises during Slack conversations when troubleshooting issues with CLI tools. Let’s say a junior developer posts: “The command failed with code 255.” A helpful response, aimed at someone still developing their English skills, could be: “Okay, that’s a general error code. Could you please tell us specifically what the command was and what it was trying to do? Knowing the exact command helps us diagnose the problem more quickly.” The use of phrases like “specifically” and “helps us diagnose” provides clearer guidance than simply stating the error code itself. Similarly, when crafting PR descriptions for new CLI utilities or scripts, avoid overly technical jargon unless absolutely necessary. Instead, focus on clear, actionable instructions framed in plain English. For instance, instead of “Utilize grep -i to filter results,” consider: “Use this command to find all lines containing the specified keyword, ignoring case.”

The key is to build language proficiency incrementally. Start with core phrases like “error,” “failure,” “permission denied,” “invalid input,” and “unable to complete” – these are universally understood. Then, layer in more sophisticated phrasing related to troubleshooting: “root cause,” “diagnose,” “further investigation required,” “verify the configuration,” and “check for dependencies.” Most importantly, remember that clarity always trumps precision when communicating technical information. A simple, well-phrased message is far more effective than a technically correct but confusing one. Aim for sentences that a non-native speaker can readily understand and act upon—a goal that significantly reduces support requests and improves collaboration within a development team.

Finally, don’t be afraid to ask for clarification if you’re unsure about a particular phrase or term. It’s far better to admit confusion than to risk misinterpreting instructions and creating further problems. A quick question like, “Could you explain what ‘root cause’ means in this context?” demonstrates proactive learning and a commitment to clear communication.