commanderjs-patterns

name	Commander.js Patterns
description	Commander.js CLI framework patterns including Command class, options, arguments, nested subcommands, and Option class usage. Use when building Node.js CLIs, implementing Commander.js commands, creating TypeScript CLI tools, adding command options/arguments, or when user mentions Commander.js, CLI commands, command options, or nested subcommands.
allowed-tools	Read, Write, Bash, Edit

Commander.js Patterns Skill

Provides comprehensive Commander.js patterns, templates, and examples for building robust Node.js CLI applications with TypeScript support.

Overview

Commander.js is the complete solution for Node.js command-line interfaces. This skill provides battle-tested patterns for:

• Command class instantiation and configuration
• Options with flags, choices, and defaults
• Arguments (required, optional, variadic)
• Nested subcommands and command hierarchies
• Option class with advanced validation
• Action handlers and middleware
• Error handling and validation

Instructions

Basic Command Setup

1. Create program instance:

   import { Command } from 'commander';
   const program = new Command();
   
   program
     .name('mycli')
     .description('CLI description')
     .version('1.0.0');
   

2. Add simple command:

   program
     .command('init')
     .description('Initialize project')
     .action(() => {
       // Command logic
     });
   

3. Parse arguments:

   program.parse();
   

Command with Options

Use options for named flags with values:

program
  .command('deploy')
  .description('Deploy application')
  .option('-e, --env <environment>', 'target environment', 'dev')
  .option('-f, --force', 'force deployment', false)
  .option('-v, --verbose', 'verbose output')
  .action((options) => {
    console.log('Environment:', options.env);
    console.log('Force:', options.force);
    console.log('Verbose:', options.verbose);
  });

Command with Arguments

Use arguments for positional parameters:

program
  .command('deploy <environment>')
  .description('Deploy to environment')
  .argument('<environment>', 'target environment')
  .argument('[region]', 'optional region', 'us-east-1')
  .action((environment, region, options) => {
    console.log(`Deploying to ${environment} in ${region}`);
  });

Option Class Usage

For advanced option configuration:

import { Command, Option } from 'commander';

program
  .command('deploy')
  .addOption(
    new Option('-m, --mode <mode>', 'deployment mode')
      .choices(['fast', 'safe', 'rollback'])
      .default('safe')
      .makeOptionMandatory()
  )
  .addOption(
    new Option('-r, --replicas <count>', 'replica count')
      .argParser(parseInt)
      .default(3)
  )
  .action((options) => {
    console.log(`Mode: ${options.mode}, Replicas: ${options.replicas}`);
  });

Nested Subcommands

Create command hierarchies:

const config = program
  .command('config')
  .description('Manage configuration');

config
  .command('get <key>')
  .description('Get config value')
  .action((key) => {
    console.log(`Config ${key}:`, getConfig(key));
  });

config
  .command('set <key> <value>')
  .description('Set config value')
  .action((key, value) => {
    setConfig(key, value);
    console.log(`✓ Set ${key} = ${value}`);
  });

config
  .command('list')
  .description('List all config')
  .action(() => {
    console.log(getAllConfig());
  });

Variadic Arguments

Accept multiple values:

program
  .command('add <items...>')
  .description('Add multiple items')
  .action((items) => {
    console.log('Adding items:', items);
  });

// Usage: mycli add item1 item2 item3

Custom Argument Parsing

Transform argument values:

program
  .command('wait <delay>')
  .description('Wait for specified time')
  .argument('<delay>', 'delay in seconds', parseFloat)
  .action((delay) => {
    console.log(`Waiting ${delay} seconds...`);
  });

Global Options

Options available to all commands:

program
  .option('-c, --config <path>', 'config file path')
  .option('-v, --verbose', 'verbose output')
  .option('--no-color', 'disable colors');

program
  .command('deploy')
  .action((options, command) => {
    const globalOpts = command.parent?.opts();
    console.log('Config:', globalOpts?.config);
    console.log('Verbose:', globalOpts?.verbose);
  });

Error Handling

program
  .command('deploy <environment>')
  .action((environment) => {
    if (!['dev', 'staging', 'prod'].includes(environment)) {
      throw new Error(`Invalid environment: ${environment}`);
    }
    // Deploy logic
  });

program.exitOverride();
try {
  program.parse();
} catch (err) {
  console.error('Error:', err.message);
  process.exit(1);
}

Available Scripts

• validate-commander-structure.sh: Validates Commander.js CLI structure and patterns
• generate-command.sh: Scaffolds new command with options and arguments
• generate-subcommand.sh: Creates nested subcommand structure
• test-commander-cli.sh: Tests CLI commands with various inputs
• extract-command-help.sh: Extracts help text from CLI for documentation

Templates

TypeScript Templates

• basic-commander.ts: Minimal Commander.js setup
• command-with-options.ts: Command with various option types
• command-with-arguments.ts: Command with required/optional arguments
• nested-subcommands.ts: Multi-level command hierarchy
• option-class-advanced.ts: Advanced Option class usage
• full-cli-example.ts: Complete CLI with all patterns
• commander-with-inquirer.ts: Interactive prompts integration
• commander-with-validation.ts: Input validation patterns

JavaScript Templates

• basic-commander.js: ES modules Commander.js setup
• commonjs-commander.js: CommonJS Commander.js setup

Configuration Templates

• tsconfig.commander.json: TypeScript config for Commander.js projects
• package.json.template: Package.json with Commander.js dependencies

Examples

• basic-usage.md: Simple CLI with 2-3 commands
• options-arguments-demo.md: Comprehensive options and arguments examples
• nested-commands-demo.md: Building command hierarchies
• advanced-option-class.md: Option class validation and parsing
• interactive-cli.md: Combining Commander.js with Inquirer.js
• error-handling-patterns.md: Robust error handling strategies
• testing-commander-cli.md: Unit and integration testing patterns

Commander.js Key Concepts

Command Class

new Command()
  .name('cli-name')
  .description('CLI description')
  .version('1.0.0')
  .command('subcommand')

Option Types

• Flag option: -v, --verbose (boolean)
• Value option: -p, --port <port> (required value)
• Optional value: -p, --port [port] (optional value)
• Negatable: --no-color (inverse boolean)
• Variadic: --files <files...> (multiple values)

Argument Types

• Required: <name>
• Optional: [name]
• Variadic: <items...> or [items...]

Option Class Methods

• .choices(['a', 'b', 'c']): Restrict to specific values
• .default(value): Set default value
• .argParser(fn): Custom parsing function
• .makeOptionMandatory(): Require option
• .conflicts(option): Mutually exclusive options
• .implies(option): Implies another option
• .env(name): Read from environment variable

Action Handler Signatures

// No arguments
.action(() => {})

// With options only
.action((options) => {})

// With arguments
.action((arg1, arg2, options) => {})

// With command reference
.action((options, command) => {})

Pattern Recipes

Pattern 1: Simple CLI with Subcommands

Use template: templates/basic-commander.ts

Pattern 2: CLI with Rich Options

Use template: templates/option-class-advanced.ts

Pattern 3: Interactive CLI

Use template: templates/commander-with-inquirer.ts

Pattern 4: CLI with Validation

Use template: templates/commander-with-validation.ts

Pattern 5: Multi-level Commands

Use template: templates/nested-subcommands.ts

Integration with Other Tools

With Inquirer.js (Interactive Prompts)

import inquirer from 'inquirer';

program
  .command('setup')
  .action(async () => {
    const answers = await inquirer.prompt([
      { type: 'input', name: 'name', message: 'Project name:' },
      { type: 'list', name: 'template', message: 'Template:', choices: ['basic', 'advanced'] }
    ]);
    // Use answers
  });

With Chalk (Colored Output)

import chalk from 'chalk';

program
  .command('deploy')
  .action(() => {
    console.log(chalk.green('✓ Deployment successful'));
    console.log(chalk.red('✗ Deployment failed'));
  });

With Ora (Spinners)

import ora from 'ora';

program
  .command('build')
  .action(async () => {
    const spinner = ora('Building...').start();
    await build();
    spinner.succeed('Build complete');
  });

Best Practices

1. Use Option class for complex options: Provides better validation and type safety
2. Keep action handlers thin: Delegate to separate functions
3. Provide clear descriptions: Help users understand commands
4. Set sensible defaults: Reduce required options
5. Validate early: Check inputs before processing
6. Handle errors gracefully: Provide helpful error messages
7. Use TypeScript: Better type safety and IDE support
8. Test thoroughly: Unit test commands and options
9. Document examples: Show common usage patterns
10. Version your CLI: Use semantic versioning

Common Patterns

Pattern: Config Command Group

const config = program.command('config');
config.command('get <key>').action(getConfig);
config.command('set <key> <value>').action(setConfig);
config.command('list').action(listConfig);
config.command('delete <key>').action(deleteConfig);

Pattern: CRUD Commands

program.command('create <name>').action(create);
program.command('read <id>').action(read);
program.command('update <id>').action(update);
program.command('delete <id>').action(deleteItem);
program.command('list').action(list);

Pattern: Deploy with Environments

program
  .command('deploy')
  .addOption(new Option('-e, --env <env>').choices(['dev', 'staging', 'prod']))
  .option('-f, --force', 'force deployment')
  .action(deploy);

Troubleshooting

Issue: Options not parsed

Solution: Ensure program.parse() is called

Issue: Arguments not received

Solution: Check action handler signature matches argument count

Issue: Subcommands not working

Solution: Verify subcommand is attached before parse()

Issue: TypeScript errors

Solution: Install @types/node and configure tsconfig

Issue: Help not showing

Solution: Commander.js auto-generates help from descriptions

Success Criteria

✅ Command structure follows Commander.js conventions ✅ Options and arguments properly typed ✅ Help text is clear and descriptive ✅ Error handling covers edge cases ✅ CLI tested with various inputs ✅ TypeScript compiles without errors ✅ Commands execute as expected

Related Skills

• click-patterns - Python Click framework patterns
• typer-patterns - Python Typer framework patterns
• clap-patterns - Rust Clap framework patterns

---

Skill Type: Framework Patterns + Code Templates Language: TypeScript/JavaScript (Node.js) Framework: Commander.js v12+ Auto-invocation: Yes (via description matching)