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

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");

/* define the command-line options */
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" }
]);

/* parse the supplied command-line values */
var options = cli.parse();

/* generate a usage guide */
var usage = cli.getUsage({
    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

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();

• command-line-args
  • CliArgs ⏏
    • new CliArgs(options)
    • instance
      • .parse([argv]) ⇒ object
      • .getUsage(options) ⇒ string
    • inner
      • ~OptionDefinition : object

CliArgs ⏏

Kind: Exported class

new CliArgs(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().

Param	Type	Description
options	Array.<OptionDefinition>	list of option definitions

cliArgs.parse([argv]) ⇒ object

Returns a flat, or grouped object containing the values set at the command-line

Kind: instance method of CliArgs

Param	Type	Default	Description
[argv]	object	process.argv	Optional argv array, pass to override the default process.argv.

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"
    }
}

cliArgs.getUsage(options) ⇒ string

Kind: instance method of CliArgs

Param	Type	Description
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

CliArgs~OptionDefinition : object

Defines an option

Kind: inner typedef of CliArgs
Properties

Name	Type	Description
name	string	the option name, used as the long option (e.g. --name)
type	function	an optional function (e.g. Number or a custom function) used as a setter to enforce type.
alias	string	a single character alias, used as the short option (e.g. -n)
defaultOption	boolean	if values are specified without an option name, they are assigned to the defaultOption
description	string	used in the usage guide

documented by jsdoc-to-markdown.