command-line-args

A mature, feature-complete library to parse command-line options.

If your app requires a git-like command interface, consider using command-line-commands.

Synopsis

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

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

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

const commandLineArgs = require('command-line-args')
 
const optionDefinitions = [
  { 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 supplied is passed through this), giving you full control over the value received.

Next, parse the options using commandLineArgs():

const options = commandLineArgs(optionDefinitions)

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.

A usage guide can be generated using command-line-usage, for example:

Notation rules

Notation rules for setting command-line options.

• Argument order is insignificant. Whether you set --example at the beginning or end of the arg list makes no difference.
• Options with a type of Boolean do not need to supply a value. Setting --flag or -f will set that option's value to true. This is the only type with special behaviour.
• Three ways to set an option value
  • --option value
  • --option=value
  • -o value
• Two ways to a set list of values (on options with multiple set)
  • --list one two three
  • --list one --list two --list three
• Short options (alias) can be set in groups. The following are equivalent:
  • -a -b -c
  • -abc

Ambiguous values

Imagine we are using "grep-tool" to search for the string '-f':

$ grep-tool --search -f

We have an issue here: command-line-args will assume we are setting two options (--search and -f). In actuality, we are passing one option (--search) and one value (-f). In cases like this, avoid ambiguity by using --option=value notation:

$ grep-tool --search=-f

Partial parsing

By default, if the user sets an option without a valid definition an UNKNOWN_OPTION exception is thrown. However, in some cases you may only be interested in a subset of the options wishing to pass the remainder to another library. See here for a example showing where this might be necessary.

To enable partial parsing, set partial: true in the method options:

const optionDefinitions = [
  { name: 'value', type: Number }
]
const options = commandLineArgs(optionDefinitions, { partial: true })

Now, should any unknown args be passed at the command line:

$ example --milk --value 2 --bread cheese

They will be returned in the _unknown property of the commandLineArgs output with no exceptions thrown:

{
  value: 2,
  _unknown: [ '--milk', '--bread', 'cheese']
}

Install

$ npm install command-line-args --save

API Reference

commandLineArgs(optionDefinitions, [options]) ⇒ object ⏏

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

By default, an exception is thrown if the user sets an unknown option (one without a valid definition). To enable partial parsing, invoke commandLineArgs with the partial option - all unknown arguments will be returned in the _unknown property.

Kind: Exported function
Throws:

• UNKNOWN_OPTION if options.partial is false and the user set an undefined option
• NAME_MISSING if an option definition is missing the required name property
• INVALID_TYPE if an option definition has a type value that's not a function
• INVALID_ALIAS if an alias is numeric, a hyphen or a length other than 1
• DUPLICATE_NAME if an option definition name was used more than once
• DUPLICATE_ALIAS if an option definition alias was used more than once
• DUPLICATE_DEFAULT_OPTION if more than one option definition has defaultOption: true

OptionDefinition ⏏

Describes a command-line option. Additionally, you can add description and typeLabel properties and make use of command-line-usage.

Kind: Exported class

• OptionDefinition ⏏
  • .name : string
  • .type : function
  • .alias : string
  • .multiple : boolean
  • .defaultOption : boolean
  • .defaultValue : *
  • .group : string | Array.<string>

option.name : string

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.

Unicode option names and aliases are valid, for example:

[
  { name: 'один' },
  { name: '两' },
  { name: 'три', alias: 'т' }
]

Kind: instance property of OptionDefinition

option.type : function

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:

const fs = require('fs')
 
function FileDetails(filename){
  if (!(this instanceof FileDetails)) return new FileDetails(filename)
  this.filename = filename
  this.exists = fs.existsSync(filename)
}
 
const cli = commandLineArgs([
  { name: 'file', type: FileDetails },
  { name: 'depth', type: Number }
])

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

Kind: instance property of OptionDefinition
Default: String

option.alias : string

getopt-style short option names. Can be any single character (unicode included) except a digit or hypen.

[
  { name: "hot", alias: "h", type: Boolean },
  { name: "discount", alias: "d", type: Boolean },
  { name: "courses", alias: "c" , type: Number }
]

Kind: instance property of OptionDefinition

option.multiple : boolean

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

[
  { name: "files", type: String, multiple: true }
]

Kind: instance property of OptionDefinition

option.defaultOption : boolean

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).

[
  { name: "files", type: String, multiple: true, defaultOption: true }
]

Kind: instance property of OptionDefinition

option.defaultValue : *

An initial value for the option.

[
  { name: "files", type: String, multiple: true, defaultValue: [ "one.js" ] },
  { name: "max", type: Number, defaultValue: 3 }
]

Kind: instance property of OptionDefinition

option.group : string | Array.<string>

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

There are two automatic groups: _all (contains all options) and _none (contains options without a group specified in their definition).

[
  { name: "verbose", group: "standard" },
  { name: "help", group: [ "standard", "main" ] },
  { name: "compress", group: [ "server", "main" ] },
  { name: "static", group: "server" },
  { name: "debug" }
]

{
 _all: { verbose: true },
 standard: { verbose: true }
}

{
 _all: { debug: true },
 _none: { debug: true }
}

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

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

Kind: instance property of OptionDefinition

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