Multitool JS / CLI Maker

Creator for CLI apps.

To create a new CLI you can just run:

    const { CLI } = require('@multitool-js/climaker');

    const myCli = new CLI([
        //commands
    ],{
        // options
    });

Options

Option	Description	Default
base	Path/command of the app, is visible in the description	node ${path.relative(process.cwd(), process.argv[1])}
throwOnMissingFlag	Throws an error before command execution if a required flag is missing	true
throwOnMissingArg	Throws an error before command execution if a required argument is missing	true
throwOnUnknownFlag	Throws an error before command execution if a non-specified flag is found	false
throwOnUnexpectedArguments	Throws an error before command execution if there are any non-parsed tokens left in the arguments	false
passthrough	When true, remaining tokens are passed to the exec function under __args, pass a string to define the variable name	false
helpFlag	Defines a flag to invoke the help output of a command. You can pass either true to use the default --help and -h or an object like { name: "help", shorthand: "h" }, shorthand is optional	true

Commands

Each command has the following properties:

Property	Type	Description	Required	Default
name	string	Name of the command	Yes
exec	function	Execution function, is called when the command is selected. Accepts the parsed flags and arguments.	Yes
alias	string|string[]	List of possible aliases for the command	No
description	string	Command description to show on help	No
extendedDescription	string	Additional description to show on command-specific help	No
flags	[]	List of flags to parse	No
arguments	[]	List of arguments to parse	No
throwOnMissingFlag	boolean	As in options, when set overrides the parent value	No	true
throwOnMissingArg	boolean	As in options, when set overrides the parent value	No	true
throwOnUnknownFlag	boolean	As in options, when set overrides the parent value	No	false
throwOnUnexpectedArguments	boolean	As in options, when set overrides the parent value	No	false
passthrough	string|boolean	As in options, when set overrides the parent value	No	false

Flags

Each flag has the --name structure. Shorthands use a single letter -c
Different types of flags exist:

Type	Example	Description	Output
bool	--test, -t	Boolean flag, if present the output is true, false otherwise	boolean
value	--foo=bar, -f=bar, --foo bar, -f bar	Value flag, can be written with or without =, reads the value and outputs it, only consumes the first occurrence of the flag	string
multivalue	--foo=bar --foo=baz	Like the value type, but can be set multiple times, the output is an array of all the occurrences	string[]

Options

Each flag has the following properties:

Property	Type	Description	Required	Default
name	string	Name of the flag	Yes
shorthand	string	Shorthand name of the flag	No
type	'bool'|'value'|'multivalue'		No	'bool'
description	string	Description of the flag, used in the help	No
variableName	string	Name of the variable passed to the command execution function. Defaults to the flag name.	No	name
required	boolean	If true an error is thrown if the flag is missing	No	false

Arguments

Options

Each argument has the following properties:

Property	Type	Description	Required	Default
name	string	Name of the flag	Yes
description	string	Description of the flag, used in the help	No
variableName	string	Name of the variable passed to the command execution function. Defaults to the flag name.	No	name
required	boolean	If true an error is thrown if the flag is missing	No	false

Default CLI

For convenience, a default cli instance is available as cli:

    const { cli } = require('@multitool-js/climaker');

To register new commands use the register method:

    cli.register({
        // command options
    })

To change settings you can set the corrisponding variable:

    cli.helpFlag = {
        name: "help-me",
        shorthand: "H"
    }

Examples

Create a new CLI with the command "hello-world"

    const { CLI } = require('@multitool-js/climaker');

    const myCli = new CLI([{
        name: "hello-world",
        exec: () => console.log('Hello world!'),
        description: "Says hello world!"
    }]);

    myCli.execute();

Assuming the CLI is defined in the myCli.js file:

$ node myCli.js help
$ Available commands:
$
$ hello-world:
$   Says hello world!

$ node myCli.js hello-world
$ Hello world!

Following the above example, register a new command hello with an argument.

NOTE: always ensure to replace register new commands before invoking the execute method.

    myCli.register({
        name: 'hello',
        exec: ({ target, happy, uppercase }) => {
            let text = `Hello ${target}!`;
            if (happy) text += ' :)';
            if (uppercase) text = text.toUpperCase();
            console.log(text);
        },
        description: 'Says hello to someone!',
        arguments: [{
            name: 'target',
            required: true
        }],
        flags: [{
            name: 'happy',
            shorthand: 'H'
        }, {
            name: 'uppercase'
        }]
    });
    
    myCli.execute();

$ node myCli.js help
$ Available commands:
$ 
$ hello-world:
$   Says hello world!
$ 
$ hello:
$   Says hello to someone!

$ node myCli.js hello universe -H
$ HELLO UNIVERSE! :)