cli-guidelines-resources-04

Error handling in CLI tools should provide actionable guidance: describe what went wrong, why it happened, and what the user can do next. Use distinct error codes, consistent exit statuses, and example-driven scenarios for common failures to reduce confusion and improve recoverability.

Robust CLI design combines descriptive error handling, clear exit codes, human-friendly messaging, and defensive patterns. These prevent confusion during failures, ensure consistent behavior across commands, and guide users toward solutions when things go wrong.

Apply resource-driven CLI design patterns covering help content, output formatting, error messages, arguments, flags, and subcommands. Consistent structure makes CLI behavior predictable, improves discoverability, and ensures users receive actionable feedback at every stage.

Exit codes communicate outcome to downstream processes and scripts. Assign distinct codes for different failure types—invalid input, missing resources, permission errors—so users and automation can respond appropriately. Pair codes with clear, descriptive error messages.

TTY-aware behavior detects interactive terminals and adjusts output accordingly: use formatting and colors for human readers, plain text for piping. This ensures your CLI integrates smoothly into workflows, automation scripts, and provides appropriate feedback based on context.

Use interactivity and prompts when CLI tools require user confirmation, multiple choices, or sensitive input. Implement TTY detection to disable prompts in non-interactive contexts like scripts or automation, ensuring your tool works reliably across different execution environments.