Note
Cloned and adapted from commander.js so that the great package can be used in browser (by removing node.js dependencies from index.js and saved as browser.js). Also added a bit functionality so that known and unknown parsed options are also collected separately (in the collectedOptions field). These hacks are not really ready for real use tho.
Commander.js
The complete solution for node.js command-line interfaces, inspired by Ruby's commander.
API documentation
Installation
$ npm install commander --save
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 /** * Module dependencies. */ var program = ; program version'0.1.0' ; console;if programpeppers console;if programpineapple console;if programbbqSauce console;console;
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.
Note that multi-word options starting with --no
prefix negate the boolean value of the following word. For example, --no-sauce
sets the value of program.sauce
to false.
#!/usr/bin/env node /** * Module dependencies. */ var program = ; program ; console;if programsauce console;else console;
Version option
Calling the version
implicitly adds the -V
and --version
options to the command.
When either of these options is present, the command prints the version number and exits.
$ ./examples/pizza -V
0.0.1
If you want your program to respond to the -v
option instead of the -V
option, simply pass custom flags to the version
method using the same syntax as the option
method.
program version'0.0.1' '-v, --version'
Now the command will accept the -v
option instead of the -V
option.
Command-specific options
You can attach options to a command.
#!/usr/bin/env node var program = ; program action { console } program
A command's options are validated when the command is used. Any unknown options will be reported as an error. However, if an action-based command does not define an action, then the options are not validated.
Coercion
{ return val;} { return val;} { memo; return memo;} { return total + 1;} program version'0.1.0' ; console;console;console;programrange = programrange || ;console;console;console;console;console;
Regular Expression
program version'0.1.0' ; console;console;
Variadic arguments
The last argument of a command can be variadic, and only the last argument. To make an argument variadic you have to
append ...
to the argument name. Here is an example:
#!/usr/bin/env node /** * Module dependencies. */ var program = ; program version'0.1.0' action { console; if otherDirs otherDirs; }; program;
An Array
is used for the value of a variadic argument. This applies to program.args
as well as the argument passed
to your action as demonstrated above.
Specify the argument syntax
#!/usr/bin/env node var program = ; program version'0.1.0' arguments'<cmd> [env]' action { cmdValue = cmd; envValue = env; }; program; if typeof cmdValue === 'undefined' console; process;console;console;
Angled brackets (e.g. <cmd>
) indicate required input. Square brackets (e.g. [env]
) indicate optional input.
Git-style sub-commands
// file: ./examples/pmvar program = ; program version'0.1.0' ;
When .command()
is invoked with a description argument, no .action(callback)
should be called to handle sub-commands, otherwise there will be an error. This tells commander that you're going to use separate executables for sub-commands, much like git(1)
and other popular tools.
The commander will try to search the executables in the directory of the entry script (like ./examples/pm
) with the name program-command
, like pm-install
, pm-search
.
Options can be passed with the call to .command()
. Specifying true
for opts.noHelp
will remove the option from the generated help output. Specifying true
for opts.isDefault
will run the subcommand if no other subcommand is specified.
If the program is designed to be installed globally, make sure the executables have proper modes, like 755
.
--harmony
You can enable --harmony
option in two ways:
- Use
#! /usr/bin/env node --harmony
in the sub-commands scripts. Note some os version don’t support this pattern. - Use the
--harmony
option when call the command, likenode --harmony examples/pm publish
. The--harmony
option will be preserved when spawning sub-command process.
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]
An application for pizzas ordering
Options:
-h, --help output usage information
-V, --version output the version number
-p, --peppers Add peppers
-P, --pineapple Add pineapple
-b, --bbq Add bbq sauce
-c, --cheese <type> Add the specified type of cheese [marble]
-C, --no-cheese You do not want any cheese
Custom help
You can display arbitrary -h, --help
information
by listening for "--help". Commander will automatically
exit once you are done so that the remainder of your program
does not execute causing undesired behaviours, for example
in the following executable "stuff" will not output when
--help
is used.
#!/usr/bin/env node /** * Module dependencies. */ var program = ; program version'0.1.0' ; // must be before .parse() since// node's emit() is immediate program; program; console;
Yields the following help output when node script-name.js -h
or node script-name.js --help
are run:
Usage: custom-help [options]
Options:
-h, --help output usage information
-V, --version output the version number
-f, --foo enable some foo
-b, --bar enable some bar
-B, --baz enable some baz
Examples:
$ custom-help --help
$ custom-help -h
.outputHelp(cb)
Output help information without exiting. Optional callback cb allows post-processing of help text before it is displayed.
If you want to display help by default (e.g. if no command was provided), you can use something like:
var program = ;var colors = ; program version'0.1.0' ; if !processargvlength program; { return colors; //display the help text in red on the console}
.help(cb)
Output help information and exit immediately. Optional callback cb allows post-processing of help text before it is displayed.
Examples
var program = ; program version'0.1.0' ; program description'run setup commands for all envs' action{ var mode = optionssetup_mode || "normal"; env = env || 'all'; console; }; program description'execute the given remote cmd' action{ console; }; program action{ console; }; program;
More Demos can be found in the examples directory.
License
MIT