Usage

1var CLI = require( '@stdlib/cli-ctor' );

CLI( [options] )

Command-line interface (CLI) constructor.

1var cli = new CLI();
2// returns <CLI>

The constructor accepts the following options:

• pkg: package meta data, such as a package.json object.
• version: command-line interface version. Default: pkg.version.
• title: process title. If set to true, the default title is either pkg.bin.<field> or pkg.name. If set to a string, the function sets the process title to the specified string. If set to false, the function does not set the process title.
• help: help text. Default: ''.
• updates: boolean indicating whether to check if a more recent version of a command-line interface exists in the package registry. In order to check for updates, the function requires both pkg.name and pkg.version meta data. Default: true.
• argv: an array of command-line arguments. Default: process.argv.
• options: command-line argument parser options.

To provide package meta data, such as the package name and version, set the pkg option.

1var opts = {
2    'pkg': require( './package.json' )
3};
4
5var cli = new CLI( opts );
6// returns <CLI>

To specify a particular command-line interface version (overriding package meta data), set the version option.

1var opts = {
2    'pkg': {
3        'name': 'beep',
4        'version': '1.1.1'
5    },
6    'version': '1.1.1-beta'
7};
8
9var cli = new CLI( opts );
10// returns <CLI>
11
12cli.version();
13// => 1.1.1-beta

By default, an instance sets the process title to either the first key in pkg.bin or to pkg.name. To explicitly set the process title, set the title option.

1var proc = require( 'process' );
2
3var opts = {
4    'title': 'beep-boop'
5};
6
7var cli = new CLI( opts );
8// returns <CLI>
9
10console.log( proc.title );
11// => 'beep-boop'

To disable setting the process title, set the title option to false.

1var opts = {
2    'title': false
3};
4
5var cli = new CLI( opts );
6// returns <CLI>

When the command-line flag --help is set, a command-line interface instance prints help text and exits the calling process. To specify the printed text, set the help option.

1var opts = {
2    'help': 'Usage: boop [options] <beep>',
3    'argv': [
4        '/usr/local/bin/node',
5        'foo.js',
6        '--help'
7    ]
8};
9
10var cli = new CLI( opts );
11// => Usage: boop [options] <beep>

By default, an instance resolves command-line arguments and flags via process.argv. To specify a custom set of command-line arguments, set the argv option.

1var opts = {
2    'argv': [
3        '/usr/local/bin/node',
4        'foo.js',
5        'a',
6        'b',
7        'c'
8    ]
9};
10
11var cli = new CLI( opts );
12
13var args = cli.args();
14// returns [ 'a', 'b', 'c' ]

To specify command-line argument parser options, such as command-line flag types and aliases, set the options option.

1var opts = {
2    'options': {
3        'boolean': [
4            'help',
5            'version'
6        ],
7        'string': [
8            'output'
9        ],
10        'alias': {
11            'help': [
12                'h'
13            ],
14            'version': [
15                'V'
16            ],
17            'output': [
18                'o'
19            ]
20        }
21    },
22    'argv': [
23        '/usr/local/bin/node',
24        'foo.js',
25        '-o=bar.js'
26    ]
27};
28
29var cli = new CLI( opts );
30
31var flags = cli.flags();
32/* returns
33    {
34        'h': false,
35        'help': false,
36        'V': false,
37        'version': false,
38        'o': 'bar.js',
39        'output': 'bar.js'
40    }
41*/

By default, if provided sufficient package meta data (package name and version), an instance checks whether a newer version of a command-line interface exists in the package registry. If a newer version exists, an instance writes a message to stdout indicating that a newer version exists. To disable this check, set the updates option to false.

1var opts = {
2    'updates': false
3};
4
5var cli = new CLI( opts );
6// returns <CLI>

Prototype Methods

CLI.prototype.close( [code] )

Gracefully exits a command-line interface and the calling process.

1var cli = new CLI();
2
3// Gracefully exit:
4cli.close();

To specify an exit code, provide a code argument.

1var cli = new CLI();
2
3// Set the exit code to `1`:
4cli.close( 1 );

CLI.prototype.error( error[, code] )

Prints an error message to stderr and exits a command-line interface and the calling process.

1var cli = new CLI();
2
3// ...
4
5// Create a new error object:
6var err = new Error( 'invalid argument' );
7
8// Exit due to the error:
9cli.error( err );

When exiting due to an error, the default exit code is 1. To specify an alternative exit code, provide a code argument.

1var cli = new CLI();
2
3// ...
4
5// Create a new error object:
6var err = new Error( 'invalid argument' );
7
8// Exit due to the error:
9cli.error( err, 2 );

CLI.prototype.exit( [code] )

Forcefully exits a command-line interface and the calling process.

1var cli = new CLI();
2
3// Forcefully exit:
4cli.exit();

To specify an exit code, provide a code argument.

1var cli = new CLI();
2
3// Set the exit code to `1`:
4cli.exit( 1 );

Instance Methods

cli.args()

Returns a list of command-line arguments.

1var cli = new CLI({
2    'argv': [
3        '/usr/local/bin/node',
4        'foo.js',
5        'a',
6        '--b',
7        'c',
8        'd'
9    ]
10});
11
12var args = cli.args();
13// returns [ 'a', 'd' ]

cli.flags()

Returns command-line flags.

1var cli = new CLI({
2    'argv': [
3        '/usr/local/bin/node',
4        'foo.js',
5        'a',
6        '--b',
7        'c',
8        '-def',
9        '--g=h',
10        'i'
11    ]
12});
13
14var flags = cli.flags();
15// returns { 'b': 'c', 'd': true, 'e': true, 'f': true, 'g': 'h' }

cli.help( [code] )

Prints help text to stderr and then exits the calling process.

1var cli = new CLI({
2    'help': 'Usage: beep [options] <boop>'
3});
4
5cli.help();
6// => Usage: beep [options] <boop>

By default, the process exits with an exit code equal to 0. To exit with a different exit code, provide a code argument.

cli.version()

Prints the command-line interface version to stderr and then exits the calling process.

1var cli = new CLI({
2    'version': '1.1.1'
3});
4
5cli.version();
6// => 1.1.1