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.
Related Prompts
Technical Documentation Writer
Generate clear, comprehensive technical documentation for APIs, functions, systems, or libraries.
Monorepo Build Cache Optimization Guide
Diagnose slow monorepo builds and create a practical optimization plan for local developer workflows, CI pipelines, caching, and dependency boundaries.
API Pagination Filtering and Sorting Design Guide
Design consistent REST API pagination, filtering, sorting, and response metadata patterns for scalable developer-friendly endpoints.