# helmsman

> Easily make command line interfaces using git style subcommands

Latest version **2.0.1** (published 2019-08-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install helmsman
pnpm add helmsman
yarn add helmsman
bun add helmsman
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2019-08-04 |
| First published | 2013-06-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 0.10.0 |
| Dependencies | 4 |
| Unpacked size | 20.5 KB |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 51 |
| Author | Matt McManus |
| Maintainers | beaugunderson, mattmcmanus |
| Keywords | cli, command, subcommand, sub-command |

## Links

- npm: https://www.npmjs.com/package/helmsman
- Repository: https://github.com/mattmcmanus/node-helmsman
- Issues: https://github.com/mattmcmanus/node-helmsman/issues
- npm.io page: https://npm.io/package/helmsman

## Dependencies (4)

- [glob](https://npm.io/package/glob.md) ~7.1.4
- [colors](https://npm.io/package/colors.md) ~1.3.3
- [lodash](https://npm.io/package/lodash.md) ~4.17.15
- [underscore.string](https://npm.io/package/underscore.string.md) ~3.3.5

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 2.0.1 (latest) — 2019-08-04
- 2.0.0 — 2019-08-04
- 1.0.3 — 2015-07-27
- 1.0.2 — 2015-07-27
- 1.0.1 — 2015-07-27
- 1.0.0 — 2014-12-16
- 0.4.0 — 2014-08-30
- 0.3.0 — 2014-08-28
- 0.2.6 — 2013-08-23
- 0.2.4 — 2013-07-29
- 0.2.3 — 2013-07-29
- 0.2.2 — 2013-07-16
- 0.2.1 — 2013-07-06
- 0.2.0 — 2013-07-05
- 0.1.1 — 2013-07-02
- … 3 more at https://npm.io/package/helmsman/versions

## 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 `<command> <subcommand>
<arguments/options>` (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 `<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](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: `<command>`

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

```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/<command>-<sub-command>

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

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

* [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)

---
_Source: https://npm.io/package/helmsman · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._