generator-sub

A Yeoman generator for writing cli apps inspired by 37signals sub

Features

Commands

Here's the commands sub comes with out of the box

A simple cli application. Broken into sub commands, invoked under sub:
    commands:  Lists all commands.
    example:  An example command.
    help:  Gets help for a sub command.
    init:  Set up configuration for example-sub. Runs interactive commands to walk you through setting up config.
    update:  Updates example-sub by pulling the most recent commit from the master branch of the remote git repository.

But wait there's more

Updating from git or npm
User-managed config
Help parsed from subcommand comments

Installation

First, install Yeoman and generator-sub using npm (we assume you have pre-installed node.js).

npm install -g yo
npm install -g generator-sub

Then generate your new project:

yo sub

Running the generated cli app locally

For example, suppose you generated a cli app called sub.

First, link the new package

npm link

Then, get the help

» sub help
[INFO] A simple cli application. Broken into sub commands, invoked under sub:
[INFO]     commands:  Lists all commands.
[INFO]     completions:  Gets autocompletions.
[INFO]     example:  An example command.
[INFO]     help:  Gets the help text for a command.
[INFO]     init:  Set up configuration for example. Runs interactive commands to walk you through setting up config.
[INFO]     update:  Updates example by pulling the most recent commit from the master branch of the remote git repository.
[INFO]     version:  Logs the installed version
[INFO] Also takes the flag --noUpdate to prevent auto updating.

And run the example sub command

» sub example
You ran the example command!

Adding a new sub command

Say you wanted to add a new subcommand, random, which prints a random number between 0 and a provided argument when invoked. First, generate a new sub command

yo sub:command

And verify that everything worked as anticipated

npm link
sub random
> You ran the random command!

Then, add your new logic inside the exported function inside lib/random.js

/**
 * Returns a random number between 0 and the argument value
 * Usage:
 *      sub random 100
 *      > 80.6944249663502
 */
module.exports = function({ argv, logger }){
  return new Promise((resolve, reject) => {
    logger.info(Math.random()*(+argv._[1]));
    resolve();
  });
}

And then test your new command locally

sub random 100
> 80.6944249663502

Example

See the boilerplate generated by thie generator here, or a sample cli app generated using this generator here.

Inspired By

This generator is Inspired 37signals sub. Read more about their pattern.

Getting To Know Yeoman

Yeoman has a heart of gold. He's a person with feelings and opinions, but he's very easy to work with. If you think he's too opinionated, he can be easily convinced. Feel free to learn more about him.

Contributing

Please make sure it passes static analysis and the unit tests

npm test

And make sure to discuss new features in an issue before you send a pull request.

doug-wade / generator-sub

readme