command-line-args

What is command-line-args?

The command-line-args npm package is a library for parsing command-line arguments in Node.js applications. It allows developers to define options and parse them from the command line, making it easier to handle user inputs and configurations.

What are command-line-args's main functionalities?

Basic Argument Parsing

This feature allows you to define and parse basic command-line arguments. In this example, the 'file' option expects a string value, and the 'verbose' option is a boolean flag.

const commandLineArgs = require('command-line-args');

const optionDefinitions = [
  { name: 'file', type: String },
  { name: 'verbose', type: Boolean }
];

const options = commandLineArgs(optionDefinitions);
console.log(options);

Default Values

This feature allows you to set default values for options. If the user does not provide a value for 'file' or 'verbose', the defaults 'default.txt' and 'false' will be used, respectively.

const commandLineArgs = require('command-line-args');

const optionDefinitions = [
  { name: 'file', type: String, defaultValue: 'default.txt' },
  { name: 'verbose', type: Boolean, defaultValue: false }
];

const options = commandLineArgs(optionDefinitions);
console.log(options);

Multiple Values

This feature allows you to handle multiple values for a single option. In this example, the 'files' option can accept multiple string values.

const commandLineArgs = require('command-line-args');

const optionDefinitions = [
  { name: 'files', type: String, multiple: true, defaultOption: true }
];

const options = commandLineArgs(optionDefinitions);
console.log(options);

Aliases

This feature allows you to define aliases for options. In this example, 'help' can be accessed with '-h' and 'version' with '-v'.

const commandLineArgs = require('command-line-args');

const optionDefinitions = [
  { name: 'help', alias: 'h', type: Boolean },
  { name: 'version', alias: 'v', type: Boolean }
];

const options = commandLineArgs(optionDefinitions);
console.log(options);

Other packages similar to command-line-args

yargs

Yargs is a popular library for parsing command-line arguments in Node.js. It provides a rich set of features, including command handling, argument validation, and automatic help generation. Compared to command-line-args, yargs offers more advanced features and a more user-friendly API.

commander

Commander is another widely-used library for building command-line interfaces in Node.js. It supports option parsing, command definitions, and automatic help generation. Commander is known for its simplicity and ease of use, making it a good alternative to command-line-args for simpler use cases.

minimist

Minimist is a lightweight library for parsing command-line arguments. It provides basic functionality for handling options and arguments, but lacks some of the advanced features found in command-line-args, yargs, and commander. Minimist is a good choice for projects that require minimal overhead.

README

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:
  • -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

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 definition
• 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

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

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

#	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 <[e-mail]>. Documented by jsdoc-to-markdown.