cli-kit

    1.14.1 • Public • Published

    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

    Install

    npm i cli-kit

    DownloadsWeekly Downloads

    1,642

    Version

    1.14.1

    License

    MIT

    Unpacked Size

    682 kB

    Total Files

    28

    Last publish

    Collaborators

    • cb1kenobi