CLI

Command-line interface.

Installation

npm install @stdlib/cli-ctor

Usage

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

CLI( [options] )

Command-line interface (CLI) constructor.

var cli = new CLI();
// 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.

var opts = {
    'pkg': require( './package.json' )
};

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

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

var opts = {
    'pkg': {
        'name': 'beep',
        'version': '1.1.1'
    },
    'version': '1.1.1-beta'
};

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

cli.version();
// => 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.

var proc = require( 'process' );

var opts = {
    'title': 'beep-boop'
};

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

console.log( proc.title );
// => 'beep-boop'

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

var opts = {
    'title': false
};

var cli = new CLI( opts );
// 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.

var opts = {
    'help': 'Usage: boop [options] <beep>',
    'argv': [
        '/usr/local/bin/node',
        'foo.js',
        '--help'
    ]
};

var cli = new CLI( opts );
// => 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.

var opts = {
    'argv': [
        '/usr/local/bin/node',
        'foo.js',
        'a',
        'b',
        'c'
    ]
};

var cli = new CLI( opts );

var args = cli.args();
// returns [ 'a', 'b', 'c' ]

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

var opts = {
    'options': {
        'boolean': [
            'help',
            'version'
        ],
        'string': [
            'output'
        ],
        'alias': {
            'help': [
                'h'
            ],
            'version': [
                'V'
            ],
            'output': [
                'o'
            ]
        }
    },
    'argv': [
        '/usr/local/bin/node',
        'foo.js',
        '-o=bar.js'
    ]
};

var cli = new CLI( opts );

var flags = cli.flags();
/* returns
    {
        'h': false,
        'help': false,
        'V': false,
        'version': false,
        'o': 'bar.js',
        'output': 'bar.js'
    }
*/

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.

var opts = {
    'updates': false
};

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

Prototype Methods

CLI.prototype.close( [code] )

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

var cli = new CLI();

// Gracefully exit:
cli.close();

To specify an exit code, provide a code argument.

var cli = new CLI();

// Set the exit code to `1`:
cli.close( 1 );

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

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

var cli = new CLI();

// ...

// Create a new error object:
var err = new Error( 'invalid argument' );

// Exit due to the error:
cli.error( err );

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

var cli = new CLI();

// ...

// Create a new error object:
var err = new Error( 'invalid argument' );

// Exit due to the error:
cli.error( err, 2 );

CLI.prototype.exit( [code] )

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

var cli = new CLI();

// Forcefully exit:
cli.exit();

To specify an exit code, provide a code argument.

var cli = new CLI();

// Set the exit code to `1`:
cli.exit( 1 );

Instance Methods

cli.args()

Returns a list of command-line arguments.

var cli = new CLI({
    'argv': [
        '/usr/local/bin/node',
        'foo.js',
        'a',
        '--b',
        'c',
        'd'
    ]
});

var args = cli.args();
// returns [ 'a', 'd' ]

cli.flags()

Returns command-line flags.

var cli = new CLI({
    'argv': [
        '/usr/local/bin/node',
        'foo.js',
        'a',
        '--b',
        'c',
        '-def',
        '--g=h',
        'i'
    ]
});

var flags = cli.flags();
// 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.

var cli = new CLI({
    'help': 'Usage: beep [options] <boop>'
});

cli.help();
// => 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.

var cli = new CLI({
    'version': '1.1.1'
});

cli.version();
// => 1.1.1

Notes

• When either --help or --version command-line flag is set, a command-line interface instance prints the respective value and then exits the calling process.
• When explicitly setting options.argv, the first element is reserved for the absolute pathname of the executable which launched the calling process and the second element is reserved for the file path of the executed JavaScript file.

Examples

var join = require( 'path' ).join;
var readFileSync = require( '@stdlib/fs-read-file' ).sync;
var CLI = require( '@stdlib/cli-ctor' );
var main = require( './examples/fixtures/main.js' );

// Load help text:
var fopts = {
    'encoding': 'utf8'
};
var help = readFileSync( join( __dirname, 'examples', 'fixtures', 'usage.txt' ), fopts );

// Set the command-line interface options:
var opts = {
    'pkg': require( './package.json' ),
    'options': require( './examples/fixtures/opts.json' ),
    'help': help,
    'title': true,
    'updates': true
};

// Create a new command-line interface:
var cli = new CLI( opts );

// Run main:
main( 'beep' );

// Close:
cli.close( 0 );

Notice

This package is part of stdlib, a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more.

For more information on the project, filing bug reports and feature requests, and guidance on how to develop stdlib, see the main project repository.

Community

License

See LICENSE.

Copyright

Copyright © 2016-2024. The Stdlib Authors.