What is commander?
The commander npm package is a complete solution for node.js command-line interfaces. It provides a simple and flexible way to write CLI tools, allowing developers to parse command-line arguments, define commands, and automatically generate help messages.
What are commander's main functionalities?
Command parsing
This feature allows you to define options and parse command-line arguments. The code sample demonstrates how to set up a simple CLI with options for debugging, pizza size, and pizza type.
const { program } = require('commander');
program.version('0.0.1');
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);
if (program.debug) console.log(program.opts());
Subcommands
Commander allows you to define subcommands for your CLI application. The code sample shows how to define three subcommands: install, search, and list, with list being the default command.
const { program } = require('commander');
program
.command('install [name]', 'install one or more packages')
.command('search [query]', 'search with optional query')
.command('list', 'list packages installed', { isDefault: true })
.parse(process.argv);
Custom help
You can customize the help output of your CLI tool. The code sample demonstrates how to change the default help option and add a custom help command.
const { program } = require('commander');
program
.helpOption('-e, --HELP', 'read more information')
.addHelpCommand('assist', 'display help for command');
program.parse(process.argv);
Action handler
Commander allows you to attach an action handler to a command. The code sample shows how to define a command that takes a required argument and attaches an action handler to it.
const { program } = require('commander');
program
.command('start <service>')
.description('start the service')
.action(function(service) {
console.log('Starting service:', service);
});
program.parse(process.argv);
Other packages similar to commander
yargs
Yargs is a node.js library that helps you build interactive command line tools, by parsing arguments and generating an elegant user interface. It provides a fluent API and is similar to commander but with a slightly different philosophy and syntax. Yargs offers more advanced features like command chaining and context-based help.
meow
Meow is a simpler alternative to commander, providing a minimalistic CLI helper with argument parsing. It is less feature-rich compared to commander and yargs, but it is suitable for simpler command-line applications that do not require complex command structures.
vorpal
Vorpal is a framework for building interactive CLI applications. It is inspired by commander but aims to provide an immersive command-line experience. Vorpal offers a more interactive command-line interface with features like command history and autocomplete, which are not present in commander.
caporal
Caporal is a robust framework for building command-line applications. It provides a similar feature set to commander, including argument parsing, command-specific help, and auto-completion. Caporal emphasizes validation and typed options and arguments, which can make it more suitable for applications that require strict input validation.
Commander.js
The complete solution for node.js command-line interfaces, inspired by Ruby's commander.
Installation
$ npm install commander
Option parsing
Options with commander are defined with the .option()
method, also serving as documentation for the options. The example below parses args and options from process.argv
, leaving remaining args as the program.args
array which were not consumed by options.
#!/usr/bin/env node
var program = require('commander');
program
.version('0.0.1')
.option('-p, --peppers', 'Add peppers')
.option('-P, --pineapple', 'Add pineapple')
.option('-b, --bbq', 'Add bbq sauce')
.option('-c, --cheese [type]', 'Add the specified type of cheese [marble]', 'marble')
.parse(process.argv);
console.log('you ordered a pizza with:');
if (program.peppers) console.log(' - peppers');
if (program.pineapple) console.log(' - pineappe');
if (program.bbq) console.log(' - bbq');
console.log(' - %s cheese', program.cheese);
Short flags may be passed as a single arg, for example -abc
is equivalent to -a -b -c
. Multi-word options such as "--template-engine" are camel-cased, becoming program.templateEngine
etc.
Automated --help
The help information is auto-generated based on the information commander already knows about your program, so the following --help
info is for free:
$ ./examples/pizza --help
Usage: pizza [options]
Options:
-v, --version output the version number
-p, --peppers Add peppers
-P, --pineapple Add pineappe
-b, --bbq Add bbq sauce
-c, --cheese <type> Add the specified type of cheese [marble]
-h, --help output usage information
Coercion
function range(val) {
return val.split('..').map(Number);
}
function list(val) {
return val.split(',');
}
program
.version('0.0.1')
.option('-i, --integer <n>', 'An integer argument', parseInt)
.option('-f, --float <n>', 'A float argument', parseFloat)
.option('-r, --range <a>..<b>', 'A range', range)
.option('-l, --list <items>', 'A list', list)
.option('-o, --optional [value]', 'An optional value')
.parse(process.argv);
console.log(' int: %j', program.integer);
console.log(' float: %j', program.float);
console.log(' optional: %j', program.optional);
program.range = program.range || [];
console.log(' range: %j..%j', program.range[0], program.range[1]);
console.log(' list: %j', program.list);
console.log(' args: %j', program.args);
.prompt(msg, fn)
Single-line prompt:
program.prompt('name: ', function(name){
console.log('hi %s', name);
});
Multi-line prompt:
program.prompt('description:', function(name){
console.log('hi %s', name);
});
Coercion:
program.prompt('Age: ', Number, function(age){
console.log('age: %j', age);
});
program.prompt('Birthdate: ', Date, function(date){
console.log('date: %s', date);
});
.password(msg[, mask], fn)
Prompt for password without echoing:
program.password('Password: ', function(pass){
console.log('got "%s"', pass);
process.stdin.destroy();
});
Prompt for password with mask char "*":
program.password('Password: ', '*', function(pass){
console.log('got "%s"', pass);
process.stdin.destroy();
});
.confirm(msg, fn)
Confirm with the given msg
:
program.confirm('continue? ', function(ok){
console.log(' got %j', ok);
});
.choose(list, fn)
Let the user choose from a list
:
var list = ['tobi', 'loki', 'jane', 'manny', 'luna'];
console.log('Choose the coolest pet:');
program.choose(list, function(i){
console.log('you chose %d "%s"', i, list[i]);
});
Links
License
(The MIT License)
Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca>
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.