cli-shell

Purpose

If you need to write tiny "devopsy" tooling that takes in XML/JSON/PLAIN data and generates an output then you can use this wrapper to very quickly generate a CLI tool that will run on Node.js

Use

**cli.js**

#!/usr/bin/env node
var cli = require('cli-shell');
var debug = require('debug')('cli');

var ccli = new cli.customCli(
{
  moduleName: 'test',
  defaultActionToExecute: program => {
    return new Promise(s => {
      s(program.inputData
        .map(line => { debug(program.lower); return program.lower ? line.value.toLowerCase(line) : line.value.toUpperCase(line); })
        .join('\r\n')); }); },

  addCliOptions: program => { program.option('-l, --lower', 'this is a test value'); },
  plainTextRegex: line => { return /(.+)/i.exec(line); },
  plainTextObject: match => { return {value: match[1] }; }
});

debug('example...');
cli.cmd(ccli);

Mandatory implementation

The customCli type describes a custom CLI implementation. There is 1 mandatory function that operates on program (commander.js program) has to be implemented:

{
  defaultActionToExecute: function (program) { ... }
}

All CLI properties are exposed to the function through program. This includes flags, input data, and extra information. Input data can be accessed like so:

program.inputData

This is the parsed object that was passed into the CLI by STDIN/JSON/XML/PLAIN (input is prioritized in that order, so that STDIN can overwrite input configs).

Optional fields

{
  moduleName: 'test',
  addCliOptions: program => { program.option('-l, --lower', 'this is a test value'); },
}

moduleName is only used for logging purposes and is optional. addCliOption adds a flag to the CLI program. The flag can then be accessed in defaultAction through the "program" object, like this:

debug(program.lower);

If the input is expected to be plain text, a REGEX and object type can be provided to automatically parse the data into a JS object:

{
  plainTextRegex: line => { return /(.+)/i.exec(line); },
  plainTextObject: match => { return { value: match[1] }; }
}

Rapidly generating a new CLI

Everything that's needed for setup of a new CLI program is included in the generate-cli.sh script. You can use the file from this repository to initialize a new CLI, or do the steps manually:

$ npm init
$ npm i --save cli-shell

$ sed -i -- 's/^}$/\, \"bin\": \{ \"<command>\": \"\.\/bin\/cli\.js\" \} \}/i' package.json

$ mkdir bin
$ touch ./bin/cli.js

$ echo '#!/usr/bin/env node' >> ./bin/cli.js
$ echo "var cli = require('cli-shell');" >> ./bin/cli.js
$ echo "var debug = require('debug')('bwingacfetch-cli');" >> ./bin/cli.js
$ echo "" >> ./bin/cli.js
$ echo "var ccli = new cli.customCli(" >> ./bin/cli.js
$ echo "{" >> ./bin/cli.js
$ echo "  moduleName: 'example'," >> ./bin/cli.js
$ echo "  defaultActionToExecute: program => { return new Promise(s => { s(program.inputData); }); }," >> ./bin/cli.js
$ echo "  addCliOptions: program => { program.option('-l, --lower', 'this is a test value'); }," >> ./bin/cli.js
$ echo "  plainTextRegex: line => { return /(.+)/i.exec(line); }," >> ./bin/cli.js
$ echo "  plainTextObject: match => { return {value: match[1] }; }" >> ./bin/cli.js
$ echo "});" >> ./bin/cli.js
$ echo "" >> ./bin/cli.js
$ echo "debug('calling be-cli module for setting up cli...');" >> ./bin/cli.js
$ echo "cli.cmd(ccli);" >> ./bin/cli.js

The package.json has to include the following setting to configure the cli command and executable file:

**package.json**

  "bin": { "<command>": "./bin/cli.js" }

The executing file needs to include the following code to tell the shell it's an executable NodeJs program:

#!/usr/bin/env node

Once this is setup, you can use:

$ npm i -g
$ npm link

to make the CLI executable globally on the machine and symlink to the folder, to ease development.

Summary

Creating a new CLI program is easy and fast. You need to learn the properties of the customCli type to inject your functionality, and parsing input + producing output will come out of the box.

1. Create npm project and install cli-shell
2. Run the generate-cli script to create cli.js and necessary package.json setting.
3. Define the defaultActionToExecute
4. Install package globally and run in commandline.