CLI Error Message and Exit Code UX Guide
Design developer-friendly command-line error messages with exit codes, stderr/stdout rules, recovery hints, logging behavior, docs, and regression tests.
Prompt Template
You are a developer experience engineer improving command-line tool errors. Create a CLI error message and exit code UX guide for: CLI/product: [tool name and purpose] Primary users: [developers, ops teams, analysts, internal users] Core commands: [install, init, deploy, sync, import, export, test, etc.] Current painful errors: [examples of confusing messages or stack traces] Common failure modes: [auth, config, network, permissions, validation, rate limits, missing files] Scripting needs: [CI usage, shell pipelines, JSON output, automation] Operating systems/shells: [macOS, Linux, Windows, bash, zsh, PowerShell] Logging and telemetry constraints: [privacy, debug logs, trace IDs, support bundles] Docs location: [README, docs site, --help, man page] Backward compatibility constraints: [existing exit codes or integrations] Produce: 1. Error taxonomy with user-facing categories 2. Exit code table with names, numeric codes, and when to use each 3. Message template for short, detailed, JSON, and CI-friendly modes 4. stdout vs stderr rules 5. Recovery hint patterns with examples 6. Before/after rewrites for the painful current errors 7. Logging and support bundle recommendations 8. Documentation updates for --help and troubleshooting pages 9. Test cases to prevent vague or unstable error output 10. Rollout plan that avoids breaking scripts Prioritize clear next actions over clever wording.
Example Output
# CLI Error UX Guide: data-sync
Exit Codes
| Code | Name | Use When |
|---:|---|---|
| 0 | OK | Command completed successfully |
| 2 | USAGE_ERROR | Flags, command syntax, or mutually exclusive options are invalid |
| 3 | CONFIG_ERROR | Config file is missing, unreadable, or malformed |
| 4 | AUTH_ERROR | Token is missing, expired, or lacks scope |
| 5 | NETWORK_ERROR | Request failed after retry budget |
| 6 | REMOTE_VALIDATION_ERROR | API rejected valid local syntax with domain-specific errors |
Rewrite
Before: Error: request failed
After: Could not connect to api.example.com after 3 attempts. Check VPN/proxy access or run data-sync doctor --network.
stdout/stderr
Machine-readable results stay on stdout. Human diagnostics, warnings, trace IDs, and recovery hints go to stderr.
Tips for Best Results
- 💡Audit real support tickets before inventing error categories.
- 💡Keep exit codes stable and document them as part of the CLI contract.
- 💡Include test fixtures for stderr, stdout, JSON output, and CI logs.
Frequently Asked Questions
What is the CLI Error Message and Exit Code UX Guide prompt?
Design developer-friendly command-line error messages with exit codes, stderr/stdout rules, recovery hints, logging behavior, docs, and regression tests. It's a free ChatGPT prompt template from our Coding collection — copy it, fill in the bracketed variables, and paste it into your AI tool.
Which AI tools work with this prompt?
It's written and tested for ChatGPT, Claude and Gemini. Any AI assistant that accepts free-form text prompts will handle it well.
How do I customize this ChatGPT prompt?
Replace the bracketed variables — such as [tool name and purpose], [README, docs site, --help, man page], [existing exit codes or integrations] — with your own details before running it. Audit real support tickets before inventing error categories.
Is this prompt free to use?
Yes. Every prompt on PromptAtlas is free to copy, customize, and use — no signup required.
Related Prompts
Python FileNotFoundError Debugging Prompt
Debug Python FileNotFoundError from the exact traceback, resolved path, working directory, filesystem context, deployment environment, and failing operation.
Python ZeroDivisionError Debugging Prompt
Debug Python ZeroDivisionError from the exact traceback, operand values and types, data path, numeric semantics, runtime context, and failing input.
Python IndentationError Debugging Prompt
Debug Python IndentationError from the exact parser message, whitespace, block structure, source bytes, formatter settings, and runtime version.
Python SyntaxError: Invalid Syntax Debugging Prompt
Debug Python SyntaxError invalid syntax from the exact parser location, surrounding tokens, Python version, generated code, execution context, and minimal reproduction.
Python AttributeError: Object Has No Attribute Debugging Prompt
Debug Python AttributeError from the exact traceback, runtime object type, attribute contract, construction path, version, imports, and minimal reproduction.
Python UnboundLocalError Debugging Prompt
Debug Python UnboundLocalError from the exact traceback, binding scope, assignments, branches, closures, imports, runtime path, and minimal reproduction.