Getting Started

Commander.js Documentation

Getting Started

Installation

npm install commander

Quick Start

You write code to describe your command line interface. Commander looks after parsing the arguments into options and command-arguments, displays usage errors for problems, and implements a help system.

Commander is strict and displays an error for unrecognised options. The two most used option types are a boolean option, and an option which takes its value from the following argument.

Declaring program variable

Commander exports a global object which is convenient for quick programs. This is used in some examples in this README for brevity.

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

For larger programs which 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, also serving 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 (|). To allow a wider range of short-ish flags than just single characters, you may also have two long options.

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

Command

Commands are defined with the .command() method.

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));
  });

Help

Help is automatically generated from the options and commands defined.

$ node string-util.js help split
Usage: string-util split [options] <string>

Split a string into substrings and display as an array.

Arguments:
  string                  string to split

Options:
  --first                 display just the first substring
  -s, --separator <char>  separator character (default: ",")
  -h, --help              display help for command

Custom Help

You can customise the help output using the .helpOption() method.

program
  .helpOption(
    {
      sortSubcommands: true,
      subcommandTerm: (cmd) => cmd.name(), // Just show the name, instead of short usage.
    },
    'Custom help'
  );

Custom Event Listeners

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

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

Bits and Pieces

There are many other features and options available in Commander, including:

• Parsing Configuration: You can customise the parsing configuration using the .parse() method.
• Legacy Options as Properties: You can use legacy options as properties using the .storeOptionsAsProperties() method.
• TypeScript: You can use TypeScript with Commander using the .ts file extension.
• createCommand(): You can create a new command using the createCommand() method.
• Node Options: You can use Node options such as --harmony with Commander.
• Debugging Stand-alone Executable Subcommands: You can debug stand-alone executable subcommands using the node -inspect command.
• npm run-script: You can use npm run-script with Commander.
• Display Error: You can display an error using the .error() method.
• Override Exit and Output Handling: You can override exit and output handling using the .exitOverride() method.

Support

The current version of Commander is fully supported on Long Term Support versions of Node.js, and requires at least v22.12.0.

Older major versions of Commander receive security updates for 12 months. For more see: Release Policy.

The main forum for free and community support is the project Issues on GitHub.

Commander for Enterprise

Available as part of the Tidelift Subscription

The maintainers of Commander and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.

Sources: index.js