Considerations when creating a command line interface

Question

There are lots of GUI best practices. I am looking for best practices when developing a command line program.

For example, if I were creating a backup program what is best?

Consideration 1, invocation:

program.exe backup

program.exe /backup

program.exe -backup

program.exe --backup

Consideration 2, parameters:

program.exe backup "C:\file1.txt" "C:\file1.bak" (implicit source and destination)

program.exe backup -source "C:\file1.txt" -destination "C:\file1.bak" (explicit)

program.exe backup -source "C:\file1.txt" "C:\file2.txt" "C:\file3.txt" -destination "C:\files.bak" (multiple sources)

program.exe backup -source "C:\file1.txt" -source "C:\file2.txt" -source "C:\file3.txt" -destination "C:\files.bak" (multiple sources, alternative syntax)

Consideration 3, chaining:

program.exe backup "C:\file1.txt" "C:\file1.bak" backup "C:\file2.txt" "C:\file2.bak" (should this be allowed?)

Consideration 4, typing economy:

program.exe backup

program.exe bkp

program.exe b (should all these be aliases to the same command?)

Answer 1

I'd always prefer what's (in order of importance from most to least):

• Most understandable by the end user
• Least ambiguous
• Follows the conventions of the platform being coded against
• Easiest to parse in my code

So on Windows I'd go for / as the prefix (follows the conventions), /source and /destination (most understandable AND least ambiguous) and not allow chaining as that makes for parsing complexity, so:

program.exe /backup /source:"c:\source" /destination:"c:\destination"

By all means also permit abbreviated versions of the parameter names, so you could allow the above to be shrunk down to:

program.exe /b /s:"c:\source" /d:"c:\destination"

But don't make it any more arcane than that. Also, include a /? parameter that can be used to list the syntax for your program. As Peter M pointed out in the comments on my answer, it's a good idea to do the same as /? when the user calls your program without specifying any parameters. Nothing's less helpful and more frustratingly useless than running a CLI program and receiving:

Program Name v1.01

No parameters specified, use /? for help

One other important thing to consider, tied to the final point, would be: don't reinvent the wheel. There are innumerable Command Line Parsers out there, take a look at the answers to this question for a starting point (if you're using C# targeting Windows). Don't do a mediocre job of doing something that someone else has already done a good job of doing.

Answer 2

I prefer using double dashes for long names in addition to single character equivalent short forms with single dashes.

If you are making something non trivial I'd also suggest to always use a switch name and have switch values optional depending on what the switch does.

So for example to backup support both of:

  program.exe --backup   
  program.exe -b 

And to restore support both of:

  program.exe --restore "5/6/2010"
  program.exe -r "5/6/2010"

For help support both of:

  program.exe --help
  program.exe -h

Answer 3

Definitely parameters and with /Help switch to explain usage. So that end user have freedom of which parameter to put first and hence not force a particular order of the parameters

Answer 4

• Allow --long-option-name and -lon for optional parameters.
• Create backup.exe instead of using backup as a command to program.exe.
• Use standard input and standard output as default input and output files.
• Use current directory as default location for operations.

That's for general UNIX/Linux rules. For Windows, they are completely different.

• Don't use /source and /destination. Imagine the hell it would be if cp (copy) required it.

Answer 5

In general, you should stay within the conventions of the platform. Unfortunately, Microsoft Windows has been pretty inconsistent about command-line interfaces! Therefore, you should be equally inconsistent. I think the ideal model in this case is the famously inconsistent dd:

dd if=C:\file1.txt of=C:\file2.bak

There's nothing else quite like it.

Answer 6

Well for starters I would ditch the program.exe syntax and just go for backup.exe

I like the /option:<value> syntax myself. I'd probably like to be able to the following:

backup /d:"c:\mydirectory" /o:"c:\mybackup.bak"
backup /f:"c:\mydiredctory\myfile.txt" /o:"c:\mybackup.bak"
backup /f:"mydiredctory\myfile.txt,mydiredctory\myfile2.txt" /o:"c:\mybackup.bak"

Answer 7

I recommend finding a library that will allow you to define your command-line parameters and parse them properly, while also printing out usage instructions that define all of your parameters to the users of your application. There should be plenty of open source libraries available for multiple languages and platforms.