| name | cli-development |
| description | CLI tool design, argument parsing, interactive prompts, shell completions, cross-platform considerations, and distribution strategies. |
CLI Development Principles
Guidelines for building fast, intuitive, cross-platform CLI tools.
When to Invoke
- Designing CLI tool architecture
- Implementing command hierarchies and argument parsing
- Adding shell completions and interactive features
- Cross-platform distribution planning
Architecture
Command Hierarchy
app <command> [subcommand] [flags] [args]
app task create --priority high "Deploy fix"
app task list --status active --format json
Design Principles
- Startup time < 100ms — lazy-load expensive dependencies.
- Sensible defaults — zero-config for common cases.
- Progressive disclosure — simple interface, advanced flags for power users.
- Machine-readable output —
--format json for scripting.
- Exit codes — 0 = success, 1 = error, 2 = usage error.
Argument Parsing Libraries
| Language | Library | Notes |
|---|
| Go | cobra + pflag | Most popular, auto-completions |
| Rust | clap (derive) | Type-safe, auto-help |
| Python | click or typer | Decorator-based, typer for type hints |
| Node.js | commander or yargs | Mature, well-documented |
Error Handling
-
Helpful error messages — what went wrong, why, how to fix:
Error: config file not found at ~/.myapp/config.yaml
Hint: run 'myapp init' to create a default config
-
--verbose / --debug flags for diagnostic output.
-
Never show stack traces by default — only with --debug.
Shell Completions
Generate completions for bash, zsh, fish, PowerShell. Most CLI frameworks support this.
myapp completion bash > /etc/bash_completion.d/myapp
myapp completion zsh > ~/.zsh/completions/_myapp
Cross-Platform
- Path handling — use
filepath.Join (Go), Path (Python), not string concat.
- Line endings — handle
\r\n on Windows.
- Color support — detect terminal capabilities, respect
NO_COLOR env var.
- Unicode — test with non-ASCII filenames and input.
Distribution
| Method | Best For |
|---|
| Go/Rust binary | Single binary, no runtime dependency |
pip install / npm install -g | Language ecosystem users |
| Homebrew formula | macOS/Linux users |
| Docker image | Containerized environments |
| GitHub Releases | Universal, with checksums |
Testing
For universal testing principles, see .agents/rules/testing-strategy.md. Below: language-specific patterns only.
- Unit test command logic — separate from CLI framework.
- Integration tests — run actual CLI commands, assert exit codes and output.
- Golden file tests — snapshot expected output for complex commands.
Related
- Command Execution Principles @.agents/rules/command-execution-principles.md
- Error Handling Principles .agents/rules/error-handling-principles.md
