command-line-args
A 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:
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
Install
as a library
$ npm install command-line-args --save
as a tool
$ 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 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
commandLineArgs(optionDefinitions, [options]) ⇒ object
⏏
Returns an object containing all options set on the command line. By default it parses the global process.argv
array.
Kind: Exported function
Throws:
UNKNOWN_OPTION
if options.partial
is false and the user set an option without a definitionNAME_MISSING
if an option definition is missing the required name
propertyINVALID_TYPE
if an option definition has a type
value that's not a functionINVALID_ALIAS
if an alias is numeric, a hyphen or a length other than 1DUPLICATE_NAME
if an option definition name was used more than onceDUPLICATE_ALIAS
if an option definition alias was used more than onceDUPLICATE_DEFAULT_OPTION
if more than one option definition has defaultOption: true
Param | Type | Description |
---|
optionDefinitions | Array.<definition> | An array of OptionDefinition objects |
[options] | object | Options. |
[options.partial] | boolean | If true , unknown and unwanted arguments are returned in the _unknown property. |
[options.argv] | Array.<string> | An array of strings, which if passed will be parsed instead of process.argv . |
Example
const commandLineArgs = require('command-line-args')
const options = commandLineArgs([
{ name: 'file' },
{ name: 'verbose' },
{ name: 'depth'}
])
OptionDefinition ⏏
Describes a command-line option. Additionally, you can add description
and typeLabel
propeties and make use of command-line-usage.
Kind: Exported class
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.
# | 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" } |
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 }
])
# | 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
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 }
]
# | 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
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 }
]
# | 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
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 }
]
# | Command line | .parse() output |
---|
1 | --files one.js two.js | { files: [ 'one.js', 'two.js' ] } |
2 | one.js two.js | { files: [ 'one.js', 'two.js' ] } |
3 | * | { files: [ 'one.js', 'two.js' ] } |
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 }
]
# | 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
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" }
]
# | 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
© 2014-17 Lloyd Brookes <75pound@gmail.com>. Documented by jsdoc-to-markdown.