The EVRYTHNG CLI (Command Line Interface) allows simple usage of the EVRYTHNG API without needing to set up third-party tools (such as
curl or Postman, for example). It also includes some extra usability features that build on the API to bring additional power to the user.
The CLI is intended to be a testing tools and not used in production systems or integrations.
Like most other CLIs commonly used by software developers, the EVRYTHNG CLI abstracts away some of the intricacies, required knowledge, and easy mistakes to allow rapid interaction, testing, integration, and scripting of API requests.
Node.js 7.6 or above is required.
npm i -g evrythng-cli
Once installed, simply run
evrythng to get set up. After setup is complete, running the same command will show a complete list of all available commands and options, as well as some simple usage examples.
The CLI uses the core concept of Operators to manage initial authentication, thus the CLI will ensure at least one valid Operator is saved before it can be used.
Unless overridden (see
--api-key below), the currently used Operator will be used for all requests. However, in some cases (such as creating an Application User), a different type of API key is required. This will be made clear by the CLI when applicable.
To add a new Operator, use the
operators command and supply a simple name, the region the account is in, and the Operator API Key:
$ evrythng operators add $name $region $apiKey
The currently used Operator can be switched at any time using its name:
$ evrythng operators $name use
Removing an Operator works in the same way:
$ evrythng operators $name remove
Each Operator is associated with a region. By default, the CLI will automatically add the available regions in which the EVRYTHNG API may be used. These are:
us- US region (
eu- EU region (
Since an Operator is intrinsically linked to a region (where the account the Operator manages is located), it must be removed before the region can be changed. This could have occurred in error, for example.
Each of the main areas of the EVRYTHNG API is made available with a specific command, and each command includes various operations that allow the exact same CRUD-style management of resources, as well as some extra functionality in some cases.
To see all the available commands, simply run
evrythng with no options.
To see all the available operations for a given command, specify it with no further options. For example, to discover how to use the action types set of operations:
$ evrythng action-types
Available operations for 'action-types': evrythng action-types create $payload evrythng action-types list evrythng action-types $type update $payload evrythng action-types $type delete
Like other CLIs, switches (also known as flags) can be used to modify the CLI behavior for a single operation. These range from simplifying the output data, specifying API query parameters, and other useful functionality.
To see all the available switches, simply run
evrythng with no options. Currently the following switches are available:
--filter <query>- Specify a Platform filter, such as 'tags=test'.
--with-scopes- Include resource scopes in the response.
--per-page <count>- Specify number of resources per page.
--context- Specify the
--summary- Show a list of resources as a summarised single-line format.
--api-key <API key>- Use a specific API key instead of the current Operator's API Key.
--expand- Expand some ID fields, timestamps to date, etc.
--field <key>- Print only a certain field from the response.
--simple- Print response in non-JSON friendly format.
--build- Interactively build a create request payload using the EVRYTHNG Swagger API description.
--project <project ID>- Specify the 'project' query parameter.
--page <page>- Go to a specific page of results.
--to-csv <output file>- Output array response to a CSV file, such as './data.csv'.
--to-page <page>- Read up to 30 pages before returning results (only with
--from-csv <input file>- Load resources from a CSV file that was previously exported with
--with-redirections <short domain>- When importing/exporting, include each resource's redirection URL.
--from-json <input file>- Load resource from a JSON array file.
--to-json <input file>- Output array response to a JSON file as an array.
As an example, switches can be used to see a simplified list of all resources (such as projects) with a certain tag:
$ evrythng projects list --filter tags=device --per-page 100 --summary
- U5C5dFfYeAh6dYawwFPDAaen 'Test Project' - UpWsPUrwbkNwMDaaaFYtgKkd 'User App Project' - UKf4tyFxrRArEMawRGGpnahn 'Demo Project' - Upf3FNy9bNnH9NRaw5hx9a4s 'Warehouse Management' - U5fYaVMtQSfK2DRwR2Dhab9b 'Data Loading Application'
Similar to switches that are applied on each invocation of the CLI, options are set once, and then applied until they are changed. Examples include
error-detail, which when enabled will show more detailed error information.
To see all the available options, simply run
evrythng with no options. Currently the following options are available:
log-level- Set level of output to the console (one of 'info', 'error').
error-detail- Show full detail of errors encountered.
no-confirm- Skip the 'confirm?' step for deletions.
show-http- Show full details of HTTP requests.
default-per-page- Set a default value for the
You can see the state of all options at any time:
$ evrythng options list
Change an options's state:
$ evrythng options error-detail $state
The EVRYTHNG CLI allows plugins to be created and installed in order to add/extend custom functionality as the user requires. These plugins are provided with an
api parameter that contains methods and data they can use to implement additional functionality, such as adding new commands.
See the Plugins page or the GitHub repository for full information about creating and installing CLI plugins.
You can import and export resources to and from your EVRYTHNG account to a local file in the following formats:
- JSON (JSON object or array file)
- CSV (file format specification)
When importing resources, check the resource's command list to see which are suitable, for example:
$ evrythng thngs
Available operations for 'thngs': evrythng thngs create [$payload|--build|--from-csv|--from-json] ...
Export data from a
list operation using the
--to-csv switch, specifying the path to the destination file.
$ evrythng products list --per-page 100 --to-csv ./products.csv
Import data from a compatible file in a
create operation using the
--from-csv switch and a path to the file containing the data. Note that data exported with the
--to-csv option will be compatible.
$ evrythng products create --from-csv ./products.csv
$ evrythng projects list --summary --per-page 100
Only available for creating basic resources such as projects, products, Thngs, collections, places, etc.
$ evrythng thngs create --build
$ evrythng thngs $THNG_ID read --expand
$ evrythng thngs list --per-page 100 --filter tags=demo > thngs.json
$ evrythng app-users anonymous create --api-key $APPLICATION_API_KEY
$ evrythng batches $BATCH_ID tasks create --build
$ evrythng products $PRODUCT_ID read --with-scopes
$ evrythng access read --api-key $MYSTERY_API_KEY