Node Simple Cli

Utility to create command-line programs.

This utility is built with typescript in mind and has an interactive mode

Install

npm i nodesimplecli

In Action

To see it in action let's build a small cli utility to gather information about sandwich order.

import {NodeSimpleCLI, ErrorType, createFlags} from 'nodesimplecli';

const flags = createFlags({
  bread: {
    alias: '-b',
    flag: '--bread',
    description: 'type of bread',
    argument: true,
    required: true,
  },
  salad: {
    alias: '-s',
    flag: '--salad',
    description: 'add salad',
  },
  sauce: {
    alias: '-u',
    flag: '--sauce',
    description: 'add sauce',
  },
  cheese: {
    alias: '-c',
    flag: '--cheese',
    description: 'add cheese',
  },
});

const cli = new NodeSimpleCLI('subway', '1.0.0');

const onError = (err: ErrorType) => {
  console.log(err.display);
  process.exit(1);
};

const program = cli.parse(process.argv.slice(2), flags, onError);

console.log(
  'You have ordered a sandwich:',
  program.bread + ' bread',
  program.salad ? '+ salad' : '',
  program.sauce ? '+ sauce' : '',
  program.cheese ? '+ cheese' : '',
);

Flags

Commands

If in flag config alias and flag have '-' then it is considered as options. If it doesn't begin with '-' then it is considered as command.

Argument vs Boolean flags

Flags can accept arguments to be passed, this can be done by setting argument: true in the flag config, e.g. in the above program the flag bread requires an argument(type of bread) to be passed, while the rest of the flags are boolean flags. A boolean flag doesn't require an argument they are either present or not.

Boolean flags Shorthand

Multiple boolean flags can be combined together e.g. -c -u -s can also be passed in as -cus.

Required Flags

If a flag has required: true then it becomes a required flag and if it is not present in the cli input onError will receive error.

Auto generated Help

The program auto generates help menu if -h or --help flags are passed.

e.g. if the above program is run with -h flag the following output is received:-

terminal> node sandwich.js -h

Usage: subway [options]

Options:
  -b, --bread <val>  type of bread
  -s, --salad        add salad
  -u, --sauce        add sauce
  -c, --cheese       add cheese

  -h, --help         help
  -v, --version      version

Usage

The usage can be customized by calling usage method.

cli.usage('my custom usage');

terminal> node sandwich.js -h

Usage: subway my custom usage

Options:
  -b, --bread <val>  type of bread
  -s, --salad        add salad
  -u, --sauce        add sauce
  -c, --cheese       add cheese

  -h, --help         help
  -v, --version      version

Auto generated version

If the program is run with -v or --version flag it shows the version of the program.

The version is passed in constructor of SimpleCLI.

Use version from Package.json

If the version is not passed into constructor, the program use the version in Package.json.

Override help and version flags

The program handles -v or --version and -h or --help automatically. However, these can be overwritten by having these flags in the flags object passed to the parse function.

The following will prevent SimpleCLI from handling these flags automatically and you can handle these in your program:-

const flags = {
.
.
.

  help: {
    alias: '-h',
    flag: '--help',
    description: 'help',
  },
  version: {
    alias: '-v',
    flag: '--version',
    description: 'version',
  },
};

const program = cli.parse(process.argv.slice(2), flags, onError);

Interactive Mode

SimpleCLI consists of an interactive mode, which displays the flags in QA form to the user.

const program = await cli.interactive(flags);

// an optional color property can also be passed to it

const program = await cli.interactive(flags, chalk.blue);

terminal> node sandwich.js

bread: Italian
salad (y/n): y
sauce (y/n): n
cheese (y/n): y

You have ordered a sandwich: Italian bread + salad  + cheese

Required

While in interactive mode if a flag has required: true, the value for that program becomes mandatory and an empty value will not be accepted for that flag.

e.g.:-

bread (required):

Errors

List of errors parse function can call the callback for:-

Code	Error
101	An argument for flag is not provided
102	The flag is required
103	An invalid flag is passed