Quickly Building a Command Line Interface for your Web Service

Make your service more accessible and force good design principles.

A Command Line Interface (CLI) is the antithesis of a modern Web interface. The Hue Query Assistant already provides a visual way to Query Data and manipulate files, and is getting simpler and smarter as the releases goes.

So why providing a CLI?

In short, we found a CLI was:

Helpful for simplifying certain usage operations, has a very quick ROI and re-enforce clean designs and opens up more creativity.

Philosophy

The CLI targets more advanced users and provides direct access to the Query Service from their desktop or favorite machine as long as it can talk to it via HTTP.

Still the same interaction as via a Web browser but via a Bash terminal

The first goal is to augment the current API for its most important operations:

• Execute an SQL statement or saved query
• List, download, upload files

It was decided to focus on the new secure Storage API (handy to manipulate files from a shell) and not blindly support all the possible operations (skip the clutter) of the recent public REST API powering the SQL Scratchpad and the File Browsers.

The CLI leverages a lot of existing pieces and it only took 2 days to design/implement a first version with one operation. It is also straightforward for the Open Source Community and Hue Contributors to add extra operation by following the existing commands.

Last but not least, there was a lot of learning and inspiration cascading down from this first version. It particular on how to design and use Typer instead of the traditional argparse:

Alternatives, Inspiration and Comparisons

Typer provides exemplary documentation, is designed for simplicity, built on top of Click, leverages Python 3 types.

But now let’s give this CLI a quick try!

The CLI project is part of the Compose repository and automatically bundled into the Gethue package.

Let’s install the latest version:

pip install gethue

See the current commands:

> compose --help
Usage: compose [OPTIONS] COMMAND [ARGS]...
Query your Data Easily
Options:
--install-completion  Install completion for the current shell.
--show-completion     Show completion for the current shell, to copy it or customize the installation.
--help                Show this message and exit.
Commands:
auth     Configure the CLI
query    Execute queries, list databases, tables
storage  Manipulate data files

And point to the demo service API:

> compose auth

Api url [https://demo.gethue.com]:
Username [demo]:
Password [demo]:
Auth: success 200
Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjMxMjE5MDkxLCJqdGkiOiJkNGJkY2Q5M2NjMjg0MDlkYWJlYWZhNGRlNjlkOTMzMyIsInVzZXJfaWQiOjJ9.Gr8bW_JaZ8yzQ3eEZYp3jKbdsSgLAXxqvSRbeU6jhLg

And list the content of a remote directory:

> compose storage list --path s3a://demo-gethue
s3a://demo-gethue/data (https://demo.gethue.com/hue/filebrowser/view=s3a%3A%2F%2Fdemo-gethue%2Fdata)
s3a://demo-gethue/data/web_logs (https://demo.gethue.com/hue/filebrowser/view=s3a%3A%2F%2Fdemo-gethue%2Fdata%2Fweb_log

Et voila!

The new CLI is paving the way for the Hue 5 Query Editor Service.

We also got new ideas along the way, like decoupling even more the Python modules, introducing design patterns from the Typer project, getting familiar with Python 3 typing… which already paid back the time spent on creating the CLI.

We bet that the user community will also come back with new usage feedback! (hint: like scheduling queries ;)