CLI Templates / Antipatterns for Ease of Use

Question

What patterns contribute to or detract from the usability of the CLI?

As an example, consider the CLI for ClearCase. The CLI is very comprehensive (+1), but it has several obvious features. Recently, I wanted files to be lowercase in ClearCase using clearfsimport . Unfortunately, I ended up in the documentation for my clearimport cousin. It may seem easy, but it cost me more hours than I would like to admit. The change in the middle bothered me.

Why provide such almost identical functions with such almost identical names? In my opinion, there are many options.

• clearimport -fs
• fsclearimport
• clear_fs_import
• clearimport_fs

Everything would be better than with them. The code I'm working on IS CLI, and this experience made me look at my own choices. I think I have all the basics (standard help, long form and short forms, short meaningful names, examples, eliminating ambiguity, precise management of spaces inside quotes, etc.).

There is several literature on this subject.

Perhaps a bad CLI is no different than a bad API . CLI is an API type in a sense. Goals are naturally common: flexibility, readability, and completeness. Several factors distinguish the CLI from a typical API. One of them is that the CLI must support scripting capabilities (often participate in a series of pipes). Another is that autocomplete and namespaces do not exist the same way. You do not always have a nice colorful graphical interface for you. CLIs must independently document themselves directly to the client. Finally, the CLI audience is significantly different from the standard API. I appreciate any understanding you may have.

Answer 1

I like the subcommand template that I’m most familiar with since it is implemented in the Subversion client from the command line.

 svn [subcommand] [options] [files] 

Without subcommands, subversion will be waaaaay too many different options for me to remember effectively, and the help system would be a pain to fail.

But if I don’t remember how any particular subcommand works, I can simply enter:

 svn help [subcommand] 

... and he shows me only the relevant parts of the reference documentation.

Answer 2

As noted above, this format:

  [master verb] [subverb] [optionally, noun] [options] 

good in terms of remembering which commands are available. cvs, svn, perforce, git all adhere to this. This improves command detection capabilities, which is a major CLI issue. One wrinkle that arises here is the options for the verb master-verb versus the options for subverb. Ie

 cvs -d dir command bar 

differs from

 cvs command -d dir bar 

It was a confusing situation in cvs, which svn “fixed”, allowing parameters specified in any order. Your own decision may vary; if you have a very good reason to pass parameters to the master verb, well, just know about the service data.

Look for usability of the API is also a good idea, but be careful that there is no real typing in the CLI commands, and there is a lot of wealth in which CLI commands are “returned” because you have a return code and exit to work. In the unixy / streams world, output is usually much more important than a return code. Getting the format of your exit right is crucial. Also, although I was seduced, I found that sending different things to stdout vs. stderr is not always useful; this confuses beginners and even intermediate users (because in most cases they are reset to the console) and are rarely useful advanced users. Therefore, if there is no real need, I avoid it; it is too easy for (for example) someone to be very embarrassed why the output of the command was “in error condition” only because the programmer perfectly dumped errors in stderr.

Another design issue is the “what's next” problem. In the graphical interface, the following steps for the user are determined by the available buttons, menus, etc. In the CLI, the user can literally enter any next command and pass any command to any other. (Or try, at least.) I develop my teams to give hints (either in help or in the output) about what potential next steps might be in a typical workflow.

Another good template allows the user to customize the output. Although users can use cut , sort , etc., to adapt the output, the ability to specify a format string increases the usefulness of the command. The example here is top , which allows you to specify which columns you need.