upvote

points

by joshka1 days ago |
comments
upvoteby dec0dedab0de1 days ago|
next
[-]
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.

reply
upvoteby joshka1 days ago|
parent|
next
[-]
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.

reply
upvoteby dec0dedab0de1 days ago|
parent|
[-]
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.

reply
upvoteby joshka18 hours ago|
parent|
[-]
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.

reply
upvoteby forsalebypwner1 days ago|
parent|
prev|
[-]
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.

reply
upvoteby organsnyder1 days ago|
prev|
next
[-]
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.
reply
upvoteby joshka1 days ago|
parent|
next
[-]
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)
reply
upvoteby maleldil1 days ago|
parent|
prev|
[-]
Jujutsu does it, and it's quite nice.
reply
upvoteby subset1 days ago|
prev|
next
[-]
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.
reply
upvoteby FabDee1 days ago|
prev|
[-]
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.

reply
upvoteby joshka1 days ago|
parent|
[-]
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.
reply