Home Reference Source Test Repository

Console Commando

Build Status Documentation

A library for creating command line tools with node.

Installation:

npm install --save console-commando

Why use this instead of [insert library here]

This library is greatly inspired in Commander, but optimized for recursive commands. I couldn't find a library that would let me easily set up simple commands as well as complicated command structures in a consistent way.

This library aims to provide a very simple way of creating all kinds of commands, from simple commands with options, to semantic commands with several levels of recursion.

With this library you can create commands that make sense very easily. The following for example would be trivial to set up:

mycommand my-resource my-action --an-option --another=option and arbitrary arguments

This library also produces easy to read help automatically.

Usage

Simple Command

You can create simple commands very easily. Just set the options and an action. The action will be called with any options.

var Commando = require('console-commando');

// Create a new command, with name, version and description.
var command = new Commando('command-name')
  .version('1.0.1')
  .description('')

  // Add global options.
  .option('-h --host <host>', 'Host name')
  .option('-p --port <port>', 'Port number', '8080')
  .option('-d --debug', 'Log all output', true)

  // Define an action.
  .action(function (command) {

  });

  // Pass arguments to the command and run it.
  commando.args(process.argv.slice(2)).run();

Subcommands

You can add subcommands to your command any time by using the command method:

var Commando = require('console-commando');

// Create a new command, with name, version and description.
var command = new Commando('command-name')
  .version('1.0.1')
  .description('')

  // Add global options.
  .option('-v --verbose', 'Log more output', true)

  // Act on global options, before any sub commands are executed.
  .before(function (command) {

  })

  // Add a subcommand.
  .command(
    // Sub commands are also commands.
    new Commando('subcommand')
      // You can add options.
      .option('-s --sub-option [subOption]', 'An option for the subcommand')
      // Define an action for this sub command.
      .action(function (command, rootCommand) {
        // You can access the current subcomand or the root command.
        // Get options for this command.
        var subOption = command.getOption('subOption');
        // Or get global options for the root command.
        var verbose = rootCommand.getOption('verbose');
      })

      // And you can add sub commands to sub commands too.
      .command(
        // ...
        // and so on, and so forth
      )
  );

  // Pass arguments to the command and run it.
  commando.args(process.argv.slice(2)).run();

CLI auto completion

Similarly to npm completion, console-commando makes it easy to get auto completion for your commands.

Simply run the following in your terminal:

source <(your-command completion)

Note that this assumes the command has been installed as an exacutable command with the name specified in the root Commando.

After doing this you should be able to auto complete your command, subcommands and options when hitting the tab key twice.

API

Console commando's public API is based in the Commando class. Instances of Commando are are immutable, via immutable.js.

Commando

The Commando class is in charge of creating commands, sub commands, adding options, parsing arguments, etc.

#Commando() constructor

The Commando constructor can be used in a few different ways:

new Commando(): Commando

Creates and returns a new command with default (empty) values. This can be used as a base for all commands.

new Commando(string: name): Commando

Creates and returns a new command with a name as its name.

new Commando(object: config): Commando

Creates and returns a new command with a set of options.

#name(value: string): Commando

#version(value: string): Commando

#description(value: string): Commando

Setters for the name, version, and description properties of a command. Returns a command based on the original, with the respective property set to value.

#option(optString: string, description: string, defaultValue: any): Commando

Returns a command with a new option based on the given optString, description, and defaultValue.

#command(command: Commando): Commando

Returns a command with a new subcommand attached to it.

#action(action: (Commando, Commando): Boolean): Commando

Returns a command with it's action property set to action. This is the function that will be called when this command or subcommand is invoked.

The action can return a value of Commando.RETURN_VALUE_SUCCESS or Commando.RETURN_VALUE_FAILURE to indicate the exit state.

Contributing

I would love to hear from anyone using this library, and if there's anything that you thing may improve it, please add an issue in github!

I'd also welcome any pull requests, although I'd suggest that you create an issue first to start the discussion.

The main points of improvement at the moment are: