CLI Developer

CLI Developer

When to Use / When Not to Use

Use when:

• Building a new CLI tool with subcommands, flags, config handling
• Adding shell completions, progress bars, or interactive prompts
• Distributing a cross-platform terminal binary

Do not use when:

• Building a web UI or REST API
• The task is SRE pipeline integration only (use sre-engineer)

Process

1. Analyze UX — Identify user workflows, command hierarchy, and common tasks. List all commands with expected --help output before writing code.
2. Design commands — Plan subcommands, flags, arguments, configuration. Confirm flag naming is consistent and no existing signatures are broken.
3. Select framework — Node.js: commander → yargs → oclif; Python: typer → click → argparse; Go: cobra + viper → bubbletea (TUI only)
4. Implement — Build with the chosen framework. After wiring commands, run <cli> --help to verify help text and <cli> --version for version output.
5. Polish — Add completions, error messages, progress indicators. Verify TTY detection for color output and graceful SIGINT handling.
6. Test — Cross-platform smoke tests; benchmark startup time (target: <50ms).

Output Template

For each CLI feature, provide:

1. Command structure (main entry point, subcommands)
2. Configuration handling (files, env vars, flags)
3. Core implementation with error handling
4. Shell completion scripts (if applicable)
5. Brief note on UX decisions

What Claude Does / What You Do

Reference Guide

Quick-Start Example (Node.js / commander)

#!/usr/bin/env node
const { program } = require('commander');

program
  .name('mytool')
  .description('Example CLI')
  .version('1.0.0');

program
  .command('greet <name>')
  .description('Greet a user')
  .option('-l, --loud', 'uppercase the greeting')
  .action((name, opts) => {
    const msg = `Hello, ${name}!`;
    console.log(opts.loud ? msg.toUpperCase() : msg);
  });

program.parse();

For Python (click/typer) and Go (cobra) examples, see references/python-cli.md and references/go-cli.md.

Constraints

MUST DO:

• Keep startup time under 50ms
• Support --help and --version flags
• Use consistent flag naming conventions
• Handle SIGINT (Ctrl+C) gracefully
• Validate user input early
• Detect TTY before applying color output
• Support both interactive and non-interactive modes

MUST NOT DO:

• Print logs/diagnostics to stdout when output will be piped (use stderr)
• Break existing command signatures — treat renames as breaking changes
• Require interactive input in CI/CD without non-interactive flag fallbacks
• Hardcode platform-specific paths (use os.homedir() / Path.home())
• Ship without shell completions

Related Skills

• sre-engineer — for integrating CLI tools into SRE pipelines
• code-documenter — for documenting CLI commands and flags