AntoArts

There are few articles on the design of command-line interfaces (CLIs), even if plenty of articles on designing graphical user interfaces (GUIs) exist. This article is an attempt at presenting some of the most important guidelines for CLI design.

The article assumes the command-line utilities are to be used on a *nix system (e.g. GNU/Linux, BSD, Mac OS X, Unix), and it will frequently reference to common tools on such systems.

Types of command-line interfaces

There are three major sorts of command-line interfaces:

• Non-interactive
• Interactive, line-based
• Text-based user interface

Non-interactive programs don’t need any user interaction after invocation. Examples include ls, mv and cp.

Interactive, line-based programs are programs that often need interaction from the user during execution. They can write text to standard output, and may request input from the user via standard input. Examples include ed and metasploit.

Text-based user interfaces are a cross between a GUI and a CLI. They are graphical user interfaces running inside a terminal emulator. Examples include nethack and vi. Many (but not all) text-based user interfaces on *nix use either curses or the newer ncurses.

Non-interactive programs get the most attention in this article, while text-based user interfaces are barely covered at all.

Advantages of command-line interfaces

Why use command-line interfaces in the 21st century? Graphical user interfaces were invented decades ago!

Many command-line interfaces provide several advantages over graphical user interfaces, still today. They are mostly popular among power users, programmers and system administrators; partly because many of the advantages apply to their tastes well:

• Ease of automation: Most command-line interfaces can easily be automated using scripts.
• Fast startup times: Most command-line interfaces beat their graphical counterparts several times at startup time
• Easier to use remotely: Maybe it’s just me, but I prefer to remotely control computers via SSH over VNC
• Lower system requirements: The lower system requirements make CLIs useful on embedded systems.
• Higher efficiency: Being able to do a lot by just typing some characters instead of searching in menus increases the efficiency which you are able to do work at
• Keyboard friendly: Grabbing the mouse is a distraction

Disadvantages of command-line interfaces

Having covered the advantages of command-line interfaces, it would be a good idea to also cover the disadvantages of them. The most major disadvantage is that the learning curve is steeper. You will also have to check the manual in many cases, while in a GUI, you can figure out many more things while using the product.

GUIs also have the advantage when it comes to presenting and editing information that is by nature graphical. This includes photo manipulation and watching movies (I have always wanted a program that shows a movie in my terminal by converting it to ASCII art in real-time, that would be sweet).

Try to avoid interactivity

Interactive interfaces are harder to automate than non-interactive user interfaces. The ease of automation is one of the greatest advantages of command-line interfaces, and by making your utility interactive, you give away much of that advantage.

There will be cases when an interactive utility makes more sense than a non-interactive one, but at least don’t make a utility interactive when the advantages are dubious. You shouldn’t create a utility which just asks (interactively) for stuff that could be easily sent to the program as arguments (imagine mv asking you for a source and destination path interactively).

Naming your utility

I would like to stress on the importance of a good name for each command-line utility. This is because a bad name is easy to forget, meaning that users will have to spend more time looking it up.

The name should be short. A long name will be tedious to type, so don’t call you version control program my-awesome-version-control-program. Call it something short, such as avc (Awesome Version Control).

The name should be easy to remember. Don’t call your utility ytzxzy.

Arguments

A lot can be said about the arguments to give to programs. First of all, follow standard practice; single-letter options are prefixed with a hyphen, and multiple of them may follow directly (e.g. -la is the same as -l -a). Multi-letter options start with two hyphens, and each such argument must be separated with spaces. Look at the arguments you give to ls, or cp. Follow the way those work. Examples of commands following non-standard practice include dd, which has been criticized for that, many times.

Continuing on the theme of standard practice, if a similar tool to yours (or a tool in the same category, such as file management) uses some option for some thing, it could be a good idea to copy that behaviour to your program. Look at most *nix file management utilities such as mv, cp and rm. All of these provide a flag called -i, with the same behaviour; asking the user interactively to confirm an action. They also provide a -f flag, to force actions (some of which the computer would think seem stupid, but you know what you are doing while using that option, don’t you?).

Options should be optional. That is part of the meaning of the word, but sometimes it is forgotten. Command-line utilities should be callable with zero, nil and no options at all. Examples include cd, calling it with no arguments returns you to the home directory. Some programs might not make sense to call with no arguments, such as mv, but in many cases, you can find some sensible standard behaviour (remember that it is, however, better to just print an error and exit than to do something stupid the user would never expect to happen (“Oh, you gave rm no options, better remove every file on your disk, just to be sure that the file you wanted to remove gets removed”)).

In the *nix world, there’s a practice that anything after double-hyphens -- should be read as a filename, even if the name contains hyphens (e.g. cmd -- -FILE-). If the arguments list ends with a single-hyphen, input should be read from standard input.

Be careful using many flags whose only difference is the case (e.g. -R and -r), as it will be hard to remember.

Always provide a long form of short arguments. Don’t provide just -i, provide --interactive as well.

Provide --version and --help

There are two options you should always include in your program: --version and --help. The first one should print version information for the program. The second should tell one what the program is for, how to use it and present common, if not all, options.

Reading the input

Make sure your program can read input from pipes, and through file redirection.

If the name of a file is passed as an argument, read the file and use its contents as input. If no such argument was passed, read from standard input until a CTRL+D key sequence is sent.

Silence trumps noise

If a program has nothing of importance to say, then be quiet (the same applies to human beings). When I run mv, I don’t want it to tell me that it moved a file to some other location. After all, isn’t that what I asked it to do? It should come to me as no surprise that that happened, so I don’t need to be told that explicitly. When things you don’t expect to happen do happen, then should you break the silence. Examples include, the file I wanted to move didn’t exist, or I didn’t have permissions to write to the directory I tried to move the file to.

Note that your program don’t need to tell its version or copyright information during each invocation, or print the names of the authors, either. That’s just extra noise, wasting space, bandwidth during remote sessions and possibly making the output harder to automatically process, for instance by sending it to another program through a pipe.

Don’t tell me what the output is, either. One should know what the program they use do. whoami prints the name of the current user, and only the name. If it printed The name of the current user is: x instead of just x, much more work would be involved in extracting just the name.

Most programs provide -v (verbose) options making the program more verbose, and a -q (quiet) option, making the program shut up all together (except possibly for some fatal error). The default behaviour should not be completely silent in every case, but in most cases. Programs that print something should only print what is relevant.

How to ask users for a yes or a no

At times, your programs might need to ask a user for a yes or a no, for different reasons, the most common being confirmations (“do you really want to do this?”). Others could be problems that the computer may offer to fix (“Table USERS doesn’t exist, do you want me to create it for you?”).

While asking for questions requiring either a yes or a no (or a y of an n), you should put (y/n) after the question:

Do you really want to do this (y/n)?

Most programs require you to manually hit return after typing the letter. While this might seem superfluous, most programs do this, and your program should require user to do this as well in order to be consistent and not surprise anyone.

Tell me what kind of input you want, and how you want it

If your program asks for a date, and it doesn’t tell me how I should type that date, I will be confused:

Enter a date:

Tell me the format in which I should input the date, and the confusion is gone:

Enter a date (YYYY-MM-DD):

Likewise, if the program just asks for a length, I would be confused. In kilometers, meters, miles, feet…? When different units for things exist, tell me the unit.

Every program should do one, and only one thing, and do it well

The above heading is one of the most important parts of the Unix philosophy, and it has survived the test of time, being just as solid advice as it was back in the late 1960′s/early 1970′s. In practice, this means that you shouldn’t create a file management program, instead, you should create a program for removing files, another for moving them and another for copying them.

Doing one thing well is partly a side-effect of doing only one thing, which allows greater focus.