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 collect command-line args and generate a usage guide.

Synopsis

Say your app was run with one of these commands (they are all equalivalent and parse the same)

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

then your app can access the values like this:

1. First describe the options your app accepts (see option definitions).

var cliArgs = require("command-line-args");

var cli = cliArgs([
    {
        name: "help", description: "Display this usage guide.",
        alias: "h", type: Boolean
    },
    {
        name: "src", description: "The input files to process",
        alias: "f", type: String, multiple: true, defaultOption: true
    },
    {
        name: "timeout", description: "Timeout value in ms",
        alias: "t", type: Number,  
    }
]);

2. then collect the command line args using .parse()

var options = cli.parse();

options now looks like this:

{
    files: [
        "one.js",
        "two.js"
    ],
    verbose: true,
    timeout: 1000  
}

The .getUsage() method generates a usage guide:

var usage = cli.usage({
    title: "my-app",
    description: "Generates something useful",
    footer: "Project home: [underline]{https://github.com/me/my-app}"
});

..for example:

  my-app
  Generates something useful

  Usage
  $ cat input.json | my-app [<options>]
  $ my-app <files>

  -h, --help               Display this usage guide.
  -v, --verbose            Display this usage guide.
  -f, --src <string[]>     The input files to process
  -t, --timeout <number>   Timeout value in ms

  Project home: https://github.com/me/my-app

Validation

Validation is out of scope for this library, which collects values only. Validate using another module or some code of your own. This example uses test-value.

var cliArgs = require("../");
var testValue = require("test-value");
var fs = require("fs");

var cli = cliArgs([
    { name: "help", type: Boolean },
    { name: "files", type: String, multiple: true, defaultOption: true },
    { name: "log-level", type: String }
]);

var options = cli.parse();

var usageForm = {};

usageForm.main = {
    files: function(files){
        return files && files.every(fs.existsSync);
    },
    "log-level": [ "info", "warn", "error", undefined ]
};

usageForm.help = {
    help: true
};

var valid = testValue(options, [ usageForm.main, usageForm.help ]);

if (!valid){
    // exit here
}

Install

as a library

$ npm install command-line-args --save

as a command-line 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 exporting an option definitions array,

All the following examples can be sampled by installing the command-line-args test harness (install globally). Usage:

$ cat example/one.js | command-line-args --main
{ main: true }

$ cat example/one.js | command-line-args --main --dessert
{ main: true, dessert: true }

API Reference

Modules

command-line-args

definition

## command-line-args

• command-line-args
  • CliArgs ⏏
    • new CliArgs(definitions)
    • .parse([argv]) ⇒ object
    • .getUsage([options]) ⇒ string

CliArgs ⏏

Kind: Exported class

new CliArgs(definitions)

Param	Type
definitions	Array.<definition>

cliArgs.parse([argv]) ⇒ object

Kind: instance method of CliArgs

Param	Type	Description
[argv]	Array.<string>	parses process.argv by default, unless you pass this

cliArgs.getUsage([options]) ⇒ string

Kind: instance method of CliArgs

Param	Type
[options]	module:usage-options

definition

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

Definition ⏏

Option Definition

Kind: Exported class

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

Kind: instance property of Definition

definition.type : function

Take control and be more specific about type..

var fs = require("fs");

function FileDetails(filename){
    if (!(this instanceof FileDetails)) return new FileDetails(filename);
    this.filename = filename;
    this.exists = fs.existsSync(filename);
}

module.exports = [
    { name: "file", type: FileDetails },
    { name: "depth", type: Number }
];

#	Command line args	parse output
5	--file asdf.txt	{ file: { filename: 'asdf.txt', exists: false } }

in 1, main was passed but is set to null (not true, as before) meaning "no value was specified".

#	Command line args	parse output
6	--depth	{ depth: null }
6	--depth 2	{ depth: 2 }

Kind: instance property of Definition

definition.alias : string

Short option names. Must be a single character.

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

#	Command line	parse output
7	-hcd	{ hot: true, courses: null, discount: true }
7	-hdc 3	{ hot: true, discount: true, courses: 3 }

Kind: instance property of Definition

definition.multiple : boolean

module.exports = [
    { name: "files", type: String, multiple: true }
];

#	Command line	parse output
8	--files one.js two.js	{ files: [ 'one.js', 'two.js' ] }
9	--files one.js --files two.js	{ files: [ 'one.js', 'two.js' ] }
10	--files *	{ files: [ 'one.js', 'two.js' ] }

Kind: instance property of Definition

definition.defaultOption : boolean

module.exports = [
    { name: "files", type: String, multiple: true, defaultOption: true }
];

#	Command line	parse output
11	--files one.js two.js	{ files: [ 'one.js', 'two.js' ] }
11	one.js two.js	{ files: [ 'one.js', 'two.js' ] }
12	*	{ files: [ 'one.js', 'two.js' ] }

Kind: instance property of Definition

definition.defaultValue : *

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

#	Command line	parse output
13		{ files: [ 'one.js' ], max: 3 }
14	--files two.js	{ files: [ 'one.js', 'two.js' ], max: 3 }
15	--max 4	{ files: [ 'one.js' ], max: 4 }

Kind: instance property of Definition

definition.group : string | Array.<string>

When your app has a large amount of options it makes sense to organise them in groups. For example, you may want to delegate the videoand audio options to separate 3rd party libraries.

module.exports = [
    { name: "verbose", group: "standard" },
    { name: "help", group: [ "standard", "main" ] },
    { name: "compress", group: [ "server", "main" ] },
    { name: "static", group: "server" },
    { name: "debug" }
];

#	Command line	parse output
13	--verbose	{ _all: { verbose: true }, standard: { verbose: true } }
14	--debug	{ _all: { debug: true }, _none: { debug: true } }
15	--verbose --debug --compress	{ _all: { verbose: true, debug: true, compress: true }, standard: { verbose: true }, server: { compress: true }, main: { compress: true }, _none: { debug: true } }
15	--compress	{ _all: { compress: true }, server: { compress: true }, main: { compress: true } }

Kind: instance property of Definition

definition.description : string

A description for this option.

Kind: instance property of Definition

---

© 2015 Lloyd Brookes <[e-mail]>. Documented by jsdoc-to-markdown.