In the beginning was the command line. And the command line is still there. Whether you're using sh, bash, csh, tch, zsh, fish or something else, you end up running the same commands. Today I want to talk about those commands. Or at least those commands and the principle of least surprise.
Let's start with a simple one. `-?` Should print out help for your command. I know someone can come up with a
valid case where that doesn't make sense, but unless you've got a really good reason, go with that. Bonus points
also giving the same output for
Another easy one. Have a way for the user to get the version of your command. If you have subcommands use
version if not, use
You should be able to type each flag by itself (in any order), or collect flags into a series of characters preceded by a `-`. If any of those flags need an option and don't get it then that's an error.
Having more than one instance of a flag that can't be repeated should be an error. If you don't like that, take the last value.
Simple, common options should have simple one-letter ways to specify them. They should also have more verbose
options. And it's OK to only have more verbose options for some things. Always use
-- for your
--help, if you have sub-commands then
--help should work at any level, giving more detailed info about the sub-command when
Have sensible defaults. That's going to be very context sensitive, but if you have defaults they
need to make sense. An obvious example would be
rm using the current directory as a base
given a fully qualified path.
Use stderr and stdout appropriately. Put the pipeable output of your command into stdout, and send errors to stderr. And once you've released an output format think 3 or 4 times about changing it. Someone has parsed it and is using it as the input to something else.
Command completion is your user's friend, so support it. Especially if you have lots of sub-commands and
options. Bonus points here for being able to compete options and providing alternatives when the user spells
something wrong (like
And above all, never make them say "WAT"