Commander.js

The complete solution for node.js command-line interfaces.

Read this in other languages: English | 简体中文

• Commander.js
  • Installation
  • Quick Start
  • Declaring program variable
  • Options
    • Common option types, boolean and value
    • Default option value
    • Other option types, negatable boolean and boolean|value
    • Required option
    • Variadic option
    • Version option
    • More configuration
    • Custom option processing
  • Commands
    • Command-arguments
      • More configuration
      • Custom argument processing
    • Action handler
    • Stand-alone executable (sub)commands
    • Life cycle hooks
  • Automated help
    • Custom help
    • Display help after errors
    • Display help from code
    • .name
    • .usage
    • .description and .summary
    • .helpOption(flags, description)
    • .helpCommand()
    • Help Groups
    • More configuration
  • Custom event listeners
  • Bits and pieces
    • .parse() and .parseAsync()
    • Parsing Configuration
    • Legacy options as properties
    • TypeScript
    • createCommand()
    • Node options such as --harmony
    • Debugging stand-alone executable subcommands
    • npm run-script
    • Display error
    • Override exit and output handling
    • Additional documentation
  • Support
    • Commander for enterprise

For information about terms used in this document see: terminology

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.

Example file: split.js

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

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

program.parse();

const options = program.opts();
const limit = options.first ? 1 : undefined;
console.log(program.args[0].split(options.separator, limit));

$ node split.js -s / --fits a/b/c
error: unknown option '--fits'
(Did you mean --first?)
$ node split.js -s / --first a/b/c
[ 'a' ]

Here is a more complete program using a subcommand and with descriptions for the help. In a multi-command program, you have an action handler for each command (or stand-alone executables for the commands).

Example file: string-util.js

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

program
  .name('string-util')
  .description('CLI to some JavaScript string utilities')
  .version('0.8.0');

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

program.parse();

$ 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

$ node string-util.js split --separator=/ a/b/c
[ 'a', 'b', 'c' ]

More samples can be found in the examples directory.

Declaring program variable

Commander exports a global object which is convenient for quick programs. This is used in the 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('-p, --port <number>', 'server port number')
  .option('--trace', 'add extra debugging output')
  .option('--ws, --workspace <name>', 'use a custom workspace')

The parsed options can be accessed by calling .opts() on a Command object, and are passed to the action handler.

Multi-word options like --template-engine are normalized to camelCase option names, resulting in properties such as program.opts().templateEngine.

An option and its option-argument can be separated by a space, or combined into the same argument. The option-argument can follow the short option directly, or follow an = for a long option.

serve -p 80
serve -p80
serve --port 80
serve --port=80

You can use -- to indicate the end of the options, and any remaining arguments will be used without being interpreted.

By default, options on the command line are not positional, and can be specified before or after other arguments.

There are additional related routines for when .opts() is not enough:

• .optsWithGlobals() returns merged local and global option values
• .getOptionValue() and .setOptionValue() work with a single option value
• .getOptionValueSource() and .setOptionValueWithSource() include where the option value came from

Common option types, boolean and value

The two most used option types are a boolean option, and an option which takes its value from the following argument (declared with angle brackets like --expect <value>). Both are undefined unless specified on command line.

Example file: options-common.js

program
  .option('-d, --debug', 'output extra debugging')
  .option('-s, --small', 'small pizza size')
  .option('-p, --pizza-type <type>', 'flavour of pizza');

program.parse(process.argv);

const options = program.opts();
if (options.debug) console.log(options);
console.log('pizza details:');
if (options.small) console.log('- small pizza size');
if (options.pizzaType) console.log(`- ${options.pizzaType}`);

$ pizza-options -p
error: option '-p, --pizza-type <type>' argument missing
$ pizza-options -d -s -p vegetarian
{ debug: true, small: true, pizzaType: 'vegetarian' }
pizza details:
- small pizza size
- vegetarian
$ pizza-options --pizza-type=cheese
pizza details:
- cheese

Multiple boolean short options may be combined following the dash, and may be followed by a single short option taking a value. For example, -d -s -p cheese may be written as -ds -p cheese or even -dsp cheese.

Options with an expected option-argument are greedy and will consume the following argument whatever the value. So --id -xyz reads -xyz as the option-argument.

program.parse(arguments) processes the arguments, leaving any args not consumed by the program options in the program.args array. The parameter is optional and defaults to process.argv.

Default option value

You can specify a default value for an option.

Example file: options-defaults.js

program
  .option('-c, --cheese <type>', 'add the specified type of cheese', 'blue');

program.parse();

console.log(`cheese: ${program.opts().cheese}`);

$ pizza-options
cheese: blue
$ pizza-options --cheese stilton
cheese: stilton

Other option types, negatable boolean and boolean|value

You can define a boolean option long name with a leading no- to set the option value to false when