Cliable

Opinionated helpers for defining command line interfaces in a declarative way. Everything is optional.

NOT USABLE YET

Summary

There's nothing particularly difficult about writing CLI applications but it can be hard to write them in a modular and testable way. The mental model for Cliable applications is a 3 stage pipeline:

1. Input flows in, e.g.:

   • CLI arguments and options
   • environment variables
   • config file values
   • fetched data from a remote service
   • content read in from the filesystem

2. Input is processed by one or more composed pure functions

3. One or more side effect happens, e.g.:

   • a file is written or uploaded
   • a kitten is rescued

And building your application this way you can avoid boilerplate and delegate the heavy lifting to Cliable (which delegates most things to yargs).

Install

NOTE: requires Node 4.0+

npm install --save cliable

API

This is the entire API. Pass your spec to this function and it will wire everything together for you.

buildCommandLineInterface(AppSpec)

Types

AppSpec

command type: CommandSpec, optional

A command declaration. Useful for simple, single action, applications. The command is run if all required options are present. If commands is configured command is ignored. The value is a CommandSpec.

commands type: object, optional

An array of command declarations. Useful for more complicated that must be invoked with a command name, e.g. fire-starter strike. Each key defines a command by name and the corresponding value is a CommandSpec.

TODO defaultConfigPath type: string, optional

A path, relative the the users's home directory, where the user's config file can be found. Config can be JS, YAML, or JSON.

TODO configKey type: string, optional

Allows an end user to override the default config file path. Defaults to 'config'. Passed through to yargs#config.

TODO enableEnvVars type: boolean, optional

A boolean value to enable/disable inclusion of environment variables in app state. Uses yargs#env.

TODO envVarsPrefix type: string, optional

An app specific environment variable prefix that will be used to match environment variables for inclusion in app state. Uses yargs#env.

TODO sideEffectProcessors type: object, optional

An object where the keys are side effect names and values are functions that know how to process the side effect named by the key. See SideEffectSpec.

CommandSpec

Passed through to yargs#command unless otherwise noted

description type: string, optional

A description of the command used when showing help text

options type: object, optional

An object describing any option that the user can enter via CLI arguments (e.g. --foo bar) and/or config file and/or environment variables.

handler type: array[function], required

A list of functions should be run by the command. The functions are expected to return a list of lightweight side effect objects that are processed by one the sideEffectProcessors. See SideEffectSpec.

arguments type: Array[object], optional

A list of command arguments. This can be used if your command can accept sub arguments (e.g. foo.txt in foo-app foo-command foo.txt --bar 42). Each item is an ArgumentSpec.

TODO dependencyResolvers type: object, optional

An object where the keys are resolve names and values are functions that know how to obtain the required data.

TODO ArgumentSpec

name type: string, required

The name of the argument, appears in usage and help messages.

required type: boolean, optional

Indicate if the argument is required to run the underlying command.

TODO SideEffectSpec

type type: string, required

The type of sideEffectProcessors that is needed to process process the side effect.

payload type: object, optional

Any data needed to describe the side effect.