Easily make command line interfaces using git style subcommands
npm install helmsmanEasily make command line interfaces using git style subcommand executables

A common setup for command line applications is (for example: git commit -m 'message'). Rather than
having a giant file that switches or if elses over each potential
subcommand, it's much neater to store each subcommand in it's own file
(bin/command,bin/command-subcomand, bin/command-subcommand2, etc).
Helmsman makes it easy to add, modify or delete subcommands without having to
do housekeeping steps in your root command file or package.json
* Helmsman is automatically aware of all the files in
your modules bin/ (or any folder you tell it to look at)
* automatically generates help output, telling you all the
subcommands that are available to you
* prints the version from package.json of the module
requiring helmsman
* Running automatically executes the
file, passing along all the arguments & options
* Helmsman is capable of smart command completion including dynamic shorthands
and spelling correction (eg: => or
=> )
* Use whatever option parsing library you want for your subcommands
(optimist,
commander, etc)
* Helmsman is minimally intrusive in your
subcommands
In your command line application folder:
```
npm install helmsman --save
In your main executable, add helmsman:
`javascript
#!/usr/bin/env node
var helmsman = require('helmsman');
helmsman().parse();
`
Want to append in additional help messaging or modify the arguments that are
parsed?
`javascript
#!/usr/bin/env node
var helmsman = require('helmsman');
var cli = helmsman()
cli.on('--help', function(){
console.log('EXTRA HELPFUL!');
});
var argv = process.argv;
argv.push('--pizza');
// parse() can accept modified arguments, otherwise it defaults to process.argv
cli.parse(argv);
`
For your sub-executables to work with helmsman you need to do two things: 1.
Expose metadata about the task, like its description and 2. Make sure the meat
& potatoes of the script only runs when it's directly called
`javascript
#!/usr/bin/env node
// 1. Expose the metadata
exports.command = {
description: 'Show current worker counts and their pids'
};
// 2. Make sure it only runs when it's directly called:
if (require.main === module) {
// Parse options and run the magic
}
`
Note: If you're not putting each script in package.json's bin object,chmod +x
make sure that the sub-commands are executable by running
bin/
* options {Object}
Create an instance of helmsman. It is an EventEmitter and will also begin
searching for files once it's instantiated.
#### Events
* --help: Emitted when --help is passed as the first option or no commands
or options are passed
#### Options
* localDir: The local module folder where to search for executable files.
Defaults to the directory of the executable (eg: If you execute
the localDir will be )
* prefix: The prefix of the subcommands to search for. Defaults to the
executed file (eg: If you run it will search for files in the
localDir that start with
* metadata: An object containing keys of command names and sub-objects
containing the keys description and optionally arguments
* usePath: If true helmsman will search the PATH for commands matching the
prefix
* fillCommandData: An optional function to use to retrieve metadata from a
command file; takes a defaults object, a filename, and an extension
* fallbackCommandData: If true helmsman will use its default function to
retrieve metadata from a command file if the user-specified fuction returns
a falsy value
* ignoreRequireFail: If true helmsman will ignore failures to require an
extensionless or .js-extensioned command file
* nodePath: The path to the node executable on Windows, defaults to 'node'
#### Methods
* parse([argv]) Parse argv or process.argv if there is no argv and either
display the help or run the subcommand
* description: A one line description of the command. Required.
* arguments: A shorthand for options the subcommand accepts. Generated help
will include it next to command. See help "
* Allow for automatically including npm installed
libraries
Much of this was inspired by TJ Holowaychuk's
commander and
component