Please don't ever make the short version of a cli flag be different than the long version.

The short version is for typing on the fly, and the long version is for scripts, they should have identical output.

The full thorough documentation should be in man, and/or info.

My perspective on the rationale for splitting short/long help is that optimizing for the reader's time is a reasonable thing to do. Often I just need a refresher of what options are available. But sometimes I need a deeper understanding of what each option controls and how. (Yes I understand that this should be in man pages). There needs to be a reasonable way to control the verbosity of the help output from the command line however.

I agree with your point that most flags should generally treat short versions as exact aliases to long flags, but I just think that a convention that treats -h and --help as concise vs long is 100% reasonable. The distinction is often breadth vs depth.

That would be a perfectly reasonable convention, except it's already a convention that they do the same thing.

Having them be different could cause someone to look at -h, and not even know about --help. Or if someone writes a script parsing the output of -h for some reason, someone else might come along and change it to --help expecting it to be the same thing.

The rust crate clap which is one of the more well known crates for command line parsing gets about 2M downloads a day and has this convention built in.

This convention existed before clap came into being, but I don't recall when I first saw it. I have been using the command line for just shy of 40 years across various operating systems.

100% agree, not sure where this idea came from but I'm not a fan.

You can just make a `--help-all` (or whatever word you want to use), imo the `--help-all` command doesn't need a short equivalent because it's not something you'd frequently use.

I've never heard of this convention. Every getopt-style CLI tool I've used has identical behavior whether an option is specified in its short- or long-form.

Any rust cli built with clap or go cli built with cobra supports short and long help and surface these with `-h` and `--help` (I think cobra surfaces this in the help command rather than in the --help, which is probably a reasonable alternative way to frame this)

Jujutsu does it, and it's quite nice.

About the cf domains -h vs cf dns -h drift you flagged, in my case, I've watched Claude learn one subcommand format, then take for granted the same flags on a sibling with a different help shape.

It's not cosmetic. Uniform help is a way to not let agents hallucinate. Otherwise you end up with invalid commands, or worse, silent ones that go through without doing anything at all, or go totally wrong.

yeah - absolutely. I use codex all the time with jj and encourage it to check the help for details about how to run commands as the commands / args / flags have evolved post training-cutoff date.

Possibly controversial, but I think short commands should be disallowed. This is the stance the AWS CLI takes, and it 1) vastly improves readability, especially for those learning the syntax 2) makes it less easy to shoot yourself in the foot with a typo.