Skip to content

mattmcmanus/node-helmsman

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

68 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

node-helmsman Build Status

Easily make command line interfaces using git style subcommand executables

NPM

So what does helmsman actually do?

A common setup for command line applications is <command> <subcommand> <arguments/options> (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

Features

  • Helmsman is automatically aware of all the <command>-<subcommand> files in your modules bin/ (or any folder you tell it to look at)
  • <command> --help automatically generates help output, telling you all the subcommands that are available to you
  • <command> --version prints the version from package.json of the module requiring helmsman
  • Running <command> <subcommand> automatically executes the <command>-<subcommand> file, passing along all the arguments & options
  • Helmsman is capable of smart command completion including dynamic shorthands and spelling correction (eg: <command> st => <command> status or <command> isntall => <command> install )
  • Use whatever option parsing library you want for your subcommands (optimist, commander, etc)
  • Helmsman is minimally intrusive in your subcommands

Installation & Setup

In your command line application folder:

npm install helmsman --save

Setting up your main executable: <command>

In your main executable, add helmsman:

#!/usr/bin/env node

var helmsman = require('helmsman');

helmsman().parse();

Want to append in additional help messaging or modify the arguments that are parsed?

#!/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);

Setting up your sub-commands: <command>-<subcommand>

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

#!/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, make sure that the sub-commands are executable by running `chmod +x bin/-

API

helmsman([options]) or new Helmsman([options])

  • 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 <module folder>/bin/<command> the localDir will be <module folder>/bin)
  • prefix: The prefix of the subcommands to search for. Defaults to the executed file (eg: If you run <command> it will search for files in the localDir that start with <command>-
  • 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

exports.command

  • 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 <command>"

TODO

Thanks

Much of this was inspired by TJ Holowaychuk's commander and component

About

Easily make command line interfaces using git style subcommands

Resources

License

Stars

Watchers

Forks

Packages

No packages published