Commands

Description

Commands define the arguments passed to a Shell.js scripts.

Properties

• name (string)
  The command name.
• description (string)
  The command description.
• options (object|array)
  Defined the expected command options, sometimes called flags. Support object and array notation. If defined as an object, keys correspond to the "name" properties. If defined as an array, the "name" property is required.
• main (object|string)
  What is left once the option and the commands have been extracted.
• commands (object|array)
  Support unlimited multi-level commands.
• handler (function|string)
  Execute a function or the function exported by a module if defined as a string, provide the params object, see the routing documentation.

Multi-level commands

The package can handle simple argument definitions as well as complex command based definitions including one or multiple nested commands. Thus, large applications can group all its functionalities into one parent CLI entry point.

Examples of configuration

Basic application

Let's start with a basic application call myapp which deploys and manages a web application. Using the "conf" option, our application require a configuration file which every command will use.

Here's the initial definition:

{
  "name": "myapp",
  "description": "My Web Application",
  "options": [{
    "name": "conf",
    "required": true
  }]
}

Multiple commands

It will accept three commands "info" and "server". Help is automatically available so there is no need to define it. The server command will need a pid file which could be defined in the global configuration or through a "pid" option. At the same level than "name" and "options", we'll enrich the definition with a new "commands" entry:

{
  "commands": [{
    "name": "info"
  },{
    "name": "server",
    "options": {
      "name": "pid"
    }
  }]
}

Usage of the "server" command is now: myapp [options] server [server options].

Multi-level commands

We now want to define commands to control our server such as "start" and "stop". The "start" command will require an option "port". Inside the object defining the "server" command, we add a new "commands" entry:

{
  "commands": [{
    "name": "info"
  },{
    "name": "server",
    "options": {
      "name": "pid"
    },
    "commands": [{
      "name": "start",
      "options": {
        "name": "port",
        "required": true
      }
    },{
      "name": "stop"
    }]
  }]
}

Usage of the "start" command is now: myapp [options] server [server options] start [start options].

With routing

The final definition, enriched with "handler" definition to route the command to our own modules, looks like:

{
  "name": "myapp",
  "description": "My Web Application",
  "options": [{
    "name": "config",
    "required": true
  }],
  "commands": [{
    "name": "info",
    "handler": "./lib/config"
  },{
    "name": "server",
    "options": {
      "name": "pid"
    },
    "commands": [{
      "name": "start",
      "handler": "./lib/server/start"
      "options": {
        "name": "port",
        "required": true
      }
    }, {
      "name": "stop",
      "handler": "./lib/server/stop"
    }]
  }]
}