cli-developer

$2a

Topic

Reference

Load When

Design Patterns

references/design-patterns.md

Subcommands, flags, config, architecture

Node.js CLIs

references/node-cli.md

commander, yargs, inquirer, chalk

Python CLIs

references/python-cli.md

click, typer, argparse, rich

Go CLIs

references/go-cli.md

cobra, viper, bubbletea

UX Patterns

references/ux-patterns.md

Progress bars, colors, help text

Quick-Start Example

Node.js (commander)

#!/usr/bin/env node

// npm install commander

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) quick-start examples, see references/python-cli.md and references/go-cli.md.

Constraints

MUST DO

• Keep startup time under 50ms

• Provide clear, actionable error messages

• Support --help and --version flags

• Use consistent flag naming conventions

• Handle SIGINT (Ctrl+C) gracefully

• Validate user input early

• Support both interactive and non-interactive modes

• Test on Windows, macOS, and Linux

MUST NOT DO

• Block on synchronous I/O unnecessarily — use async reads or stream processing instead.

• Print to stdout when output will be piped — write logs/diagnostics to stderr.

• Use colors when output is not a TTY — detect before applying color:

// Node.js

const useColor = process.stdout.isTTY;

# Python

import sys

use_color = sys.stdout.isatty()

// Go

import "golang.org/x/term"

useColor := term.IsTerminal(int(os.Stdout.Fd()))

• Break existing command signatures — treat flag/subcommand renames as breaking changes.

• Require interactive input in CI/CD environments — always provide non-interactive fallbacks via flags or env vars.

• Hardcode paths or platform-specific logic — use os.homedir() / os.UserHomeDir() / Path.home() instead.

• Ship without shell completions — all three frameworks above have built-in completion generation.

Output Templates

When implementing CLI features, provide:

• Command structure (main entry point, subcommands)

• Configuration handling (files, env vars, flags)

• Core implementation with error handling

• Shell completion scripts if applicable

• Brief explanation of UX decisions

Knowledge Reference

CLI frameworks (commander, yargs, oclif, click, typer, argparse, cobra, viper), terminal UI (chalk, inquirer, rich, bubbletea), testing (snapshot testing, E2E), distribution (npm, pip, homebrew, releases), performance optimization

Documentation