unix-cli
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 librariesargs-provide-long-options- Provide long options for all short optionsargs-support-double-dash- Support double-dash to terminate optionsargs-require-help-version- Implement --help and --version optionsargs-prefer-flags-over-positional- Prefer flags over positional argumentsargs-use-standard-flag-names- Use standard flag namesargs-never-read-secrets-from-flags- Never read secrets from command-line flagsargs-support-option-bundling- Support option bundling
2. Exit Codes (CRITICAL)
exit-zero-for-success- Return zero for success onlyexit-use-standard-codes- Use standard exit codesexit-signal-codes- Use 128+N for signal terminationexit-partial-success- Handle partial success consistentlyexit-distinguish-error-types- Distinguish error types with different exit codes
3. Output Streams (CRITICAL)
output-stdout-for-data- Write data to stdout onlyoutput-stderr-for-errors- Write errors and diagnostics to stderroutput-detect-tty- Detect TTY for human-oriented outputoutput-provide-machine-format- Provide machine-readable output formatoutput-line-based-text- Use line-based output for text streamsoutput-respect-no-color- Respect NO_COLOR environment variable
4. Error Handling (HIGH)
error-include-program-name- Include program name in error messageserror-actionable-messages- Make error messages actionableerror-use-strerror- Use strerror for system errorserror-avoid-stack-traces- Avoid stack traces in user-facing errorserror-validate-early- Validate input early and fail fast
5. I/O & Composition (HIGH)
io-support-stdin- Support reading from stdinio-write-to-stdout- Write output to stdout by defaultio-be-stateless- Design stateless operationsio-handle-binary-safely- Handle binary data safelyio-atomic-writes- Use atomic file writesio-handle-multiple-files- Handle multiple input files consistently
6. Help & Documentation (MEDIUM-HIGH)
help-show-usage-on-error- Show brief usage on argument errorshelp-structure-help-output- Structure help output consistentlyhelp-show-defaults- Show default values in helphelp-include-examples- Include practical examples in helphelp-version-format- Format version output correctly
7. Signals & Robustness (MEDIUM)
signal-handle-sigint- Handle SIGINT gracefullysignal-handle-sigterm- Handle SIGTERM for clean shutdownsignal-handle-sigpipe- Handle SIGPIPE for broken pipessignal-cleanup-on-second-interrupt- Skip cleanup on second interrupt
8. Configuration & Environment (MEDIUM)
config-follow-xdg- Follow XDG Base Directory Specificationconfig-precedence-order- Apply configuration in correct precedence orderconfig-env-naming- Use consistent environment variable namingconfig-never-store-secrets- Never store secrets in config files or environmentconfig-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 |
More from pproenca/dot-skills
zod
Zod schema validation best practices for type safety, parsing, and error handling. This skill should be used when defining z.object schemas, using z.string validations, safeParse, or z.infer. This skill does NOT cover React Hook Form integration patterns (use react-hook-form skill) or OpenAPI client generation (use orval skill).
2.0Kclean-architecture
Clean Architecture principles and best practices from Robert C. Martin's book. This skill should be used when designing software systems, reviewing code structure, or refactoring applications to achieve better separation of concerns. Triggers on tasks involving layers, boundaries, dependency direction, entities, use cases, or system architecture.
1.4Kemilkowal-animations
Emil Kowalski's animation best practices for web interfaces. Use when writing, reviewing, or implementing animations in React, CSS, or Framer Motion. Triggers on tasks involving transitions, easing, gestures, toasts, drawers, or motion.
917vitest
Vitest testing framework patterns for test setup, async testing, mocking with vi.*, snapshots, and test performance (formerly test-vitest). This skill should be used when writing or debugging Vitest tests. This skill does NOT cover TDD methodology (use test-tdd skill), API mocking with MSW (use test-msw skill), or Jest-specific APIs.
906typescript
This skill should be used when the user asks to "optimize TypeScript performance", "speed up tsc compilation", "configure tsconfig.json", "fix type errors", "improve async patterns", or encounters TS errors (TS2322, TS2339, "is not assignable to"). Also triggers on .ts, .tsx, .d.ts file work involving type definitions, module organization, or memory management. Does NOT cover TypeScript basics, framework-specific patterns, or testing.
820nuqs
nuqs (type-safe URL query state) best practices for Next.js applications. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, or Next.js routing with state.
734