CLI Patterns/Antipatterns for usability

Question

What patterns contribute or detract from the usability of a CLI interface?

As an example consider the CLI for ClearCase. The CLI is very comprehensive (+1) but it is has several glaring opportunities. Recently, I wanted to force the files to lower case into ClearCase using clearfsimport. Unfortunately I wound up on the documentation for its cousin clearimport. It may seem slight but it cost me more hours than I care to admit. The variation in the middle got me.

Why provide such nearly identical functionality with such nearly identical names? There are many better options in my opinion

• clearimport -fs
• fsclearimport
• clear_fs_import
• clearimport_fs

Anything would be better than what they went with. The code I am working on IS a CLI and this experience made me look at my own choices. I think I have all the basics covered (standard help, long-form vs short-form, short meaningful names, providing examples, eliminate ambiguity, accurately handling spaces within quotes, etc).

There is some literature on this subject.

Perhaps a bad CLI is no different than a bad API. CLI are type of an API in some sense. The goals are naturally common:: flexibility, readability, and completeness. Several factors differentiate CLI from a typical API. One is that CLI needs to support scriptability (participate many times perhaps in a series of pipes). Another is that autocompletion and namespaces don't exist in the same way. You don't always have a nice colorful GUI doing stuff for you. CLIs must document themselves externally to customer directly. And finally the audience of a CLI is vastly different than the standard API. I appreciate any insight you may have.

Answer 1

I like the subcommand pattern, which I'm most familiar with as its implemented in the command-line Subversion client.

svn [subcommand] [options] [files]

Without the subcommands, subversion would have waaaaay too many different options for me to remember them effectively, and the help system would be a pain to slog through.

But, if I don't remember how any particular subcommand works, I can just type:

svn help [subcommand]

...and it shows me only the relevant portions of the help documentation.