Advisor CLI Champion

An agent focused on building high-quality command-line interfaces and developer tools, covering argument parsing, interactive prompts, output formatting, shell integration, and CLI distribution across platforms.

When to Use This Agent

Choose CLI Champion when:

• Building command-line tools with proper argument parsing and help text
• Creating interactive CLI experiences with prompts and progress indicators
• Designing CLI architectures with subcommands and plugins
• Implementing shell completion, configuration files, and output formatting
• Distributing CLI tools across platforms (npm, pip, homebrew, binaries)

Consider alternatives when:

• Building web applications with no CLI component (use a web dev agent)
• Creating shell scripts without a tool framework (use a bash scripting agent)
• Building GUI applications (use a desktop or frontend agent)

Quick Start

Copy
# .claude/agents/advisor-cli-champion.yml
name: CLI Champion
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
prompt: |
  You are a CLI development expert. Build professional command-line
  tools with proper argument parsing, help text, subcommands,
  interactive prompts, and formatted output. Follow CLI UX
  conventions and make tools that developers love to use.

Example invocation:

Copy
claude --agent advisor-cli-champion "Build a CLI tool for managing
  database migrations with subcommands: create, up, down, status.
  Include interactive prompts for dangerous operations, color
  output, and shell completion support."

Core Concepts

CLI Architecture Patterns

CLI Entry Point
├── Argument Parser (commander, click, cobra)
├── Subcommand Router
│   ├── create → CreateCommand handler
│   ├── status → StatusCommand handler
│   └── deploy → DeployCommand handler
├── Configuration Loader (.rc file, env vars, flags)
├── Output Formatter (table, JSON, plain text)
└── Error Handler (exit codes, error messages)

CLI UX Conventions

Convention	Description	Example
--help / -h	Display usage information	Always present
--version / -V	Show tool version	Semantic version
--verbose / -v	Increase output detail	Stackable: -vvv
--quiet / -q	Suppress non-essential output	Opposite of verbose
--output / -o	Output format selection	--output json
--dry-run	Preview without executing	Show what would happen
--force / -f	Skip confirmation prompts	Dangerous operations
--config	Custom config file path	Override default location

Exit Code Standards

0    Success
1    General error
2    Misuse of shell command / invalid arguments
126  Command not executable
127  Command not found
128+ Fatal error signal (128 + signal number)

Configuration

Parameter	Description	Default
language	Implementation language	TypeScript/Node.js
parser	Argument parser library	Commander.js / Click
output_formats	Supported output formats	table, json, plain
interactive	Support interactive prompts	true
completion	Shell completion support	bash, zsh, fish
config_format	Config file format	YAML
distribution	Distribution method	npm / pip / binary

Best Practices

1. Make every destructive action require explicit confirmation unless --force is passed. Deleting data, overwriting files, and modifying production systems should prompt the user: "This will delete 42 migration files. Continue? [y/N]." Default to the safe option (N). The --force flag skips confirmation for scripting contexts. Never make a destructive action the default behavior of any command.

2. Support both human-readable and machine-parseable output. Default to formatted, colorful output for humans (--output table). Support --output json for scripting and piping to other tools. Never mix human-readable decorations (colors, progress bars, spinners) into machine output. Check stdout.isTTY to auto-detect context and adjust output format accordingly.

3. Write comprehensive help text with examples. Every command and flag should have a one-line description. The main --help should include 2-3 usage examples showing common workflows. Examples teach faster than descriptions. Place the most common usage pattern first. Users who read --help are already invested in using your tool—make their experience great.

4. Load configuration from multiple sources with clear precedence. Support: default values → config file (.toolrc) → environment variables → command-line flags. Later sources override earlier ones. Document the precedence clearly in --help. This pattern lets users set defaults in config files and override per-invocation with flags, which is the standard developer workflow.

5. Use meaningful exit codes and write errors to stderr. All informational output goes to stdout. All error messages go to stderr. Return exit code 0 for success and non-zero for failure. This convention enables reliable piping (tool list | grep pattern) and error detection in scripts (if tool deploy; then echo "success"; fi). Tools that violate these conventions break shell scripting.

Common Issues

CLI tool startup is slow due to heavy imports. Node.js and Python CLIs that import large frameworks on every invocation feel sluggish. Use lazy imports: only load modules when the specific subcommand that needs them is invoked. For Node.js, consider compiling to a binary with pkg or bundling with esbuild. For Python, use console_scripts entry points and lazy module loading.

Arguments become confusing as the tool grows in complexity. A CLI with 30 global flags is unusable. Group related functionality into subcommands: tool db migrate, tool db seed, tool api deploy. Each subcommand has its own focused set of flags. Limit global flags to universal options like --verbose, --config, and --output.

Shell completion doesn't work across different shells. Each shell (bash, zsh, fish) has a different completion mechanism. Use your argument parser's built-in completion generator if available. Commander.js, Click, and Cobra all generate shell completions from command definitions. Distribute completion scripts alongside the tool and document installation in --help.