Command-line parser, usage text producer

work in progress, draft documentation


A command-line parser and usage-guide producer.. Particularly good at organising large sets of options.

$ npm install command-line-args --save

the following app.js...

var cliArgs = require("command-line-args");
/* define the command-line options */
var cli = cliArgs([
    { name: "verbose", type: Boolean, alias: "v", description: "Write plenty output" },
    { name: "help", type: Boolean, description: "Print usage instructions" },
    { name: "files", type: Array, defaultOption: true, description: "The input files" }
/* parse the supplied command-line values */
var options = cli.parse();
/* generate a usage guide */
var usage = cli.getUsage({
    header: "A synopsis application.",
    footer: "For more information, visit"
console.log( ? usage : options);

...returns this output at the command line:

$ node app.js
$ node app.js -v
{ verbose: true }
$ node app.js package.json
{ files: [ '''package.json' ] }
$ node app.js package.json -v
{ verbose: true, files: [ '''package.json' ] }
$ node app.js --help
  A synopsis application.
  -v, --verbose    Write plenty output
  --help           Print usage instructions
  --files <array>  The input files
  For more information, visit

API Reference


var cliArgs = require("command-line-args");
var cli = cliArgs([
    { name: "help", type: Boolean, alias: "h" },
    { name: "files", type: Array, defaultOption: true}
var argv = cli.parse();

Kind: Exported class

A constructor function, taking your desired command-line option definitions as input, returning an instance of command-line-args which you can parse() or getUsage().

optionsArray.<OptionDefinition>list of option definitions

Returns a flat, or grouped object containing the values set at the command-line

Kind: instance method of CliArgs

[argv]objectprocess.argvOptional argv array, pass to override the default process.argv.

Output from parse() looks something like this:

    delete: "thisfile.txt",
    force: true

or, if the option definitions are grouped:

    standard: {
        delete: "thisfile.txt",
        force: true
    extra: {
        intentions: "bad"

Kind: instance method of CliArgs

[options]objectoptions for template
[options.title]stringa title
[options.header]stringa header
[options.footer]stringa footer
[options.forms]arraythe invocation forms
[options.groups]arraythe groups to display in usage

Defines an option

Kind: inner typedef of CliArgs

namestringthe option name, used as the long option (e.g. --name)
typefunctionan optional function (e.g. Number or a custom function) used as a setter to enforce type.
aliasstringa single character alias, used as the short option (e.g. -n)
defaultOptionbooleanif values are specified without an option name, they are assigned to the defaultOption
descriptionstringused in the usage guide

© 2015 Lloyd Brookes <>. Documented by jsdoc-to-markdown.