cli-kit

A command line application toolkit for Node.js.

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

1import CLI from 'cli-kit';
2
3(async () => {
4	const { argv, _ } = await new CLI({
5		options: {
6			'-f, --force': 'use the force',
7			'--timeout [value]': {
8				desc: 'the timeout duration',
9				type: 'int'
10			}
11		}
12	}).exec();
13
14	console.log('options:', argv);
15	console.log('args:', _);
16})();

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

1const cli = new CLI({
2	// An array of argument definitions. They are parsed in the order they are defined.
3	args: [
4		// An argument can be as simple as its name. Wrapping the name with `<` and `>` signifies
5		// that the argument is required.
6		'<arg1>',
7
8		// To define an optional arguemnt, you can use `[` and `]`.
9		'[arg2]',
10
11		// Or simply omit the brackets
12		'arg3',
13
14		// For more options, you can specify an argument descriptor
15		{
16			// The argument name. Follows the same rules as above.
17			name: 'arg4',
18
19			// The argument's description to show in the help output.
20			desc: undefined,
21
22			// When `true`, hides the argument from usage string in the help output.
23			hidden: false,
24
25			// When `true`, captures all subsequent argument values into an array
26			multiple: false,
27
28			// Overrides the brackets and forces the argument to be required or optional.
29			required: false,
30
31			// There are several built-in types. See the "types" section below for more info.
32			type: 'string'
33		},
34
35		// Adding `...` will capture all subsequent argument values into an array
36		'arg4...'
37	],
38
39	// Global flag to camel case property names derived from multi-word options/arguments.
40	// Defaults to true, can be overwritten by the option/argument.
41	camelCase: true,
42
43	// An object of command names to command descriptors.
44	commands: {
45		'some-command': {
46			// The action to perform when the command is parsed.
47			action({ argv, _ }) {
48				console.log('options:', argv);
49				console.log('args:', _);
50			},
51
52			// An array of alternate command names.
53			aliases: [ 'another-command' ],
54
55			// Command specific args. See `args` section above.
56			args: [],
57
58			// When `true`, camel case all option and argument names in the `argv` result.
59			camelCase: true,
60
61			// An object of subcommand names to subcommand descriptors.
62			commands: {},
63
64			// The command description.
65			desc: undefined,
66
67			// When `true`, hides the command from the help output.
68			hidden: false,
69
70			// An object of option formats to option descriptors. See the `options` section below.
71			options: {},
72
73			// The command name to display in the help output. Defaults to the command name.
74			title: undefined
75		}
76	},
77
78	// The default command `exec()` should run if no command was found during parsing.
79	// If `help` is `true` and no default command is specified, it will default to displaying the
80	// help screen. If you want help, but do not want to default to the help command, then set the
81	// `defaultCommand` to `null`.
82	defaultCommand: undefined,
83
84	// The CLI description to print on the help screen between the usage and commands/options/args.
85	desc: undefined,
86
87	// Adds the `-h, --help` to the global flags and enables the auto-generated help screen.
88	// Defaults to `true`.
89	help: true,
90
91	// The exit code to return when the help screen is displayed. This is useful if you want to
92	// force the program to exit if `--help` is specified and the user is chaining commands together
93	// or after displaying the help screen and prevent further execution in the CLI's promise chain.
94	helpExitCode: undefined,
95
96	// The name of the program used by the help screen to display the command's usage.
97	// Defaults to "program".
98	name: 'program',
99
100	// An object of option formats to option descriptors or an array of sorted group names and
101	// objects of option formats to option descriptors.
102	options: {
103		//
104	},
105
106	// The title for the top-level (or "Global") context. This title is displayed on the help screen
107	// when displaying the list of options.
108	title: 'Global',
109
110	// When set, it will automatically wire up the `-v, --version` option. Upon calling with your
111	// program with `--version`, it will display the version and exit with a success (zero) exit
112	// code.
113	version: null
114});

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

1cli.exec()
2	.then(({ argv, _ }) => {
3		console.log('options:', argv);
4		console.log('args:', _);
5	});

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

1// define a non-required argument "foo"
2cli.argument('foo');
3
4// define a non-required argument "wiz"
5cli.argument('[wiz]');
6
7// define a required argument "pow"
8cli.argument('<pow>');
9
10cli.argument({
11	name: 'bar',
12	type: 'int'
13});
14
15cli.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?

• Axway

License

MIT