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