Contributing

Contributing to Commander.js

Issues

New issues are welcome, whether questions or suggestions or reporting bugs. You are also welcome to contribute by adding helpful comments on an existing issue.

Pull Requests

Pull Requests will be considered. Please submit pull requests against the develop branch.

Contributing Guidelines

• npm run test
• npm run check

Don't update the CHANGELOG or command version number. That gets done by maintainers when preparing the release.

Useful things to include in your request description are:

• what problem are you solving?
• what Issues does this relate to?
• suggested summary for CHANGELOG

Code Style

Follow the existing code style.

Documentation

• TypeScript typings
• JSDoc documentation in code
• tests
• README
• examples/

Dependencies

Commander currently has zero production dependencies. That isn't a hard requirement, but is a simple story. Requests which add a dependency are much less likely to be accepted, and we are likely to ask for alternative approaches to avoid the dependency.

Security Updates

Older major versions of Commander receive security updates for 12 months.

Support

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

Community Support

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

Commercial Support

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.

Additional Documentation

• deprecated features still supported for backwards compatibility
• Help in Depth configuring help output
• options taking varying arguments
• parsing life cycle and hooks
• Release Policy

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

import { program } from '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

import { Command } from '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 some examples in this README for brevity.

import { program } from '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>');

Commands

Commands are defined with the .command() method. Each command can have a description, arguments, and options.

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

Automated help is provided by the .help() method.

$ 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

Custom help can be provided by creating a subclass of the Help class.

class MyHelp extends Help {
  formatItem(term, termWidth, description, helper) {
    // Pre-pad the term at start instead of end.
    const paddedTerm = term.padStart(
      termWidth + term.length - helper.displayWidth(term),
    );

    return super.formatItem(paddedTerm, termWidth, description, helper);
  }
}

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.

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

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: CONTRIBUTING.md