CLI Development Patterns
Modern CLI design patterns for commands, flags, output, errors, signals, config, and distribution.
Rules
Core CLI design rules extracted as discrete, actionable patterns. See rules index for the full list organized by:
- Commands & Naming - Lowercase, typeable command names
- Flags & Arguments - Standard flag conventions (-h, -v, -q, etc.)
- Configuration - Precedence order (flags > env > config > defaults)
- Output & Streams - stdout vs stderr separation
- Error Handling - Actionable error messages with clear fixes
- Signals & Lifecycle - Ctrl-C handling with timeout and force option
- Security - Never read secrets from environment variables
- Distribution - Single binary packaging when possible
References
See references/cli-patterns.md for comprehensive guidance organized by:
- Design & Naming - Command structure, naming conventions, future-proofing
- Flags & Arguments - Standard flags, short forms, boolean negation
- Output & Formatting - stdout/stderr, TTY detection, colors, machine-readable formats
- Error Handling - Exit codes, error messages, signal-to-noise ratio
- Signals & Lifecycle - Ctrl-C handling, cleanup timeouts
- Environment & Config - Standard variables, precedence, naming
- Distribution & Packaging - Single binary distribution, uninstall instructions
- Security & Privacy - Secret handling, telemetry consent
Examples
Positive Trigger
User: "Design CLI commands, flags, and exit codes for a deployment tool."
Expected behavior: Use platform-cli guidance, follow its workflow, and return actionable output.
Non-Trigger
User: "Write a migration plan for PostgreSQL partitioning."
Expected behavior: Do not prioritize platform-cli; choose a more relevant skill or proceed without it.
Troubleshooting
Skill Does Not Trigger
- Error: The skill is not selected when expected.
- Cause: Request wording does not clearly match the description trigger conditions.
- Solution: Rephrase with explicit domain/task keywords from the description and retry.
Guidance Conflicts With Another Skill
- Error: Instructions from multiple skills conflict in one task.
- Cause: Overlapping scope across loaded skills.
- Solution: State which skill is authoritative for the current step and apply that workflow first.
Output Is Too Generic
- Error: Result lacks concrete, actionable detail.
- Cause: Task input omitted context, constraints, or target format.
- Solution: Add specific constraints (environment, scope, format, success criteria) and rerun.
Workflow
- Identify whether the request clearly matches
platform-cli scope and triggers.
- Apply the skill rules and referenced guidance to produce a concrete result.
- Validate output quality against constraints; if gaps remain, refine once with explicit assumptions.
1---2name: platform-cli3description: Design and implementation patterns for building command-line tools with modern UX. Use when designing a CLI, reviewing CLI UX, defining commands and flags, or implementing error handling and signal handling.4---56# CLI Development Patterns78Modern CLI design patterns for commands, flags, output, errors, signals, config, and distribution.910## Rules1112Core CLI design rules extracted as discrete, actionable patterns. See [rules index](rules/_sections.md) for the full list organized by:1314- **Commands & Naming** - Lowercase, typeable command names15- **Flags & Arguments** - Standard flag conventions (-h, -v, -q, etc.)16- **Configuration** - Precedence order (flags > env > config > defaults)17- **Output & Streams** - stdout vs stderr separation18- **Error Handling** - Actionable error messages with clear fixes19- **Signals & Lifecycle** - Ctrl-C handling with timeout and force option20- **Security** - Never read secrets from environment variables21- **Distribution** - Single binary packaging when possible2223## References2425See [references/cli-patterns.md](references/cli-patterns.md) for comprehensive guidance organized by:2627- **Design & Naming** - Command structure, naming conventions, future-proofing28- **Flags & Arguments** - Standard flags, short forms, boolean negation29- **Output & Formatting** - stdout/stderr, TTY detection, colors, machine-readable formats30- **Error Handling** - Exit codes, error messages, signal-to-noise ratio31- **Signals & Lifecycle** - Ctrl-C handling, cleanup timeouts32- **Environment & Config** - Standard variables, precedence, naming33- **Distribution & Packaging** - Single binary distribution, uninstall instructions34- **Security & Privacy** - Secret handling, telemetry consent3536## Examples3738### Positive Trigger3940User: "Design CLI commands, flags, and exit codes for a deployment tool."4142Expected behavior: Use `platform-cli` guidance, follow its workflow, and return actionable output.4344### Non-Trigger4546User: "Write a migration plan for PostgreSQL partitioning."4748Expected behavior: Do not prioritize `platform-cli`; choose a more relevant skill or proceed without it.4950## Troubleshooting5152### Skill Does Not Trigger5354- Error: The skill is not selected when expected.55- Cause: Request wording does not clearly match the description trigger conditions.56- Solution: Rephrase with explicit domain/task keywords from the description and retry.5758### Guidance Conflicts With Another Skill5960- Error: Instructions from multiple skills conflict in one task.61- Cause: Overlapping scope across loaded skills.62- Solution: State which skill is authoritative for the current step and apply that workflow first.6364### Output Is Too Generic6566- Error: Result lacks concrete, actionable detail.67- Cause: Task input omitted context, constraints, or target format.68- Solution: Add specific constraints (environment, scope, format, success criteria) and rerun.6970## Workflow71721. Identify whether the request clearly matches `platform-cli` scope and triggers.732. Apply the skill rules and referenced guidance to produce a concrete result.743. Validate output quality against constraints; if gaps remain, refine once with explicit assumptions.
ravnhq