Plugins

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:

• evrythng-cli-plugin-greeter - the simple example shown above, demonstrating adding a new command.

• evrythng-cli-plugin-upc-lookup - a more complex example that adds a new command that can be used to look up a product UPC code and then create an EVRYTHNG product from that data.

• evrythng-cli-plugin-smartlabel - adds a smartlabel command that allows creation of products compatible with smartlabel.evrythng.io.

• evrythng-cli-plugin-reactor-test - allows faster iterative testing and development of a Reactor script locally before being uploaded to the Platform.

• evrythng-cli-plugin-query - integrates evrythng CLI with thng-query domain specific language to perform queries to EVRYTHNG API.

• evrythng-cli-plugin-account-config - Easy importing, exporting, and comparing of many resource types between accounts.

• evrythng-cli-plugin-csv-loader - Allows validation, mapping, and creating/updating resources from a CSV file.