commander-guidelines

name	commander-guidelines
description	Comprehensive guide for building Node.js command-line interfaces using Commander.js. Use when creating CLI tools with options, commands, subcommands, arguments, and help system customization.

Commander.js Guidelines

Overview

This skill provides guidance for building Node.js command-line interfaces using Commander.js. It covers common patterns for defining options, commands, arguments, and customizing the help system.

Quick Start

Installation

npm install commander

Basic Program

const { program } = require('commander');

program
  .option('-p, --port <number>', 'server port number')
  .option('-d, --debug', 'output extra debugging')
  .argument('<input>', 'input file to process')
  .action((input, options) => {
    console.log(`Processing ${input} on port ${options.port}`);
    if (options.debug) console.log('Debug mode enabled');
  });

program.parse();

Multi-Command Program

const { Command } = require('commander');
const program = new Command();

program
  .name('my-cli')
  .description('CLI tool for managing tasks')
  .version('1.0.0');

program.command('add')
  .description('Add a new task')
  .argument('<task>', 'task description')
  .action((task) => {
    console.log(`Added task: ${task}`);
  });

program.command('list')
  .description('List all tasks')
  .action(() => {
    console.log('Listing tasks...');
  });

program.parse();

Common Patterns

Options

Boolean Options

program.option('-d, --debug', 'enable debug mode');
// Usage: my-cli --debug

Value Options

program.option('-p, --port <number>', 'server port');
// Usage: my-cli --port 8080

Required Options

program.requiredOption('-k, --key <api-key>', 'API key is required');
// Usage: my-cli --key abc123

Variadic Options

program.option('-f, --files <files...>', 'files to process');
// Usage: my-cli --file file1.txt file2.txt file3.txt

Negatable Options

program.option('--no-cache', 'disable caching');
// Usage: my-cli --no-cache

Default Values

program.option('-p, --port <number>', 'server port', 3000);
// Default: 3000 if not specified

Custom Processing

function parsePort(value) {
  const port = parseInt(value, 10);
  if (isNaN(port)) {
    throw new commander.InvalidArgumentError('Not a number.');
  }
  return port;
}

program.option('-p, --port <number>', 'server port', parsePort);

Commands and Subcommands

Action Handler Commands

program.command('clone <source> [destination]')
  .description('clone a repository')
  .action((source, destination) => {
    console.log(`Cloning ${source} to ${destination}`);
  });

Stand-alone Executable Commands

program.command('install [package-names...]', 'install one or more packages');
program.command('search [query]', 'search with optional query');

Arguments

Required Arguments

program.argument('<username>', 'user to login');

Optional Arguments

program.argument('[password]', 'password for user', 'no password given');

Variadic Arguments

program.argument('<files...>', 'files to process');

Multiple Arguments

program.arguments('<username> <password>');

Help System

Custom Help Text

program.addHelpText('after', `

Example call:
  $ my-cli --help`);

Custom Help Option

program.helpOption('-e, --HELP', 'read more information');

Show Help After Error

program.showHelpAfterError();
// or
program.showHelpAfterError('(add --help for additional information)');

Life Cycle Hooks

program
  .option('-t, --trace', 'display trace statements')
  .hook('preAction', (thisCommand, actionCommand) => {
    if (thisCommand.opts().trace) {
      console.log(`About to call: ${actionCommand.name()}`);
    }
  });

Advanced Features

Parsing Configuration

// Only look for program options before subcommands
program.enablePositionalOptions();

// Pass options through to another program
program.passThroughOptions();

// Allow unknown options
program.allowUnknownOption();

// Allow excess arguments
program.allowExcessArguments();

Error Handling

// Display custom error
program.error('Password must be longer than four characters');

// Override exit handling
program.exitOverride();

try {
  program.parse(process.argv);
} catch (err) {
  // custom processing
}

TypeScript Support

import { Command } from '@commander-js/extra-typings';
const program = new Command();

Detailed API Reference

For comprehensive API documentation including all options, commands, arguments, help system customization, and advanced features, see the detailed API reference:

references/commander-api.md

This reference includes:

• Complete option types and configuration
• Command and subcommand patterns
• Argument handling (required, optional, variadic)
• Help system customization
• Life cycle hooks
• TypeScript support
• Advanced parsing configuration
• Error handling patterns
• And more

Resources

references/

This skill includes detailed API documentation:

• commander-api.md - Comprehensive API reference extracted from Commander.js documentation, organized by topic with code examples for each feature.