UNIX/POSIX Standards CLI Best Practices

Comprehensive guidelines for building command-line tools that follow UNIX conventions, designed for AI agents and LLMs. Contains 44 rules across 8 categories, prioritized by impact from critical (argument handling, exit codes, output streams) to incremental (configuration and environment).

When to Apply

Reference these guidelines when:

• •Writing new CLI tools in any language
• •Parsing command-line arguments and flags
• •Deciding what goes to stdout vs stderr
• •Choosing appropriate exit codes
• •Handling signals like SIGINT and SIGTERM

Rule Categories by Priority

Quick Reference

1. Argument & Flag Design (CRITICAL)

• •args-use-getopt - Use standard argument parsing libraries
• •args-provide-long-options - Provide long options for all short options
• •args-support-double-dash - Support double-dash to terminate options
• •args-require-help-version - Implement --help and --version options
• •args-prefer-flags-over-positional - Prefer flags over positional arguments
• •args-use-standard-flag-names - Use standard flag names
• •args-never-read-secrets-from-flags - Never read secrets from command-line flags
• •args-support-option-bundling - Support option bundling

2. Exit Codes (CRITICAL)

• •exit-zero-for-success - Return zero for success only
• •exit-use-standard-codes - Use standard exit codes
• •exit-signal-codes - Use 128+N for signal termination
• •exit-partial-success - Handle partial success consistently
• •exit-distinguish-error-types - Distinguish error types with different exit codes

3. Output Streams (CRITICAL)

• •output-stdout-for-data - Write data to stdout only
• •output-stderr-for-errors - Write errors and diagnostics to stderr
• •output-detect-tty - Detect TTY for human-oriented output
• •output-provide-machine-format - Provide machine-readable output format
• •output-line-based-text - Use line-based output for text streams
• •output-respect-no-color - Respect NO_COLOR environment variable

4. Error Handling (HIGH)

• •error-include-program-name - Include program name in error messages
• •error-actionable-messages - Make error messages actionable
• •error-use-strerror - Use strerror for system errors
• •error-avoid-stack-traces - Avoid stack traces in user-facing errors
• •error-validate-early - Validate input early and fail fast

5. I/O & Composition (HIGH)

• •io-support-stdin - Support reading from stdin
• •io-write-to-stdout - Write output to stdout by default
• •io-be-stateless - Design stateless operations
• •io-handle-binary-safely - Handle binary data safely
• •io-atomic-writes - Use atomic file writes
• •io-handle-multiple-files - Handle multiple input files consistently

6. Help & Documentation (MEDIUM-HIGH)

• •help-show-usage-on-error - Show brief usage on argument errors
• •help-structure-help-output - Structure help output consistently
• •help-show-defaults - Show default values in help
• •help-include-examples - Include practical examples in help
• •help-version-format - Format version output correctly

7. Signals & Robustness (MEDIUM)

• •signal-handle-sigint - Handle SIGINT gracefully
• •signal-handle-sigterm - Handle SIGTERM for clean shutdown
• •signal-handle-sigpipe - Handle SIGPIPE for broken pipes
• •signal-cleanup-on-second-interrupt - Skip cleanup on second interrupt

8. Configuration & Environment (MEDIUM)

• •config-follow-xdg - Follow XDG Base Directory Specification
• •config-precedence-order - Apply configuration in correct precedence order
• •config-env-naming - Use consistent environment variable naming
• •config-never-store-secrets - Never store secrets in config files or environment
• •config-respect-standard-vars - Respect standard environment variables

How to Use

Read individual reference files for detailed explanations and code examples:

• •Section definitions - Category structure and impact levels
• •Rule template - Template for adding new rules

Reference Files