Toolsmith

Yet another CLI tool framework.

Installation

npm install toolsmith

Basic Example

#!/usr/bin/env node
require('toolsmith')
  .option('foo')
  .parameter('bar')
  .handler(run)
  .parse()

function run (ctx) {
  if (ctx.opts.foo) {
    ctx.log('foo is enabled')
  }
  ctx.log('bar says ' + ctx.args.bar)
}

$ ./example.js --foo hello
foo is enabled
bar says hello

$ ./example.js --help
Usage: example.js [OPTIONS...] <bar>
Parameters:
  bar
Options:
  -h,--help  You are here.
  -f,--foo

Advanced Example

#!/usr/bin/env node
const toolsmith = require('toolsmith')

toolsmith
  .option({
    long: 'foo',
    short: 'f',
    value: 'FOO',
    inherit: true,
    desc: 'Specify a custom foo.'
  })
  .subcommand(toolsmith.Command('bar')
    .option({
      long: 'boo',
      short: 'b',
      desc: 'Enable boo.'
    })
    .parameter({
      name: 'STUFF',
      desc: 'Stuff to process.',
    })
    .parameter({
      name: 'THINGS',
      optional: true,
      variadic: true,
      desc: 'An assortment of things.'
    })
    .handler(runBar))
  .handler(run)
  .parse()

API

Command

command([name])

Returns a new command object, with an optional name. If name is not provided, the command will assume the name of the running process.

.handler(fn)

Specify a handler function that will be called when a the associated command is executed. The handler function will receive a single argument, a context object representing the current invocation of the command:

command()
  .handler((ctx) => {
    console.log('%s has been executed!', ctx.name)
  })

Note: Any command object that does not contain sub-commands must have a handler associated with it. A command may have both sub-commands and a handler, in which case the handler will only be called if the command is executed without any arguments.

.option(opts)

.option(long, [short], [value], [desc])

Specify a option or flag that the command will accept. Options must have a long form (e.g. --arg), may also have a short form (e.g. -a), and may or may not accept a value (e.g. --arg=VAL or -aVAL).

Valid opts keys include:

• desc: Optional string describing the purpose of the option. This string will be displayed in help output.
• inherit: Optional boolean value indicating whether or not this option should be inherited by sub-commands.
• key: Optional string that will be used as the key for storing any collected results. If omitted, the long form will be used instead.
• long: Mandatory long form of the argument; must be a string at least two characters long.
• repeatable: Optional boolean value indicating whether or not this option can occur multiple times.
• short: Optional short form of the argument; must be a string exactly one character long.
• value: Optional boolean value indicating whether or not this option receives a value.

The manner in which options are recorded depends on how they are configured:

• If an option is neither repeatable nor accepts a value, it will be recorded as true.
• If an option is repeatable, it will be recorded as an integer count of the number of times it occured.
• If an option accepts a value, it will be recorded as the collected value.
• If an option is both repeatable and accepts a value, an array of collected values will be recorded.
• In all cases, no value is recorded for an option that occurs zero times.

If a string is provided is provided as the value key, it will be used to describe the value in help output:

command()
  .option('foo', 'f', 'FOO', 'Specify custom foo.')

$ ./example.js --help
Usage: example.js [OPTIONS...] <bar>
Options:
  -h,--help     You are here.
  -f,--foo=FOO  Specify custom foo.

.summary(desc)

Add a string describing the function of a command. This string will be displayed in help output, either as the primary command summary or as part of a sub-command listing:

command()
  .summary('Does the primary thing, with gusto!')
  .subcommand(command('also')
    .summary('Does secondary thing, with comparable enthusiasm!')
  .parse()

$ ./example.js --help
Usage: example.js [OPTIONS...]
Summary:
  Does the primary thing, with gusto!
Commands:
  also  Does secondary thing, with comparable enthusiasm!
Options:
  -h,--help  You are here.

$ .example.js also --help
Usage: example.js also [OPTIONS...]
Summary:
  Does secondary thing, with comparable enthusiasm!
Options:
  -h,--help  You are here.