The Hitchhiker's Guide to CLIs in Python — Part 4: User Experience

04 May 2020 Tweet

Now that we know how to write CLIs in Python, let's talk about the CLI user experience. As mentioned earlier, we're operating in a constrained design space. In contrast to GUIs, which offer a lot of visual cues and guidance to the user.

There are some principles that can help us create a nice user experience for the CLIs we write.

Unix philosophy

The first is to keep things simple and follow the Unix philosophy.

• Write programs that do one thing and do it well.
• Write programs to work together using the redirection operators.
• Write programs to handle text streams, because that is a universal interface.

Following the Unix philosophy makes sure that there are no surprises when users interact with our CLIs.

Fish design philosophy

Fish (short for friendly interactive shell) is a Unix shell which focuses on being interactive and user-friendly.

The Fish design doc details the Fish design philosophy. Fish shell was a huge inspiration in the design of pgcli and mycli. Let's look at some Fish design principles in the CLI context.

The law of responsiveness

A CLI should be quick to respond to user commands. If any command takes a long time to run, the CLI should display a progress bar or a spinner to the user.

The law of user focus

Users come first, implementation later. Implementation should only be considered once an intuitive user interface has been designed.

This starts with the name of the CLI itself. A CLI should have a short and catchy name, like pip / kubectl, instead of a long one that is hard to recall and type, like pip-installs-packages / k8scontrolutility. The CLI should also have consistent naming and a clear philosophy behind use of subcommands vs options and verbs vs nouns. — Command-line usability: A terminal user’s thought process

The law of discoverability

A CLI should make its features discoverable, by being forthcoming about them. This is similar to the visual cues that the GUIs offer. Some things that can make our CLI features more discoverable are:

• Storing a user's command-line history
• Letting them search through it
• Auto-completing user commands using
  • Shell completion
  • Command-line history
  • Features available in the CLI

Amjith Ramanujam talks about these principles in detail in his PyCon 2017 talk — Awesome CLI Tools.

He also talks about prompt-toolkit, a Python package written by Jonathan Slenders, using which we can implement the aforementioned history and auto-completion features and make our CLI fancy! prompt-toolkit is used by ipython and all the dbcli tools.

Continue to Closing Thoughts