name

unix-cli

description

UNIX command-line interface guidelines for building tools that follow POSIX conventions, proper exit codes, stream handling, and the UNIX philosophy. This skill should be used when writing, reviewing, or designing CLI tools to ensure they integrate properly with the UNIX tool chain. Triggers on tasks involving CLI tools, command-line arguments, exit codes, stdout/stderr, signals, or shell scripts.

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

Priority	Category	Impact	Prefix
1	Argument & Flag Design	CRITICAL	`args-`
2	Exit Codes	CRITICAL	`exit-`
3	Output Streams	CRITICAL	`output-`
4	Error Handling	HIGH	`error-`
5	I/O & Composition	HIGH	`io-`
6	Help & Documentation	MEDIUM-HIGH	`help-`
7	Signals & Robustness	MEDIUM	`signal-`
8	Configuration & Environment	MEDIUM	`config-`

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

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information