Can I optimize this command-line interface?

Question

I am designing a command-line interface for users and administrators to interact with an online radio system. One of the administrator tasks is assigning songs and albums to various genres. This is the general format of the command I designed for this task:

> command-name action object-class object-id target-genre

In this particular case:

• command-name is manage-genre
• action can be one of show, add, drop, reset
• object-class is either song or album; operating on an album is a shortcut for operating on every song in the album
• object-id is a unique numeric identifier for the song or album; it can be obtained through other commands
• target-genre is the genre to apply to the song or album

An example in context might be:

> manage-genre add song 12345 "Vocal"

Is there a best practice for how to order the arguments in this command? Is there a more natural way to do it? Can you point me to any literature on designing useful command-line interfaces?

Answer 1

Your word order is pretty good, it's generally a good idea to keep to a familiar "sentence structure" like format, especially if you want a natural-language like search. Keeping similar to how the familiar CLIs (DOS and Unix) work is important too.

Unix Standards are pretty much the standard for CLI applications and I wouldn't stray far from their model.

command [options] [arguments]

In this format, manage-genre is your command, add songcould be seen as an extension of the command or your options. Your arguments are 12345 and Vocal. In a natural language approach the order is a bit more important than the specifics of what's an option and what's a command though; to the users you're really saying "Do what" (command or verb) and "with what" (arguments or nouns). Think of the structure of an imperative sentence to a human:
Label song 12345 as Vocal.

Start with the command (the verb) and order your arguments from least specific to most specific because, in most cases this makes sense. It's harder to get the gist if you order the sentence as "Vocal is the genre in 12345, the song." By stringing arguments from most specific you start out with what you're looking for in general (a song), then once we know the context we learn the specific item (12345), then once we know what we're operating on, we're ready to hear what specific attribute is changing (Vocal) .

Interestingly there's a great deal of discussion about Natural Language CLI applications there seem to be little to no guidelines or standards to be found. Most everything uses the Linux model, but it's not the most Natural Language approach.

Answer 2

The pattern I have observed in CLIs that I use on a regular basis (Unix/Cygwin, perforce, ant, etc) is: "sub-commands" go first, required arguments go on the command line as-is; optional args go with option flags. For example:

cp file-1 file-2

Both files are required arguments.

ls -als

There are no required args, but three options that themselves pass no values are specified for how the command operates.

rm -rf tmp

"tmp" is a required argument (the directory to remove); "r" and "f" are options to the "rm" command.

p4 integrate -i //some/place //some/other/place

p4 (perforce) is the command, integrate is the operation (sub-command), -i is an optional argument with no value, and //some/place and //some/other/place are required args.

ant -f my_build.xml compile

"ant" is the command, "compile" is the operation, and "-f my_build.xml" means override the default build file with this one. Note that the argument here (-f) takes a value so its syntax differs from the ones above that didn't.

One thing to be noted from all this is that you need to understand your default behavior. Is everything you've listed really required to be explicit, for example, or does your program default type or genre? Relatedly, are IDs unique and, if so, do you actually need to specify song vs. album? Can't you tell without the user saying it?

Another thing to be noted is that applications can have "sub-commands", e.g. perforce (p4) has several operations, like "edit", "integrate", and "delete", that come on the command line right after the application name. Do you have several "manage" operations, or is genre the only thing you can operate on?

Depending on the answers to these questions, the following command lines seem plausible:

manage add -genre "vocal" 12345 (add new song)
manage add 24680 (assign default genre)
manage change -genre "pop" 12345 (song is already in system)
manage add -group "top-40" 12345 (add this song to a collection, distinct from genre)

On Unix flags go after the command/sub-command and before positional arguments. You haven't said what systems your users are used to or what your application will be running on, but you should be consistent with whatever is normal in their environment.

Answer 3

Most Unix commands either take at most one or two ordered non-option arguments:

cp source target
mv source target

or take an arbitrary number that all (or almost all) refer to the same kind of thing:

echo word1 word2 word3 word4 word5 ...
rm file1 file1 file3 ...

Another common pattern is to have the first argument to the command be the action to perform:

git commit -m "Message" this-file that-file

Having four arguments, each of which has a different meaning, with a required order, strikes me as a bit much. You're likely to end up with songs whose genre is "12345".

If I were implementing this, I'd probably make all but the "action" arguments to options. For example:

manage-genre add -type song -id 12345 -genre "Vocal"

And I'd probably make -song and -album equivalent to -type song and -type album, respectively. In fact, given the abbreviations, I might just drop the -type option altogether:

manage-genre add -song -id 12345 -genre "Vocal"

You'd need a fair amount of logic in the program itself to determine which combinations of options are permitted, with the command failing with an error message for a number of errors: type not specified, missing information, -id given twice, -id with an invalid id, -id as the last argument, and so forth. (Do the work once when you're writing the program so the user doesn't have to do it over and over.)

You might also allow some options to be omitted in some cases; for example, manage-genre drop -id 12345 probably doesn't need the other fields.

(I might also consider using a shorter name than manage-genre, depending on how often users are going to have to type it.)

Answer 4

OP: "Can you point me to any literature on designing useful command-line interfaces?"

Concept: Command wizard

I don't have "literature" per se, but in this post, I'm proposing the concept "command wizard" that presents the CLI as "a friendly search dialog", feeling familiar to Google.com. It relies heavily on regular expressions, dictionaries and synonyms to guide the user in 1) formulating the initial command, and also 2) in supplying the desired command parameters.

Using synonyms, users can initiate commands using their personal vocabulary, while being informed about the business' preferred nomenclature.

If you go to the original post (also here on UX-SE) you'll see the wider picture, with lots of intended benefits: "Familiarity, improved readability, reduced intimidation, more efficient, less strain, focus on content, improved batch entry, improved registration workflows, natural language support, guided process, embeddable".

Simplified use case

• Use case: User wants to approve a number plate.
• Solution:
  • Keyboard focus is already in the input field.
  • User types "app".
  • Several "autocomplete" rows, Google-style, appear beneath the input field. The top item is Approve vehicle DD12345.
  • User presses arrow down and Enter, selecting the autocomplete.
  • The system supplies a confirmation in a dedicated feedback field (not a pop-up). The vehicle status is correctly updated in the read-only view. A highlight appears and fades away.

Test results

I did some testing for a client (with a JavaScript-driven mock-up). The feedback was the best I have ever had as an interaction designer. The users passed the tests, the managers were close to ecstatic, and co-workers said things like "this concept is the best I have seen in [the company]". Unfortunately, just as the project received green light, there was a worldwide layoff the company, and the staff in this particular department was reduced heavily. The concept therefore never reached production status. The research is therefore limited to the initial testing of the mock-up.

If you have relevant examples pertaining to the concept that would be most appreciated.

Screen shots

Proposed interface – User issues command in the input field (presses p then arrow down):

Proposed interface – When issuing commands, the optional "command wizard" provides help entering parameters: