Home

Awesome

node-cmdln is a node.js helper lib for creating CLI tools with subcommands (think git, svn, zfs, brew, etc.). It is a sister of my earlier Python lib for this.

Usage

You define a subclass of Cmdln and subcommands as do_NAME methods. Minimally you could have a "conan.js" as follows:

#!/usr/bin/env node
var util = require('util');
var cmdln = require('cmdln');

function Conan() {
    cmdln.Cmdln.call(this, {
        name: 'conan',
        desc: 'What is best in life?'
    });
}
util.inherits(Conan, cmdln.Cmdln);

Conan.prototype.do_crush = function do_crush(subcmd, opts, args, cb) {
    console.log('Yargh!');
    cb();
};
Conan.prototype.do_crush.help = 'Crush your enemies.';

cmdln.main(new Conan());  // mainline

With this, you get the following behaviour:

$ node examples/conan.js
What is best in life?

Usage:
    conan [OPTIONS] COMMAND [ARGS...]
    conan help COMMAND

Options:
    -h, --help      Show this help message and exit.

Commands:
    help (?)        Help on a specific sub-command.
    crush           Crush your enemies.

$ node examples/conan.js help crush
Crush your enemies.

$ node examples/conan.js crush
Yargh!

Option processing

Option processing (using dashdash) is integrated. do_crush above could be replaced with:

Conan.prototype.do_crush = function (subcmd, opts, args, cb) {
    if (opts.help) {
        this.do_help('help', {}, [subcmd], cb);
        return;
    }
    if (!args.length) {
        console.log('No enemies? Yarg!');
    } else {
        args.forEach(function (enemy) {
            console.log('Smite %s with a %s!', enemy, opts.weapon);
        });
    }
    cb();
};
Conan.prototype.do_crush.options = [
    {
        names: ['help', 'h'],
        type: 'bool',
        help: 'Show this help.'
    },
    {
        names: ['weapon', 'w'],
        helpArg: 'WEAPON',
        type: 'string',
        default: 'sword',
        help: 'Weapon with which to smite.'
    }
];
Conan.prototype.do_crush.help = (
    'Crush your enemies.\n'
    + '\n'
    + 'Usage:\n'
    + '     {{name}} {{cmd}} [OPTIONS] [ENEMIES...]\n'
    + '\n'
    + '{{options}}'
);

Then we get this behaviour:

$ node examples/conan.js crush Bob
Smite Bob with a sword!

$ node examples/conan.js crush Bob Linda --weapon mattock
Smite Bob with a mattock!
Smite Linda with a mattock!

$ node examples/conan.js crush -h
Crush your enemies.

Usage:
     conan crush [OPTIONS] [ENEMIES...]

Options:
    -h, --help                  Show this help.
    -w WEAPON, --weapon=WEAPON  Weapon with which to smite.

See examples/conan.js for the complete example. Run node example/conan.js ... to try it out.

Bash completion

One can generate Bash completion code for a Cmdln subclass via

cli.bashCompletion()

One possible usage is to add a completion subcmd to your CLI:

CLI.prototype.do_completion = function (subcmd, opts, args, cb) {
    console.log( this.bashCompletion() );
    cb();
};

and get users to use that to setup Bash completion:

$ alias conan="node examples/conan.js"
$ conan completion > conan.completion
$ source conan.completion

$ conan <TAB>
crush      hear       help       pulverize  see        smash
$ conan -<TAB>
--help     --verbose  --version  -h         -v         -x
$ conan crush --weapon <TAB>            # custom 'weapon' completion type
bow-and-array  mattock        spear          sword
$ conan crush --weapon spear <TAB>      # custom 'enemy' completion type
King-Osric    Subotai       Thulsa-Doom   _mbsetupuser  trentm

See the do_completion subcommand on "examples/conan.js" for a complete example of this. See the equivalent in the larger triton tool for another example: https://github.com/joyent/node-triton/blob/master/lib/do_completion.js.

Another potential usage could be to pre-generate a completion file and distribute it with your tool.

Reference

In general, also please read the comments in the source and browse the examples.

cmdln.Cmdln

To use this module you create a class that inherits from cmdln.Cmdln; add some methods to that class that define the tool's commands, options, etc.; then pass an instance to cmdln.main(). Roughly like this:

function CLI() {
    cmdln.Cmdln.call(this, {<config>});
}
util.inherits(CLI, cmdln.Cmdln);
...
var cli = new CLI();
cmdln.main(cli);

We'll use the CLI and cli names as used above in the following reference:

cmdln.main()

This is a convenience method for driving the mainline of your script using the your defined Cmdln subclass. There are a number of options to control how it works. Read the block comment on that function in "lib/cmdln.js" for the best docs.

errHelp and Errors

cmdln v4 introduced subcmd synopses, errHelp, and some related functionality to help provide brief automatic command help for some usage errors. errHelp is a brief message after a printed error, giving potentially helpful info. Some examples from familiar commands (marked here with >):

    $ ls -D
    ls: illegal option -- D
>   usage: ls [-ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1] [file ...]

    $ git foo
    git: 'foo' is not a git command. See 'git --help'.

>   Did you mean this?
>          fo

Use the following suggestions to get this kind of error-help for your commands:

  1. Optionally set synopses on your subcmd handlers. E.g.:

     do_list.synopses = ['{{name}} list [OPTIONS] FILTERS...'];

    Doing so allows two things: (a) the use of the {{usage}} template var in your command help, and (b) use of those synopses for errHelp.

  2. Optionally use the {{usage}} template var in your command help. E.g.:

     do_list.help = [
     'List instances.',
     '',
     '{{usage}}',
     '',
     '{{options}}'
 ].join('\n');

  3. Optionally use the cmdln.UsageError error class for usage errors in your subcmds. E.g.:

     function do_list(subcmd, opts, args, callback) {
     // ...
     } else if (args.length < 1) {
         callback(new cmdln.UsageError('missing FILTER args'));
         return;
     }

  4. Use cmdln.main() for your mainline

    This will now attempt to determine errHelp from any returned error and print it on stderr -- use options.showErrHelp=false to disable. Or if you are not using cmdln.main(), then you can use cmdln.errHelpFromErr(err) to get errHelp to print, if you like.

Error help is determined by calling err.cmdlnErrHelpFromErr(), which is implemented for cmdln's error classes:

You can implement that method for custom error classes if you like.

cmdln.dashdash

This is a re-export of the dashdash option processing module that cmdln is using. This is exported so that calling code can add option types if wanted, via cmdln.dashdash.addOptionType. E.g.,

var cmdln = require('cmdln');

function parseCommaSepStringNoEmpties(option, optstr, arg) {
    return arg.trim().split(/\s*,\s*/g)
        .filter(function (part) { return part; });
}

cmdln.dashdash.addOptionType({
    name: 'commaSepString',
    takesArg: true,
    helpArg: 'STRING',
    parseArg: parseCommaSepStringNoEmpties
});

// ...

See the node-dashdash documentation for details.

License

MIT. See LICENSE.txt