ActivateAuthenticateAmplify
Developer Blog
DashboardSupportDeveloper Blog
Back to All

Introducing the EVRYTHNG CLI

over 6 years ago by Chris Lewis

We have just released the first version of the EVRYTHNG CLI (Command Line Interface)! Similar to other products and systems you may already use (including Git, AWS, npm, etc.), the CLI is a tool that provides a structured, simplified interface to the API for developers to use when prototyping, querying, testing, and integrating with the EVRYTHNG Platform.

Why Use a CLI?

The ultimate aim is to remove some of the complexity and knowledge requirements when performing simple interactions with the API. As a simple example, looking for a Thng by ID that has a certain tag to discover which project it is in with curl looks something like this:

curl -H ‘Content-Type: application/json’ \
  -H ‘Authorization: oirm2diNKKhua8gHk8HVEeS8xBb9w5…’ \
  -X GET ‘https://api.evrythng.com/thngs/UHQs4DYPegPRQKwaw2AgCk7b?withScopes=true’

Quite a lot to type by hand, or recall from memory!

Similarly, using a visual request tool such as Postman would involve a similar number of controls to be configured, options to be looked up, etc.:

894

However, using the EVRYTHNG CLI, whose command syntax is structured similar to the evrythng.js SDK, the query is simpler and more memorable, thanks to the opportunity to remove complexity and required knowledge:

evrythng thngs UHQs4DYPegPRQKwaw2AgCk7b read --with-scopes

Much simpler!

Getting Started

You can easily get started using the CLI by installing it globally with npm:

npm i -g evrythng-cli

Then, simply type evrythng to be guided through setting up the initial Operator:

725

Once you have your first Operator set up, you can view all the available commands and options by simply typing evrythng. This also includes some interesting example commands for you you try out.

For more information on the available commands and options, and more usage tips, read the EVRYTHNG CLI documentation page.

Other Features

The layer the CLI forms between the API and the developer using it allows many more such opportunities for aiding the user and providing additional functionality. These features include:

  • Consistent commands for virtually the entire API, compatible with the same JSON payload.
  • Management of multiple accounts by storing the Operator API Key, allowing fast switching between accounts.
  • Query parameters surfaced as program switches, and filters are automatically encoded.
  • Interactive payload builders for most simple resources using the EVRYTHNG Swagger API description file.
  • Interactive payload builder for the more complex Tasks API.
  • Self-documenting commands with suggestions for incomplete commands, as well as documentation for all switches and options that are also available.
  • A confirmation step before performing delete operations.

More Advanced Usage

In addition to creating, reading, listing, updating, and deleting EVRYTHNG Platform resources, the CLI allows you to do some other interesting things in a more streamlined manner. Here are some examples:

Quickly find a resource in a list

The --summary switch transforms the usual JSON array output into a simplified view showing just the id and name of each item. This is useful for quickly finding the ID of a known item:

evrythng projects list --summary

- UpAKkdA5MG8Yh6awaGxRxCrm 'Test Project'
- UKWET3pP7wArhqRRaGPKKNhm 'evrythng-cli Demo Project'
- UHXpSctBBgsRQpRaaEcqYrUn 'Warehouse Applications'
- UHEkTgnrBXPw9KaaREkRxHtq 'Reactor Extensions'
- UKyMsPn9eqPN9NwwwnUggcbp 'Weather Station Project'

Interactively create a resource

Most simple resources (projects, Thngs, products, collections, files, places, etc.) can be built without knowledge of the JSON payload using the --build switch. This draws on the definition of that resource type from the evrythng/swagger API description to ask the user questions about the data they want to specify for each property of the resource.

For example, creating a Thng:

evrythng thngs create --build

The resulting payload will be displayed, and the CLI will automatically complete the process by sending the creation request.

823

Quickly create an anonymous Application User

Anonymous Application Users are useful for web applications and representing users of an integration where their personal details cannot or are not known. This special request is simplified using the CLI, and the --api-key switch to override the currently selected Operator with the required Application API Key:

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

{
  "evrythngUser": "UpYc9xa8et9xxxaRwkcayr9g",
  "status": "anonymous",
  "email": "anon-46c15a80-9fd4-11e8-ba8d-14526343.app-ungycjdjskdfsdhkhshjdkhc6rq2d@anon.evrythng.com",
  "evrythngApiKey": "DLs8jFb9AonCvhWw4gpXi6hkIgV14n...",
  "socialNetwork": "evrythng"
}

Scripting with the CLI

Since each request performed with the CLI is a discrete operation, it can be used as part of a larger script to automate the creation of a particular account or project setup. This is achieved using the --field switch to return only a certain field from a JSON object response.

A simple example script is shown below that sets up a Thng relating to a product, all scoped to a new project, shows an expanded view of the Thng, then cleans up after itself:

#!/bin/bash

# Create a project
PAYLOAD='{"name": "Test Project"}'
PROJECT_ID=$(evrythng projects create "$PAYLOAD" --field id)
echo "Created project $PROJECT_ID"

# Create a product scoped to that 
PAYLOAD='{"name": "Example Product"}'
PRODUCT_ID=$(evrythng products create "$PAYLOAD" --project "$PROJECT_ID" --field id)
echo "Created product $PRODUCT_ID"

# Create a Thng referencing the product scoped to the project
PAYLOAD="{\"name\": \"Example Thng\", \"product\": \"$PRODUCT_ID\"}"
THNG_ID=$(evrythng thngs create "$PAYLOAD" --project "$PROJECT_ID" --field id)
echo "Created Thng $THNG_ID"

# Read back the whole Thng with expanded references and scopes to verify project scope
RESULT=$(evrythng thngs "$THNG_ID" read --expand --with-scopes)
echo -e "\nThe expanded Thng:\n\n$RESULT\n"

# Clean up, skipping confirmation steps
evrythng options no-confirm true
evrythng thngs "$THNG_ID" delete
evrythng products "$PRODUCT_ID" delete
evrythng projects "$PROJECT_ID" delete
evrythng options no-confirm false

echo 'Cleaned up'

Summing Up

Our hope is that this new tool will help developers accomplish a wide range of routine and automated tasks in less time, and with more accuracy. We have exciting plans for more usability and integration features in future versions, so stay tuned!

In the meantime, please let us know if you encounter any problems or bugs.