Scenario: Congratulations, you won the lottery! You can barely believe your eyes as you stand there holding the winning ticket! It's amazing - so many feelings rush over you as you realize that some of your dreams are within reach now! You run over, nay, you float over to the lottery office to collect your winnings in pure excitement. You push open the doors to the building, scamper up to the front desk, present your ticket to the clerk, and the exchange goes something like this:

You: Hi! I won! Here's my ticket! Where do I collect my winnings?

Clerk: Hello. I understand you would like to collect your winnings, but I'm afraid I cannot let you do that unless you ask me in a very specific way.

You: .....

Clerk: Perhaps try something like "May I ..., please?"

You: May I have my winnings, please?

Clerk: Hello. I understand you would like to collect your winnings, but I'm afraid I cannot let you do that unless you ask me in a very specific way.

You: May I collect my winnings, please?

Clerk: Congrats on winning! Here you go!

Of course this would never happen in real life, right? There's no possible situation where the above interaction would make any sense in any way.

$ podman -h
Error: pflag: help requested
See 'podman --help'

Ya... Ok. I'm picking on podman[1] above, but it's pervasive in many, many command line tools. There are innumerable ways to ask a tool for help, and this blog's title has the most common ways I've seen, though I'm quite sure there are more. Anyway, the point of this post is to talk a little about the various ways to ask for help on the command line and quickly go over pitfalls.

-h / --help

Ah, the POSIX short/long help options. These are classics. Any competent, POSIX-compliant argument parser will handle them just fine. There are command argument parsers in many, many languages that are (or claim to be) compliant. A myriad of tools use these options, so there's a good chance your users are familiar with using them to ask for help. In my humble opinion, these are the best options to support because of how pervasive support is for them. In other words, many users have been trained with plentiful tools over considerable time, and have built these into their muscle memory. There's a reason why emergency phone numbers don't change arbitrarily every time some operator wants to "disrupt" the scene, thinking they know better. When it comes to asking for help, you probably want your users to get what they need quickly so they can use your tool.

[Edit 2021-04-12] Ok, I was wrong about long options being a POSIX thing, I guess they're a GNU thing.

-help

This one might save you 1 keystroke over --help, but it breaks any attempt to support short option chaining. For example, tar -xjf becomes impossible to parse correctly if the tool expects long option names to be proceeded by a single dash. Did the user mean -x -j -f? Or some option called xjf ?

Honestly, in practice, I've seen many tools that support -help also allow --help and -h for those who have the muscle memory reflex for those, so it's not nearly as problematic.

help

Some folks like to treat "help" as a command/verb on the command line. Some examples might include:

$ go help build

$ podman help run

Or more dramatically:

This pattern is cumbersome to deal with in practice, especially in tools that use subcommands. Instead of typing foo bar -h to get help, you have to move the cursor between foo and bar to insert help: foo help bar in order to get help about the bar subcommand. Then, once you presumably know how to use it, up-arrow, remove help from between the tool and subcommand, move to the end of the line, and continue on.

"Help" is commonly used in speech as an interjection, "Help!", and as a noun, "I need help with ____." It's also used as a verb, e.g., "Can you help me with ____?" However, I feel using it as a verb in command line tools that use the command/subcommand structure is awkward at best, as demonstrated above. It's also a verb in the following sentence: "Are you going to help me?!" Which is exactly what I feel like shouting every time I am forced to deal with tools that insist on using this pattern.

--? / -?

???? I have no idea where these came from, but my guess is that they are migrants from the wild west Windows-land, where I assume the shell won't try to expand ? into anything. Using these options will cause problems for anyone using common shells like bash, zsh, others. Don't do it.

asking for help

One final bit to end with: As in the case of podman above, if you know your user is asking for help, show them the damn help. It serves no one to chide them for not guessing the specific way your app wants them to ask for help. Better yet, support a more "common" way to allow users to ask for help if your app doesn't already. /rant

1. Handling -h aside, podman is a really great alternative to docker. I highly recommend it, for many technical and non-technical reasons!