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.
work in progress, draft documentation
#command-line-args
A command-line parser and usage-guide producer.. Particularly good at organising large sets of options.
##Install
$ npm install command-line-args --save
##Synopsis
the following app.js
...
var cliArgs = require("command-line-args");
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" }
]);
var options = cli.parse();
var usage = cli.usage({
header: "A synopsis application.",
footer: "For more information, visit http://example.com"
});
console.log(options.help ? usage : options);
...returns this output at the command line:
$ node app.js
{}
$ node app.js -v
{ verbose: true }
$ node app.js README.md package.json
{ files: [ 'README.md', 'package.json' ] }
$ node app.js README.md package.json -v
{ verbose: true, files: [ 'README.md', 'package.json' ] }
$ node app.js --help
A synopsis application.
Usage
-v, --verbose Write plenty output
--help Print usage instructions
--files <array> The input files
For more information, visit http://example.com
#API Reference
##command-line-args(options)
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()
.
####Example
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();
###cli.parse([argv])
Returns a flat, or grouped object containing the values set at the command-line
- [argv=process.argv]
object
- Optional argv array, pass to override the default process.argv
.
Returns: object
####Example
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"
}
}
###cli.getUsage(options)
- options
object
- options for template - options.title
string
- a title - options.header
string
- a header - options.footer
string
- a footer - options.forms
array
- the invocation forms
Returns: string
###type: OptionDefinition
Defines an option
Scope: inner typedef of command-line-args
Type: object
###name
the option name, used as the long option (e.g. --name
)
Type: string
###type
an optional function (e.g. Number
or a custom function) used as a setter to enforce type.
Type: function
###alias
a single character alias, used as the short option (e.g. -n
)
Type: string
###defaultOption
if values are specified without an option name, they are assigned to the defaultOption
Type: boolean
###description
used in the usage guide
Type: string