Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mattmcmanus/node-helmsman

Easily make command line interfaces using git style subcommands
https://github.com/mattmcmanus/node-helmsman

Last synced: 9 days ago
JSON representation

Easily make command line interfaces using git style subcommands

Awesome Lists containing this project

README 

        
# node-helmsman [![Build Status](https://travis-ci.org/mattmcmanus/node-helmsman.png?branch=master)](https://travis-ci.org/mattmcmanus/node-helmsman)



Easily make command line interfaces using git style subcommand executables



[![NPM](https://nodei.co/npm/helmsman.png?downloads=true)](https://nodei.co/npm/helmsman/)



## So what does helmsman actually do?



A common setup for command line applications is ` 

` (for example: `git commit -m 'message'`). Rather than

having a giant file that `switch`es or `if else`s 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 `-` files in

  your modules `bin/` (or any folder you tell it to look at)

* ` --help` automatically generates help output, telling you all the

  subcommands that are available to you

* ` --version` 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: ` st` => ` status` or

  ` isntall` => ` install` )

* Use whatever option parsing library you want for your subcommands

  ([optimist](https://github.com/substack/node-optimist),

  [commander](https://github.com/visionmedia/commander.js), etc)

* Helmsman is [minimally intrusive in your

  subcommands](#setting-up-your-sub-commands-command-subcommand)



## Installation & Setup



In your command line application folder:



```

npm install helmsman --save

```



### Setting up your main executable: ``



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);

```



### Setting up your sub-commands: `-`



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,

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

  `/bin/` the `localDir` will be `/bin`)

* `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



###  `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 `"



## TODO



* [Allow for automatically including npm installed

  libraries](https://github.com/mattmcmanus/node-helmsman/issues/2)



## Thanks



Much of this was inspired by TJ Holowaychuk's

[commander](https://github.com/visionmedia/commander.js) and

[component](https://github.com/component/component)