The EVRYTHNG CLI allows anyone to create plugin modules that can add new functionality specific to the requirements of the users. Example can include data queries, adding new commands, running sequences of commands, or integrations with other external APIs and systems.


Requirements

In order to be considered a plugin, its npm module must meet the following:

  • Be installed in the same directory as the CLI, as will be the case when installed globally with -g or as a project dependency (i.e: in node_modules).
  • Have a package name beginning with the prefix evrythng-cli-plugin-.
  • Have a single source file identifiable when it is required, such as setting main in its package.json. That file must export a single function, which is provided the api parameter (see below).

Plugin API

The api parameter provided to a plugin's exported function contains the following usable methods and data:

  • registerCommand() - Register a new command.
  • getOptions() - Retrieve an object describing the user's options from the CLI configuration file, which defines the persistent options preferences.
  • getSwitches() - Retrieve an object describing the currently active switches.
  • runCommand() - Run a CLI command using a list of string arguments, such as ['thngs', 'list'].
  • getConfig() - As of 1.4.0, get a get()/set() interface to the CLI configuration file.

## Simple Example

An example of such a plugin is shown below. The basic directory structure is:

- evrythng-cli-plugin-greeter
    - package.json (with main: index.js)
    - index.js

index.js exports a single function that will be run when it is loaded:

module.exports = (api) => {
  const newCommand = {
    about: 'Greet someone',
    firstArg: 'greet',
    operations: {
      greetSomeoneByName: {
        execute: ([name]) => console.log(`Hello there, ${name}!`),
        pattern: '$name',
      },
    },
  };

  // Register a new command
  api.registerCommand(newCommand);
};
{
  "name": "evrythng-cli-plugin-greeter",
  "version": "1.0.0",
  "description": "Greet someone by name.",
  "main": "index.js",
  "author": "EVRYTHNG"
}

In the example above, a new command greet is added with one operation that is provided the remaining arguments, in the same way as regular built-in commands. This is validated against a schema before being loaded - so it must match the structure of the above example.

This example adds a new operation under the greet command: greet $name. This is then available as usual when using the CLI:

$ evrythng greet Charles
Hello there, Charles!

Published Plugins

The following CLI plugins have been published by EVRYTHNG, and can serve as reference examples: