command-line-args

A library to collect command-line args and generate a usage guide.

command-line-args

A library to collect command-line args and generate a usage guide.

You can set options using the main notation standards (getopt, getopt_long, etc.). These commands are all equivalent, setting the same values:

$ my-app --verbose --timeout=1000 --src one.js --src two.js
$ my-app --verbose --timeout 1000 --src one.js two.js
$ my-app -vt 1000 --src one.js two.js
$ my-app -vt 1000 one.js two.js

To access the values, first describe the options your app accepts (see option definitions).

var commandLineArgs = require("command-line-args");
 
var cli = commandLineArgs([
    { name: "verbose", alias: "v", type: Boolean },
    { name: "src", type: String, multiple: true, defaultOption: true },
    { name: "timeout", alias: "t", type: Number }
]);

The type property is a setter function (the value you receive is the output of this), giving you full control over the value received.

Next, collect the command line args using .parse():

var options = cli.parse();

options now looks like this:

{
    files: [
        "one.js",
        "two.js"
    ],
    verbose: true,
    timeout: 1000
}

When dealing with large amounts of options it often makes sense to group them.

The .getUsage() method generates a usage guide. If you add descriptions to each option definition and call .getUsage() with some template data, for example:

var usage = cli.getUsage({
    title: "my-app",
    description: "Generates something useful",
    footer: "Project home: [underline]{https://github.com/me/my-app}"
});

..then usage, written to the terminal, looks something like:

$ npm install command-line-args --save
$ npm install -g command-line-args

If you install globally you get the command-line-args test-harness. You test by piping in a module which exports an option definitions array. You can then view the .parse() output for the args you pass.

For example:

$ cat example/typical.js | command-line-args lib/* --timeout=1000
{ src:
   [ 'lib/command-line-args.js',
     'lib/definition.js',
     'lib/definitions.js',
     'lib/option.js' ],
  timeout: 1000 }

API Reference

A library to collect command-line args and generate a usage guide.

A class encapsulating operations you can perform using an OptionDefinition array as input.

Kind: Exported class

ParamTypeDescription
definitionsArray.<definition>An optional array of OptionDefinition objects

Example

var commandLineArgs = require("command-line-args");
var cli = commandLineArgs([
    { name: "file" },
    { name: "verbose" },
    { name: "depth"}
]);

Returns an object containing all the values and flags set on the command line. By default it parses the global process.argv array.

Kind: instance method of CommandLineArgs

ParamTypeDescription
[argv]Array.<string>An array of strings, which if passed will be parsed instead of process.argv.

Generates a usage guide. Please see command-line-usage for full instructions of how to use.

Kind: instance method of CommandLineArgs

ParamTypeDescription
[options]objectthe options to pass to command-line-usage

Describes a command-line option.

Kind: Exported class

The only required definition property is name, so the simplest working example is

[
    { name: "file" },
    { name: "verbose" },
    { name: "depth"}
]

In this case, the value of each option will be either a Boolean or string.

#Command line args.parse() output
1--file{ file: true }
2--file lib.js --verbose{ file: "lib.js", verbose: true }
3--verbose very{ verbose: "very" }
4--depth 2{ depth: "2" }

Kind: instance property of OptionDefinition

The type value is a setter function (you receive the output from this), enabling you to be specific about the type and value received.

You can use a class, if you like:

var fs = require("fs");
 
function FileDetails(filename){
    if (!(this instanceof FileDetails)) return new FileDetails(filename);
    this.filename = filename;
    this.exists = fs.existsSync(filename);
}
 
module.exports = [
    { name: "file", type: FileDetails },
    { name: "depth", type: Number }
];
#Command line args.parse() output
1--file asdf.txt{ file: { filename: 'asdf.txt', exists: false } }

The --depth option expects a Number. If no value was set, you will receive null.

#Command line args.parse() output
2--depth{ depth: null }
3--depth 2{ depth: 2 }

Kind: instance property of OptionDefinition

getopt-style short option names. Must be a single character.

[
  { name: "hot", alias: "h", type: Boolean },
  { name: "discount", alias: "d", type: Boolean },
  { name: "courses", alias: "c" , type: Number }
]
#Command line.parse() output
1-hcd{ hot: true, courses: null, discount: true }
2-hdc 3{ hot: true, discount: true, courses: 3 }

Kind: instance property of OptionDefinition

Set this flag if the option takes a list of values. You will receive an array of values passed through the type function (if specified).

module.exports = [
    { name: "files", type: String, multiple: true }
];
#Command line.parse() output
1--files one.js two.js{ files: [ 'one.js', 'two.js' ] }
2--files one.js --files two.js{ files: [ 'one.js', 'two.js' ] }
3--files *{ files: [ 'one.js', 'two.js' ] }

Kind: instance property of OptionDefinition

Any unclaimed command-line args will be set on this option. This flag is typically set on the most commonly-used option to make for more concise usage (i.e. $ myapp *.js instead of $ myapp --files *.js).

module.exports = [
    { name: "files", type: String, multiple: true, defaultOption: true }
];
#Command line.parse() output
1--files one.js two.js{ files: [ 'one.js', 'two.js' ] }
2one.js two.js{ files: [ 'one.js', 'two.js' ] }
3*{ files: [ 'one.js', 'two.js' ] }

Kind: instance property of OptionDefinition

An initial value for the option.

module.exports = [
    { name: "files", type: String, multiple: true, defaultValue: [ "one.js" ] },
    { name: "max", type: Number, defaultValue: 3 }
];
#Command line.parse() output
1{ files: [ 'one.js' ], max: 3 }
2--files two.js{ files: [ 'two.js' ], max: 3 }
3--max 4{ files: [ 'one.js' ], max: 4 }

Kind: instance property of OptionDefinition

When your app has a large amount of options it makes sense to organise them in groups.

module.exports = [
    { name: "verbose", group: "standard" },
    { name: "help", group: [ "standard", "main" ] },
    { name: "compress", group: [ "server", "main" ] },
    { name: "static", group: "server" },
    { name: "debug" }
];
#Command Line.parse() output
1--verbose

{ 
 _all: { verbose: true }, 
 standard: { verbose: true } 
}
2--debug

{ 
 _all: { debug: true }, 
 _none: { debug: true } 
}
3--verbose --debug --compress

{ 
 _all: { 
   verbose: true, 
   debug: true, 
   compress: true 
 }, 
 standard: { verbose: true }, 
 server: { compress: true }, 
 main: { compress: true }, 
 _none: { debug: true } 
}
4--compress

{ 
 _all: { compress: true }, 
 server: { compress: true }, 
 main: { compress: true } 
}

Kind: instance property of OptionDefinition


© 2015 Lloyd Brookes <75pound@gmail.com>. Documented by jsdoc-to-markdown.