ez-cli v0.0.1

ez-cli

(this lib is a work in progress. I went ahead and published early to reserve thename, but I'm working hard now to get it ready-- I promise!)

ez-cli was created to make writing CLI commands, including the necessary help text, switches, error messages, interactive configuration AND automatic completion easy!

ez-cli is built from the ground up to enable anything built with it to be extensible, to provide services to other commands. Anything made with it can ALSO automatically be used as a plug-in to another CLI system. It's hierarchical and (mostly) unopinionated, and heavily inspired by the Express framework and functional programming in general.

Quick start

A minimal cli command that, for example, just echoes what you type might look like:

#!/usr/bin/env node
const EzCli = require('ez-cli');
//Mind the curry! That's how your command gets access to ezcli,
//for example so that a plugin/sub-verb can add multiple verbs under 
//itself, set required parameters, add aliases for shorthand etc.
//think of it this way-- by default, you don't pass the command 
//callback itself to ez-cli, you pass a setup function that returns
//the callback.
EzCli(cli => (switches, ...params) =>
{
	cli.out(params.join(','));
}).run();

But you can do a LOT more:

#!/usr/bin/env node
const EzCli = require('ez-cli');

let cmd = EzCli(cli => 
{
	cli.command('test', cli =>
	{
		cli.help.text('an example command for the cli system');

		return switches => cli.out('first test!');
	});

	cli.command('test2', cli =>
	{
		cli.help.text('another example command for the cli system');

		return switches => cli.out.bold.green('chalk commands are bundled in by default!');
	});

	cli.command('hello', cli =>
	{
		//add switches, with some aliases, and some help text
		cli.booleanSwitch('value', ['v'], 'a switch');
		
		///positional params are the same, just pass their name (used for generating help text) and a description.
		//this adds a measure of self-documenting-ness to your code!
		cli.rParam('a', 'a required param');

		//Just your params in order, but note that a call to `rParam` CANNOT come after a call to `oParam` 
		cli.oParam('b', 'an optional param');

		//the help text is optional, in fact you don't even have to specify params but seriously, why not?
		cli.oParam('c');

		return (switches, a, b, c) =>
		{
			if (switches.value)
				cli.out('you passed a switch value!');
			else
				cli.out('you didn\'t pass a switch value!');

			cli.out('you entered:', a, b, c);
				
		};
	});

	return (switches, ...params) =>
	{
		cli.out.bold.center.yellow('put in a way cool splash screen or something here!');
		//or call help for some usage info.
		cli.verbs.help();

		//the splash function can also be your error handler, or you can define your own by passing a configuration object.
		if (switches._error)
			cli.out.red.bold(switches._error.message);
		if (params.length)
			cli.out.red.bold('unknown command verb: ' + params.join(' '));
	}
}).run();

Info

ez-cli exports a constructor that can either accept a setup function, or a configuration object. The setup function for the base constructor is exactly the same as what's used to add subcommands-- it must accept the cli object and return a callback function.

TODO (coming VERY soon)

• Tabular output (i.e. the ability to just submit objects or arrays or just paramter lists to the logger and have them formatted nicely)
• Might spin off chainify into a third-party library (make it better first)
• Just don't use 0.0.x if you don't want the implementation to break every upgrade. I'm still getting things figured out, and in the interest of moving fast I'll be breaking things. 0.1.x and beyond will impart a kind of contract-- no major changes to behavior then.
• Make stuff like parameters and help ACTUALLY work. I had them working earlier but I restructured and they're broken now. Story of my life.