API

Commander.js API

Overview

Commander.js is a complete solution for Node.js command-line interfaces. It provides a simple way to define and parse command-line arguments, display usage errors, and implement a help system.

Declaring the program variable

Commander exports a global object, which is convenient for quick programs. However, for larger programs that may use Commander in multiple ways, including unit testing, it is better to create a local Command object to use.

// CommonJS (.cjs)
const { Command } = require('commander');
const program = new Command();

// ECMAScript (.mjs)
import { Command } from 'commander';
const program = new Command();

// TypeScript (.ts)
import { Command } from 'commander';
const program = new Command();

Options

Options are defined with the .option() method, which also serves as documentation for the options. Each option can have a short flag (single character) and a long name, separated by a comma, a space, or a vertical bar (|).

program
  .option('--first')
  .option('-s, --separator <char>')
  .argument('<string>');

Commands

Commands are defined with the .command() method. Each command can have its own options, arguments, and action handler.

program
  .command('split')
  .description('Split a string into substrings and display as an array')
  .argument('<string>', 'string to split')
  .option('--first', 'display just the first substring')
  .option('-s, --separator <char>', 'separator character', ',')
  .action((str, options) => {
    const limit = options.first ? 1 : undefined;
    console.log(str.split(options.separator, limit));
  });

Automated Help

Commander provides a built-in help system. You can customize the help output using the .helpOption() method.

program
  .helpOption('-h, --help', 'display help for command');

Custom Event Listeners

You can add custom event listeners to Commander using the .on() method.

program.on('command:split', (command) => {
  console.log('Split command executed');
});

Parsing Configuration

You can customize the parsing configuration using the .configureOutput() method.

program
  .configureOutput({
    writeOut: (str) => process.stdout.write(`[OUT] ${str}`),
    writeErr: (str) => process.stdout.write(`[ERR] ${str}`),
    outputError: (str, write) => write(errorColor(str)),
  });

Creating a Custom Command Class

You can create a custom command class by extending the Command class.

class CustomCommand extends Command {
  createCommand(name) {
    const cmd = new CustomCommand(name);
    cmd.option('-t, --trace', 'display extra information when run command');
    return cmd;
  }
}

Creating a Custom Option Class

You can create a custom option class by extending the Option class.

class CustomOption extends Option {
  constructor(short, long, description) {
    super(short, long, description);
    this.type = 'custom';
  }
}

Creating a Custom Argument Class

You can create a custom argument class by extending the Argument class.

class CustomArgument extends Argument {
  constructor(description) {
    super(description);
    this.type = 'custom';
  }
}

Mermaid Diagram

graph TD
  A[Commander.js] --> B[Options]
  B --> C[Option]
  C --> D[Short Flag]
  C --> E[Long Name]
  C --> F[Description]
  B --> G[Arguments]
  G --> H[Argument]
  H --> I[Description]
  A --> J[Commands]
  J --> K[Command]
  K --> L[Description]
  K --> M[Action Handler]

Sources: index.js lib/command.js lib/option.js tests/command.description.test.js tests/command.alias.test.js tests/imports.test.cjs examples/custom-command-class.js examples/configure-output.js package.json