JSPM

  • Created
  • Published
  • Downloads 1923
  • Score
    100M100P100Q108486F
  • License MIT

Everything you need to create awesome command line interfaces

Package Exports

  • cli-kit

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (cli-kit) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

cli-kit

A command line application toolkit for Node.js.

NPM Version NPM Downloads Build Deps Dev Deps

Features

  • Command line parsing
  • Support for dynamic command hierarchies
  • Auto-generated help
  • CLI template engine
  • External CLI extensions
  • Client and server for remote CLI session such as xterm.js
  • Automatic Node.js version enforcement

Installation

npm install cli-kit --save

Usage

import CLI from 'cli-kit';

(async () => {
    const { argv, _ } = await new CLI({
        options: {
            '-f, --force': 'use the force',
            '--timeout [value]': {
                desc: 'the timeout duration',
                type: 'int'
            }
        }
    }).exec();

    console.log('options:', argv);
    console.log('args:', _);
})();

Architecture

In cli-kit, commands and options are grouped into "contexts". The main CLI instance defines the "global context". Each command defines a new context. Each context can have its own commands, options, and arguments. What you end up with is a hierarchy of contexts.

When cli-kit parses the command line arguments, it will check each argument against the global context to see if the argument can be identified as a known command, option, or argument. If it finds a command, it adds the command's context to a stack and re-parses any unidentified arguments.

This allows you to create deep and dynamic hierarchies of commands, options, and arguments.

Pseudo-Terminal Support

cli-kit extensions can be native binary executables or other Node.js scripts. When the extension is a native executable, then it is executed using Node's spawn(). Note that spawned child processes do not have a TTY and thus things like prompting will not work.

API

class CLI

A CLI intance defines a global context for which you add commands, options, and arguments.

Extends Context > HookEmitter.

constuctor(opts)

  • opts : Object (optional)

    Various options to initialize the CLI instance.

Example
const cli = new CLI({
    // An array of argument definitions. They are parsed in the order they are defined.
    args: [
        // An argument can be as simple as its name. Wrapping the name with `<` and `>` signifies
        // that the argument is required.
        '<arg1>',

        // To define an optional arguemnt, you can use `[` and `]`.
        '[arg2]',

        // Or simply omit the brackets
        'arg3',

        // For more options, you can specify an argument descriptor
        {
            // The argument name. Follows the same rules as above.
            name: 'arg4',

            // The argument's description to show in the help output.
            desc: undefined,

            // When `true`, hides the argument from usage string in the help output.
            hidden: false,

            // When `true`, captures all subsequent argument values into an array
            multiple: false,

            // Overrides the brackets and forces the argument to be required or optional.
            required: false,

            // There are several built-in types. See the "types" section below for more info.
            type: 'string'
        },

        // Adding `...` will capture all subsequent argument values into an array
        'arg4...'
    ],

    // Global flag to camel case property names derived from multi-word options/arguments.
    // Defaults to true, can be overwritten by the option/argument.
    camelCase: true,

    // An object of command names to command descriptors.
    commands: {
        'some-command': {
            // The action to perform when the command is parsed.
            action({ argv, _ }) {
                console.log('options:', argv);
                console.log('args:', _);
            },

            // An array of alternate command names.
            aliases: [ 'another-command' ],

            // Command specific args. See `args` section above.
            args: [],

            // When `true`, camel case all option and argument names in the `argv` result.
            camelCase: true,

            // An object of subcommand names to subcommand descriptors.
            commands: {},

            // The command description.
            desc: undefined,

            // When `true`, hides the command from the help output.
            hidden: false,

            // An object of option formats to option descriptors. See the `options` section below.
            options: {},

            // The command name to display in the help output. Defaults to the command name.
            title: undefined
        }
    },

    // The default command `exec()` should run if no command was found during parsing.
    // If `help` is `true` and no default command is specified, it will default to displaying the
    // help screen. If you want help, but do not want to default to the help command, then set the
    // `defaultCommand` to `null`.
    defaultCommand: undefined,

    // The CLI description to print on the help screen between the usage and commands/options/args.
    desc: undefined,

    // Adds the `-h, --help` to the global flags and enables the auto-generated help screen.
    // Defaults to `true`.
    help: true,

    // The exit code to return when the help screen is displayed. This is useful if you want to
    // force the program to exit if `--help` is specified and the user is chaining commands together
    // or after displaying the help screen and prevent further execution in the CLI's promise chain.
    helpExitCode: undefined,

    // The name of the program used by the help screen to display the command's usage.
    // Defaults to "program".
    name: 'program',

    // An object of option formats to option descriptors or an array of sorted group names and
    // objects of option formats to option descriptors.
    options: {
        //
    },

    // The title for the top-level (or "Global") context. This title is displayed on the help screen
    // when displaying the list of options.
    title: 'Global',

    // When set, it will automatically wire up the `-v, --version` option. Upon calling with your
    // program with `--version`, it will display the version and exit with a success (zero) exit
    // code.
    version: null
});

exec(args)

Parses the command line args and executes a command, if found.

  • args : Array<String> (optional)

    An array of arguments. Each argument is expected to be a string.

    Defaults to process.argv.slice(2).

Returns a Promise that resolves an Arguments object. This object will contain the parsed options in argv and arguments in _.

Example
cli.exec()
    .then(({ argv, _ }) => {
        console.log('options:', argv);
        console.log('args:', _);
    });

class Context

Base class for CLI and Command classes.

Extends HookEmitter.

argument(arg)

Adds an argument to a CLI or Command.

  • arg : Argument, Object, or String.

    An argument descriptor. Either an Argument instance or an Object to pass into a Argument constructor.

    An argument requires a name.

Returns a reference to the CLI or Command.

Example
// define a non-required argument "foo"
cli.argument('foo');

// define a non-required argument "wiz"
cli.argument('[wiz]');

// define a required argument "pow"
cli.argument('<pow>');

cli.argument({
    name: 'bar',
    type: 'int'
});

cli.argument(new Argument('baz'));

command(cmd, opts)

Adds a command to a CLI or Command.

TODO

option(optOrFormat, group, params)

Adds an option or group of options to a CLI or Command.

TODO

Who Uses cli-kit?

License

MIT