Designing command-line interfaces

Designing command-line interfaces
antoarts.com

Provide explicit flags for default behavior.

For example, if your lines-of-code counting utility excludes preprocessor directives by default, and includes them when you pass "-i", provide an "-x" switch that signals to use the default behavior. This way, when someone wants to write a bash script that uses your utility, they can do this:

    case $include_directives in
    y)
        LOC_FLAGS='-i';;
    n)
        LOC_FLAGS='-x';;
    esac

    myloc $LOC_FLAGS

1.) It's explicit, and thus more obvious and clearer.

2.) It's more consistent, so there's no risk of empty/unset variables, whitespace, or other edge conditions screwing up a delicate munging operation.

3.) It's change-tolerant, so if future versions of your utility change the default behavior, scripts will continue functioning as expected.

---

Speaking from an experience writing CLIs for configuration-heavy embedded devices, the key design element of a functional CLI is a context-aware TAB expansion. This is what makes a CLI truly convenient for routine use.

For example, if a mysql shell was smarter, it would've been allowing this:

  > use p                   expands to "use production"
  > show c s      expands to "show columns from secondary"
  > select * f s ...     expands to "select * from secondary ..."

  # ip addr         shows "ip addr add"
  #                 shows "ip addr del"
  #                 shows "ip addr"

Use your language's command-line option processing libraries.

OptionParser in ruby and argparse in python. There is no reason to eschew these libraries: they're part of the standard library, they require zero coupling to your app logic, and they handle all of the edge cases for free.

"But I can just shift the arguments", you say! Yeah? Great! What if the user pipes input through STDOUT? What if the user passes a flag, a required argument, and then another flag? Will your script read the last flag correctly, or has the naive logic already entered "required argument processing mode"? Just use the library. It's a solved problem!

Context-aware tab completion is very doable in the unix world, actually; it's just a hassle on the part of the utility-writer. Have you ever noticed that if you add a new file "foo/bar/baz.py" to a mercurial repository and type "hg add fo", it will autocomplete all the way to "foo/bar/baz.py", without stopping at each directory? This is because hg has overridden the default tab completion provided by bash and defined its own set of possibilities.

I wish it were easier to set up; I think if that were the case, we'd see a lot more utilities with spot-on tab completion.