ActivateAuthenticateAmplify
Documentation
DashboardSupportDeveloper Blog

EVRYTHNG CLI

Suggest Edits

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.

📘

Note

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.

Installation

The EVRYTHNG CLI can be installed directly from npm or you can view and run the source code.

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.

Operators

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

Regions

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 (https://api.evrythng.com)
  • eu - EU region (https://api-eu.evrythng.com)

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.

Commands

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

Switches

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 context query parameter.
  • --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 --to-csv).
  • --from-csv <input file> - Load resources from a CSV file that was previously exported with --to-csv.
  • --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'

Options

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 perPage query parameter.

You can see the state of all options at any time:

$ evrythng options list

Change an options's state:

$ evrythng options error-detail $state

Plugins

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.

Data Import/Export

You can import and export resources to and from your EVRYTHNG account to a local file in the following formats:

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 to file

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 file

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

## Useful Examples

See all projects and their IDs

$ evrythng projects list --summary --per-page 100

Create a resource interactively

Only available for creating basic resources such as projects, products, Thngs, collections, places, etc.

$ evrythng thngs create --build

See more detailed information on a resource (timestamps, IDs, etc)

$ evrythng thngs $THNG_ID read --expand

Save a result to a file

$ evrythng thngs list --per-page 100 --filter tags=demo > thngs.json

Quickly create an anonymous Application User

$ evrythng app-users anonymous create --api-key $APPLICATION_API_KEY

Create a batch task interactively

$ evrythng batches $BATCH_ID tasks create --build

See a resource's scopes

$ evrythng products $PRODUCT_ID read --with-scopes

Identify an API key type

$ evrythng access read --api-key $MYSTERY_API_KEY

Updated about 5 years ago