Commander.js

To use Commander.js effectively, it is important to distinguish between the different types of arguments used in a command line interface:

• option: An argument starting with - (short form, e.g., -s) or -- (long form, e.g., --short). In some contexts, these are referred to as flags.
• option-argument: A value provided specifically for an option (e.g., in --file <path>, <path> is the option-argument).
• command: A specific action or program execution. Commands can have subcommands.
• command-argument: An argument intended for the command itself, rather than an option. These are also known as positional arguments or operands.

Example structure: my-utility command -o --option option-argument command-argument-1 command-argument-2

When a command is defined with a description as the second argument to .command(), Commander treats it as a stand-alone executable.

How it works: Commander searches the directory of the entry script for a file named command-subcommand (e.g., pm install looks for pm-install). It supports common extensions like .js.

Key Configuration:

• executableFile: Specify a custom name or path for the executable.
• executableDir(): Specify a custom search directory for subcommands.

Important: In this mode, the executable handles its own options; they are not declared in the main program.

program
  .name('pm')
  .command('install [package-names...]', 'install packages')
  .command('update', 'update packages', { executableFile: 'myUpdateSubCommand' })
  .command('list', 'list packages', { isDefault: true });

program.parse(process.argv);

The Help class uses two types of routines to generate output:

1. Stringify routines: These take a Command, Option, or Argument object and return a string. Use these to change how terms (like subcommand usage) are represented.
2. Style routines: These take a string and return a styled version (e.g., adding colors or bold text).

Commander.js automatically handles color detection and respects environment variables like NO_COLOR, FORCE_COLOR, and CLIFORCE_COLOR. If you use custom styles, Commander will strip colors if the output destination does not support them using Command.configureOutput().stripColor().

Example of styling titles using Node's util.styleText:

import { styleText } from 'node:util';
program.configureHelp({
   styleTitle: (str) => styleText('bold', str)
});

Commander supports two primary option types:

1. Boolean options: Defined without an argument placeholder. They are true if present and undefined if not.
2. Value options: Defined with angle brackets <value> (e.g., --expect <value>). These are greedy and consume the next argument. They are undefined if not specified.

Multiple boolean short options can be combined (e.g., -ds instead of -d -s).

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 run with: pizza-options -d -s -p vegetarian
// options is: { debug: true, small: true, pizzaType: 'vegetarian' }

By default, options are listed under Options: and commands under Commands:. You can create custom headings using two methods:

1. High-level: Use .optionsGroup(heading) and .commandsGroup(heading) when adding options or commands.
2. Low-level: Use .helpGroup(heading) on an individual Option or Command instance.

When a .command() is provided with a description as the second argument, Commander treats it as an external executable.

Key behaviors:

• Search Pattern: Commander looks for a file named {programName}-{commandName} (e.g., pm-install) in the directory of the entry script.
• Customization:
  • Use { executableFile: 'path/to/file' } in the command options to specify a custom path/name.
  • Use .executableDir('/path/to/dir') to change the search directory for subcommands.
• Permissions: If the command is intended for global installation, ensure the executable has appropriate permissions (e.g., 755).

program
  .command('update', 'update packages', { executableFile: 'myUpdateSubCommand' })
  .command('list', 'list packages', { isDefault: true });

program.parse(process.argv);

Commander provides two ways to initialize your CLI program:

1. Using the global program object

For simple scripts, you can import the pre-instantiated program object directly. This is the easiest way to get started.

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

2. Creating a local Command instance

For complex applications or when you need to perform unit testing, it is recommended to create your own Command instance. This provides better isolation.

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

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

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

Avoid importing from commander/esm.mjs. For both CommonJS and ESM, import directly from the main commander module.

Also, avoid relying on the default import of a global Command object. Instead, explicitly import Command or the program instance.

// Recommended (ESM or CJS)
import { Command } from 'commander';
// or
const { Command } = require('commander');

const program = new Command();

To use Commander.js in your Node.js project, install it using npm:

npm install commander

To get strong typing for the options returned by .opts() and the parameters passed to .action(), use the @commander-js/extra-typings package.

import { Command } from '@commander-js/extra-typings';