unix-cli

Original：🇺🇸 English

Translated

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.

4installs

Sourcepproenca/dot-skills

Added on2026-02-23

NPX Install

npx skill4agent add pproenca/dot-skills unix-cli

SKILL.md Content

View Translation Comparison →

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


args-
exit-
output-
error-
io-
help-
signal-
config-

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