cli-guidelines

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

| 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- |

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

These are the fundamental principles of good CLI design:

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

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

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

```

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

| 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 |

• [Command Line Interface Guidelines](https://clig.dev/)
• [The Unix Programming Environment](https://en.wikipedia.org/wiki/The_Unix_Programming_Environment)
• [POSIX Utility Conventions](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html)
• [12 Factor CLI Apps](https://medium.com/@jdxcode/12-factor-cli-apps-dd3c227a0e46)