CLI Design - Julio Merino (jmmv.dev)

CLI design: Series wrap-up

The time to conclude the CLI design series has come. I hope you have enjoyed the topic and that got some useful tips and tricks for your future developments! Here is the summary of all the topics that were covered: Series introduction The CLI is the presentation layer Error reporting Requesting and offering help Putting flags to good use Do not reinvent option parsing Subcommand-based interfaces Single-command interfaces Handling output messages Screen wrapping Consider interactive prompts twice Stay tuned for the next series!

September 19, 2013 · Tags: <a href="/tags/cli-design">cli-design</a>
Continue reading (about 1 minute)

CLI design: Consider interactive prompts twice

While it is a rare thing to find, CLI-based applications can be interactive just like any other kind of application can. If you choose to interactively query the user for details in your program or script, you should be aware of the two scenarios that can result from this choice (which, interestingly, are the same scenarios that we already saw regarding output verbosity). The first scenario is about “fast” applications: if the program is expected to complete in a short amount of time—where short is defined as an amount of time in which the user will not context-switch—it is alright to pop up interactive prompts at any point during the execution of the application. The user will be there watching the command prompt, and he will be ready to answer such questions. Nothing wrong here.

September 16, 2013 · Tags: <a href="/tags/cli-design">cli-design</a>
Continue reading (about 4 minutes)

CLI design: Screen wrapping

In a world of terminal emulators within graphical environments, there is no longer a “standard” window size. 80x24 is still the default, sure, but it’s trivial for users to resize the terminal. Why does this matter? Consider the most obvious case: the help message of your program. It is incredibly common to see carefully-formatted embedded strings into the program’s code designed to fit within a 80x24 window (which is especially true for the width of the text). Other than being a nightmare to maintain such a piece of code, what happens when the user resizes the terminal? If he increases the number of columns, the output of the application won’t make use of such extra space and will continue to use the same number of lines — a situation that may be undesirable in a widescreen setting. If he decreases the number of columns, the output of the application will get wrapped at weird boundaries.

September 12, 2013 · Tags: <a href="/tags/cli-design">cli-design</a>
Continue reading (about 4 minutes)

CLI design: Handling output messages

Your CLI-based program has to communicate with the user. The most obvious case is to display error or warning messages, but in some cases it is also to report progress status. There are a few details to be considered in this area. Quietness vs. verbosity by default You’ve probably heard the “No news is good news” principle. This is a major guideline behind the design of most standard Unix tools: when no problems arise, the tool just does what it was asked for and does not print anything on the screen. Only when something goes wrong an error or warning message is printed. Examples include cp, mv, git add, etc.

September 9, 2013 · Tags: <a href="/tags/cli-design">cli-design</a>
Continue reading (about 4 minutes)

CLI design: Single-command interfaces

In the previous post, I provided common guidelines on how to implement a subcommand-based interface. It is now the time to look into the interface of those applications that implement a single command or function, which are actually quite abundant. Without going too far, you will encounter cp, ls and sudo, all of which are just a tiny sample of tools that fit this model. General syntax The general syntax of a single-command interface is simple:

September 5, 2013 · Tags: <a href="/tags/cli-design">cli-design</a>
Continue reading (about 4 minutes)

CLI design: Subcommand-based interfaces

Subcommand-based interfaces are common: the majority of the CLI tools that provide more than one operation within them expose their features in this manner. Examples of such interfaces include svn, git, ifconfig, yum, apt-get and many, many more. Designing the interface of these applications is quite straightforward once you have the concepts clear, but there are quite a few common pitfalls that you need to be aware of to prevent falling into them. In this post, I will guide you through what the general design of such interfaces is and I will cover a bunch of the common problems. Let’s get started.

September 2, 2013 · Tags: <a href="/tags/cli-design">cli-design</a>
Continue reading (about 5 minutes)

CLI design: Do not reinvent option parsing

In the previous post, we saw what good and bad use cases for flags in the interface of a command-line application are. We talked about the theory, so it is now the time to talk about the implementation details. The point I want to make in this post is simple: do not reinvent option parsing. Use the libraries provided by the platform you are targeting to implement the interface of your application: even if there is some little detail of the library that you don’t agree with, consistency with the platform is lightyears better than a custom implementation that fails to handle some corner cases and/or behaves in an unexpected manner.

August 29, 2013 · Tags: <a href="/tags/cli-design">cli-design</a>
Continue reading (about 3 minutes)

CLI design: Putting flags to good use

As the Wikipedia puts it in its Command-line interface page: A command-line option or simply option (also known as a flag or switch) modifies the operation of a command; the effect is determined by the command’s program. Yet, many developers abuse flags to do many unrelated things and therefore end up providing a non-standard and confusing user interface. Let’s take a look at some specific use cases, both bad and good.

August 26, 2013 · Tags: <a href="/tags/cli-design">cli-design</a>
Continue reading (about 5 minutes)

CLI design: Requesting and offering help

Any CLI application must offer help to describe its command line syntax: the flags it supports, the subcommands it implements, the meaning of the positional arguments, etc. Failure to do results in an application that is completely unusable: unlike GUI applications, the interface of CLI tools is not discoverable without instructions. It is, therefore, important to realize that help does not only exist to aid the user in recovering from errors. Help also exists to teach users how the application works, what the expectations are and, more importantly, to showcase the features of the program.

August 22, 2013 · Tags: <a href="/tags/cli-design">cli-design</a>
Continue reading (about 5 minutes)

CLI design: Error reporting

Error reporting is a tricky business. Get it right and your users will be able to correct their actions quickly. Get it wrong and you will be the cause of your user’s frustration — because, face it: A) users will make mistakes and B) your application will encounter erroneous conditions due to bugs or unpredicted scenarios. Understand usage errors and application errors From the programmer’s point of view, there are many types of errors that an application can detect; but, from the point of view of the user, errors can be classified in two broad categories: usage errors and application errors. Let’s take a look at what these are before diving into how to handle them.

August 19, 2013 · Tags: <a href="/tags/cli-design">cli-design</a>
Continue reading (about 5 minutes)

CLI design: The CLI is the presentation layer

Treat the code that implements a CLI utility to the highest standards. Let’s step back for a moment. In any graphical application, there always is a chunk of code to deal with the interface of the tool and there is another chunk of code to do the “real work” behind the interface, possibly split into multiple logical layers. This basic split of presentation vs. logic is essential for the maintainability of the code. The same is equally true for CLI tools: the code that interacts with the console is the presentation layer, and anything else is part of the backend.

August 15, 2013 · Tags: <a href="/tags/cli-design">cli-design</a>
Continue reading (about 3 minutes)

CLI design: Series introduction

Ready for a new series? Having just gone over a bunch of items regarding code readability, it is time to shift gears and get into the topic of the design of Command Line Interfaces (or CLIs for short). The main focus of this series will be to cover best practices involved in creating applications whose interface is command-line oriented. Among other things, I will detail how the CLI should accept optional and required arguments, how a tool should expose more than one action and how interactive help should be handled.

August 12, 2013 · Tags: <a href="/tags/cli-design">cli-design</a>
Continue reading (about 2 minutes)