Conventions for Command Line Options

Just, whatever, you do, please please PLEASE PLEASE support `--help`. I don't mean `-h` or `-help`, I mean `--help`.

There's only one thing the long flag can possibly mean: give me the help text. I understand that your program might prefer the `-help` style, but many do not. And do you know how I figure out which style your program likes? That's right, I use `--help`. I have to use `--help` rather than just `-help` because of GNU userspace tools, among others. It seems unlikely they're going to suddenly clean up their act this decade, so I have to default to starting with `--help`.

So it's very frustrating when the response to `program --help` is "Argument --help not understood, try -help for help." This is then often followed by me saying indecent things about the stupid program.

I write a lot of commandline utilities and scripts for automating tasks. I find environment variables much simpler to provide and accept key/value pairs than using arguments. Env vars don't depend on order; if present, they always have a value (even if it's the empty string); they're also inherited by subprocesses, which is usually a bonus too (especially compared to passing values to sub-commands via arguments, e.g. when optional arguments may or may not have been given).

Using arguments for key/value pairs allows invalid states, where the key is given but not the value. It can also cause subsequent, semantically distinct, options to get swallowed up in place of the missing value. They also force us to depend on the order of arguments (i.e. since values must follow immediately after their keys), despite it being otherwise irrelevant (at least, if we've split on '--'). I also see no point in concatenating options: it introduces redundant choices, which imposes a slight mental burden that we're better off without.

The only advice I wholeheartedly encourage from this article is (a) use libraries rather than hand-rolling (although, given my choices above, argv is usually sufficient!) and (b) allow a '--' argument for disambiguating flag arguments from arbitrary string arguments (which might otherwise parse as flags).

Most cli parsers don't fully support the author's suggested model because it means you can't parse argv without knowing the flags in advance.

For example, the author suggests that a cli parser should be able to understand these two as the same thing:

    program -abco output.txt
    program -abcooutput.txt

But this is a pain. All it gets you is the ability to save one space character, in exchange for a much complex argv-parsing process. The `-abco output.txt` form can be parsed without such additional context, and is already a pretty nice user interface.

For those of us who aren't working on ls(1), there's no shame in having a less-sexy but easier-to-build-and-debug cli interface.

Very opinionated, and IMO without enough justification.

The assertions around short options with arguments - conjoining with other short options, for example - are actively harmful to legibility in scripts, since there's no lexical distinction between the argument and extra short options. I don't recommend using that syntax when alternatives are available and I deliberately don't support it when implementing ad-hoc argument parsing (typically when commands are executed as parsing proceeds).

I really do like argparse.

It will cleanly do just about anything you need done, including nice stuff like long/short options, default values, required options, types like type=int, help for every option, and even complicated stuff like subcommands.

And the namespace stuff is clever, so you can reference arg.debug instead of arg['debug']

> program -iinput.txt -ooutput.txt

What good is that? Who wants to save a space? Given -abcfoo.txt I can't tell whether it's abcf oo.txt or -abc foo.txt? So that's a definite drawback, and the benefit is?

> Go’s [...] intentionally deviates from the conventions.

Sigh

Of course if does.

> When grouped, the option accepting an argument must be last ... program -abcooutput.txt

Good grief, no.

There may be some utilities out there which work this way, but it is not convention and should not be regarded as one.

Single letter options should almost always take an argument as a separate argument.

Some traditional utilities allow one or more arguments to be extracted as they are scanning through a "clump" of single letter options:

  -abc b-arg c-arg

Newly written utilities should not allow an option to clump with others if it requires an argument. Only Boolean single-letter options should clump.

Under no circumstances should an option clump if its argument is part of the same argument string. For instance consider the GCC option -Dfoo=bar for defining a preprocessor macro, and the -E option doing preprocessing only. Even if -Dfoo=bar is last, we don't want it to clump with -E as -EDfoo=bar --- and it doesn't.

But, in the first place, even if it did, we don't want to be looking to C compilers for convention, unless we are specifically making a C compiler driver that needs to be compatible.

Some other commenters have mentioned environment variables as input.

IMO there are broadly two types of command: plumbing and porcelain. There's a certain amount of convention and culture in distinguishing them and I'm not going to try to argue the culture boundary...

For the commands which are plumbing (by whatever culture's rules), the following apply:

* They are designed to interact with other plumbing: pipes, machine-comprehension, etc

* Exit code 0 for success, anything else for error. Don't try to be clever.

* You can determine precisely and unambiguously what the behaviour will be, from the invocation alone. Under no circumstances may anything modify this; no configuration, no environment.

For the commands which are porcelain (by the same culture's rules, for consistency), the following apply:

* Try to be convenient for the user, but don't sacrifice consistency.

* If plumbing returns a failure which isn't specifically handled properly, either something is buggy or the user asked for something Not Right; clean up and abort.

* Environment and configuration might modify things, but on the command line there must be the option to state 'use this, irrespective of what anything else says' without knowing any details of what the environment or configuration currently say.

To make things more exciting, some binaries might be considered porcelain or plumbing contextually, depending on parameters... (Yes, everyone sane would rather this weren't the case.)

Do I add more to this code just for convention? The command line option parsing (or broken ParseOptions dependency) will become magnitudes larger and more complex than what the program does.

  usage = 0
  argc = len(sys.argv)
  if argc == 2 and sys.argv[1] == "-r":
   hex2bin()
  else:
   if argc == 2 and sys.argv[1].startswith('-w', 0, 2):
    s = sys.argv[1][2::]
   elif argc == 3 and sys.argv[1] == '-w':
    s = sys.argv[2]
   elif argc >= 2:
    usage = 1
   if usage == 0:
    try:
     width = int(s)
    except ValueError:
     print("Error: invalid, -w {}".format(s))
     usage = 1
    except NameError:
     width = 40
   if usage == 0:
    bin2hex(width)
   else:
    print("usage: mondump [-r | -w width]")
    print("       Convert binary to hex or do the reverse.")
    print("            -r reverse operation: convert hex to binary.")
    print("            -w maximum width: fit lines within width (default is 40.)")
  sys.exit(usage)

I recently ran into a case I hadn’t seen before with python’s argparse. Multiple arguments in a single option, e.g. “—foo bar daz” with —foo set to ‘*’ swallows both bar and daz, where I would have expected to have to explicitly specify “—foo bar —foo daz” to get that behaviour. I guess this is a side effect of treating non-option arguments the same as dash-prefixed arguments, but I have no idea what the “standard” to expect with this is?

Otherwise, my main bugbear is software using underscore instead of dash for long-names, and especially applications or suites that mix these cases.

I really like the simplicity that docopt somewhat forces you into, which avoids most of these tricky edge cases, but am seeing less and less usage nowadays of it.

I use clap/structop in Rust for all my CLIs ever since those libraries came out and it's just stupid easy to make a nicely functioning CLI. You define a data structure which holds the arguments a user will pass to your program and you can annotate fields to give them short and long names. You can also define custom parsing logic via plain functions if the user is passing something exotic.

At the end you can parse arguments into your data structure in one line. At that point the input has been validated and you now have a type safe representation of it. Well-formatted help text comes for free.