CLI Design Guidelines Skill

CLI Design Guidelines

Comprehensive guide to designing command-line interfaces following modern best practices. Based on the Command Line Interface Guidelines. Prioritized by impact to guide CLI development and code review.

When to Apply

Reference these guidelines when:

Creating new CLI tools or adding commands/subcommands
Implementing help text and error handling
Parsing arguments and flags
Designing interactive prompts
Setting up configuration systems
Improving CLI UX and output formatting
Reviewing CLI code for best practices
Refactoring existing command-line tools

Rule Categories by Priority

| Priority | Category | Impact | Prefix | | -------- | --------------------- | ----------- | -------------- | | 1 | The Basics | CRITICAL | basics- | | 2 | AI Agent Integration | CRITICAL | agents- | | 3 | Help & Documentation | CRITICAL | help- | | 4 | Output Formatting | HIGH | output- | | 5 | Error Handling | HIGH | errors- | | 6 | Arguments & Flags | HIGH | args- | | 7 | Interactivity | HIGH | interactive- | | 8 | Signals & Control | HIGH | signals- | | 9 | Robustness | MEDIUM-HIGH | robustness- | | 10 | Subcommands | MEDIUM-HIGH | subcommands- | | 11 | Configuration | MEDIUM | config- | | 12 | Future-proofing | MEDIUM | future- | | 13 | Naming & Distribution | LOW-MEDIUM | naming- | | 14 | Documentation | MEDIUM | help- | | 15 | Analytics | MEDIUM | analytics- |

Quick Reference

1. The Basics (CRITICAL)

basics-use-parsing-library - Use argument parsing library (don't roll your own)
basics-exit-codes - Return 0 on success, non-zero on failure
basics-stdout-stderr - Send output to stdout, messages/errors to stderr
basics-help-flags - Support -h and --help flags
basics-full-flags - Have full-length versions of all flags

2. AI Agent Integration (CRITICAL)

agents-json-required - Always support --json for agent consumption
agents-structured-errors - Provide structured error information
agents-exit-codes-documented - Document all exit codes
agents-no-prompts-default - Avoid interactive prompts, use flags
agents-yes-flag - Provide --yes flag to skip confirmations
agents-progress-to-stderr - Send progress to stderr, data to stdout
agents-deterministic-output - Ensure deterministic, versioned output
agents-dry-run - Provide --dry-run for safety
agents-help-machine-readable - Make help text machine-readable

3. Help & Documentation (CRITICAL)

help-concise-default - Display concise help when run with no args
help-lead-examples - Lead with examples in help text
help-suggest-corrections - Suggest corrections for typos

4. Output Formatting (HIGH)

output-tty-detection - Check if TTY before using colors/animations
output-json-flag - Support --json for machine-readable output
output-plain-flag - Support --plain for script-friendly output
output-state-changes - Tell the user when you change state
output-pager - Use a pager for long output

5. Error Handling (HIGH)

errors-rewrite-for-humans - Catch errors and rewrite for humans
errors-signal-to-noise - Maintain signal-to-noise ratio in error output
errors-important-info-end - Put important info at end of output
errors-exit-code-mapping - Map exit codes to failure modes

6. Arguments & Flags (HIGH)

args-prefer-flags - Prefer flags over positional arguments
args-standard-names - Use standard flag names (-f/--force, -n/--dry-run)
args-no-secrets-flags - Don't read secrets from flags (use files or stdin)
args-stdin-stdout - Accept - to read from stdin / write to stdout
args-order-independent - Make flags order-independent

7. Interactivity (HIGH)

interactive-tty-check - Only prompt if stdin is a TTY
interactive-no-input-flag - Support --no-input to disable prompts
interactive-password-no-echo - Don't echo passwords as user types

8. Signals & Control (HIGH)

signals-exit-on-ctrl-c - Exit immediately on Ctrl-C
signals-crash-only-design - Design for crash-only operation

9. Robustness (MEDIUM-HIGH)

robustness-100ms-response - Print something within 100ms
robustness-progress-indicators - Show progress for long operations
robustness-validate-early - Validate input early, fail fast
robustness-idempotent - Make operations idempotent/recoverable
robustness-network-timeouts - Set timeouts on network operations

10. Subcommands (MEDIUM-HIGH)

subcommands-consistency - Be consistent across subcommands (same flags, output)
subcommands-consistent-verbs - Use consistent verbs (create/get/update/delete)
subcommands-no-abbreviations - Don't allow arbitrary abbreviations
subcommands-no-catch-all - Don't have catch-all subcommands

11. Configuration (MEDIUM)

config-precedence - Follow precedence: Flags > Env vars > Project > User > System
config-xdg-spec - Follow XDG Base Directory spec for config locations

12. Future-proofing (MEDIUM)

future-additive-changes - Keep changes additive (add flags, don't change behavior)

13. Naming & Distribution (LOW-MEDIUM)

naming-simple-memorable - Use simple, memorable, lowercase command names
naming-distribute-single-binary - Distribute as single binary when possible

14. Help & Documentation (MEDIUM)

help-web-documentation - Provide web-based documentation

15. Analytics (MEDIUM)

analytics-no-phone-home - Don't phone home without consent

Philosophy

These are the fundamental principles of good CLI design:

Human-first design - Design for humans, optimize for machines second
Simple parts that work together - Composable via stdin/stdout/stderr, exit codes, JSON
Consistency across programs - Follow existing patterns users already know
Saying (just) enough - Not too much output, not too little
Ease of discovery - Help users learn through suggestions, examples, clear errors
Conversation as the norm - CLI interaction is iterative—guide the user through it
Robustness - Handle failures gracefully, be responsive, feel solid
Empathy - Be on the user's side, help them succeed
Chaos - Know when to break the rules—do so with intention

Structure

This skill contains:

rules/ - Focused, actionable rules
- Each rule has frontmatter (title, impact, tags)
- Includes incorrect/correct code examples
- TypeScript/JavaScript examples with modern libraries
references/ - Comprehensive topic guides (for deeper context)
- Background documentation and detailed explanations
- Loaded by agents only when deeper understanding is needed
AGENTS.md - Complete compiled guide (auto-generated from rules)
- All rules in one document
- Full table of contents
- Searchable reference

How to Use

Read individual rule files for specific guidance:

rules/basics-use-parsing-library.md
rules/agents-json-required.md
rules/output-tty-detection.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and implementation details

For deeper background, see reference files:

references/philosophy.md
references/basics.md

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

Common Argument Parsing Libraries

| Language | Libraries | | -------------- | ---------------------- | | Node | oclif, commander | | Go | Cobra, urfave/cli | | Python | Click, Typer, argparse | | Rust | clap | | Ruby | TTY | | Java | picocli | | Swift | swift-argument-parser | | Multi-platform | docopt |

Agent Skills: CLI Design Guidelines

Install this agent skill to your local

Skill Files