disruptive-cli

Unofficial CLI for the Disruptive Technologies (DT) API.

At the time of writing, I'm employed at DT as an Application Engineer, which entails all sorts of internal projects, experiments, and customer-centric development. I've gotten quite familiar with our public APIs, including DT Studio, our customer front-end, both key in handling quantities of device and sensor data.

I think they're both well-designed tools that get the job done, but I've found there to be a gap in the toolchain for tasks that are too small to write a Python or Bash API script, but too complex for a GUI front-end to handle. This is, however, where CLIs fit in perfectly.

I created disruptive-cli to fill this gap. It is essential a wrapper on top of the DT Python API, but with the extra convenience of a CLI with functionalities like chaining commands through piping and formatting the output to common filetypes.

Though I'm a frequent user of CLIs both through work and outside, I had never created one. To avoid my own ingrained biases, the design is heavily inspired by the excellent CLI Guidelines, a must-read for anyone looking into designing their own CLI.

Usage

Call the dt command using a dt <NOUN> <VERB> syntax. 


      dt project list

See dt -h or the Github page for more usage details.

Formats

A human-readable tabular output is prioritized, while CSV, TSV, and JSON is also supported.

Tabular Output

It was an interesting challenge to implement the table structure. It should be easy to read while also being natively supported by tools like awk. One should also be able to chain commands using pipes, which means support for including/excluding columns.

The result was a simple but functional table where column values decide their width dynamically. Headers are case-insensitive and be hidden using --no-header, and columns isolated with the --include flag. 


      PROJECT-ID             DISPLAY-NAME                     SENSOR-COUNT   CLOUD-CONNECTOR-COUNT
      c10humqoss90036gu530   jhg-playground Inventory         14             0
      c14u9p094l47cdv1o3pg   main                             11             1
      br1rrd35443g009mhk60   Default                          0              0
      c34c05mh9dh7pohjtorg   Sensors I don't know where are   4              1
      c9akpca7090rjibacslg   B                                9              0
      c35emu6h9dh7pohjtp4g   Oslo Office                      82             1

Common Formats

Depending on usage, writing the output to a common file format can save a lot of time, and disruptive-cli supports all of the following formats using their namesake flags.

It is supported to pipe the output of --json into jq.

Chaining Commands

Piping is one of the most powerful features of a CLI, and I'm pretty happy with how I've implemented the behavior. After some back and forth I decided to use the - symbol for pipe input, where the values come from isolated column values in the preceding.

In the following example all project IDs are piped into a command which lists all devices in a single project, resulting in a list of all devices in all projects. 


      dt project list --include project-id | dt device list - --device-type temperature

Notice the - symbol which replaces each project ID in dt device list.

Interactive Mode

Quite a few endpoints on the DT API have a lot of optional arguments, and an interactive mode lets me take it one step at a time. Piping is currently not supported whilst using interactive mode.

For example, in normal operation, an emulated device can be created as shown below. 


      dt emulator create <PROJECT_ID> <DEVICE_TYPE> <DISPLAY_NAME> <LABELS>

Sometimes it might be more manageable using the interactive mode, the you focus on one line at a time. 


      dt emulator create -i
      required > project_id: <PROJECT_ID>
      required > device_type: <DEVICE_TYPE>
      optional > display_name: <DISPLAY_NAME>
      optional > labels: <LABELS>

You could, of course, just check the possible arguments using -h flag instead.