Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

CLI Guidelines – A guide to help you write better command-line programs

clig.dev

Post reply on HN
Print view View original

31–40 of 217 posts

Re: CLI Guidelines – A guide to help you write better command-line programs

#31

Post by abathur »

bfirsh wrote: post #2

Hello HN! We’re Ben, Aanand, Carl, Eva, and Mark, and we made the Command Line Interface Guidelines. Earlier this year, I was working on the Replicate CLI [0]. I had previously worked on Docker so I had a bunch of accumulated knowledge about what makes a good CLI, but I wanted to make Replicate really good, so I looked for some design guides or best practices. Turns out, nothing substantial had been published since t…

Thanks for writing! I haven't had a chance to read it yet, but I'm always looking for new opinions here. Looking forward to going through it :)

Re: CLI Guidelines – A guide to help you write better command-line programs

#32

Post by scbrg »

mmalone wrote: post #26
kitotik wrote: post #20

Earlier quoted context omitted.

Right. I still prefer terse help text from the command line, and more in-depth in the man pages. I find commands with copious -h output and having to pipe that into a pager or using scroll back a far worse UX than just opening up a man page that’s easily searchable / scrollable.

Yea that's reasonable, but there are pros and cons and it's also definitely an opinion :). I don't see the problem with piping help text through a pager (that's literally all `man` is doing). Alternatively, a tool can use a pager automatically (as `git help ...` does). So `man` isn't required to have a pager. Whether you should use a pager by default is a different argument. That said, I find pagers annoying because…

> I don't see a lot of benefit to using man pages other than "because that's how it's always been done".

Man pages are organized, categorized, indexed and searchable. It's a common format that can be read by multiple pagers (including dedicated GUI browsers for those so inclined). They're also available when the command might not be. There are definitely benefits over command --help other than the syntax of the invocation.

> I find pagers annoying because it's hard to switch back and forth between typing a command and the docs.

less -X

If people don't know about man, why not teach them? A simple line in the summary -h gives that says: For more information, read the man page: man foo.

> Plus, there's still the cross-platform argument.

This just makes me sad. I don't know exactly where we'd be if every computer system didn't feel it needed to be garbage just because Windows is. But I don't think it'd be quite as bad as where we are.

Re: CLI Guidelines – A guide to help you write better command-line programs

#33

Post by colordrops »

mmalone wrote: post #18
kitotik wrote: post #16

This is a great resource, thanks for the effort. I strongly disagree with the “ Don’t bother with man pages” advice. It’s extremely annoying when tools don’t provide a manpage. The overhead of opening up a browser to reference command is cumbersome and highly annoying. There are tools such as pandoc that make generating manpages from various source formats very easy. Perhaps it is just my grouchy old man syndrome…

They're not saying you shouldn't provide command-line help. Just that you should deliver them through a `help` subcommand and/or through a `--help` flag (like `git` does) because people don't find man pages and because man pages don't work on every platform.

Perhaps prioritize a --help flag over a man page, but add both if time permits. In any case, a man page is static text and much easier to implement than --help, especially if you have multiple help modes (e.g. verbose or different sets of commands).

Re: CLI Guidelines – A guide to help you write better command-line programs

#34

Post by whelming_wave »

ucarion wrote: post #8
bfirsh wrote: post #2

Hello HN! We’re Ben, Aanand, Carl, Eva, and Mark, and we made the Command Line Interface Guidelines. Earlier this year, I was working on the Replicate CLI [0]. I had previously worked on Docker so I had a bunch of accumulated knowledge about what makes a good CLI, but I wanted to make Replicate really good, so I looked for some design guides or best practices. Turns out, nothing substantial had been published since t…

Since you bring up Docker, this little behavior has always baffled me: $ docker image ls -h Flag shorthand -h has been deprecated, please use --help But: $ docker image -h ls Flag shorthand -h has been deprecated, please use --help Flag shorthand -h has been deprecated, please use --help Flag shorthand -h has been deprecated, please use --help What's up with that? I'm guessing cobra nonsense, because everyone ends up…

I know you're talking about how it's repeated three times, but something else here really bothers me.

I understand if they're deprecating it because they plan to replace it with something else, but if they don't then I'll be pretty disappointed. From their docs, it looks like some of their other subcommands have shorthands which conflict with `-h'? Fine, I guess, but that just means when `-h' does work it'll shoot people in the foot with that other behavior.

Software that clearly knows what I want, but refuses to, annoys me so much. For example,

    $ python3
    Python 3.9.0 (default, Dec  2 2020, 10:34:08) 
    [Clang 12.0.0 (clang-1200.0.32.27)] on darwin
    Type "help", "copyright", "credits" or "license" for more information.
    >>> quit
    Use quit() or Ctrl-D (i.e. EOF) to exit
because they added `quit' as a top level variable with a `__str__' defined which returns that string. Do anything else! Make the `__str__' definition quit the program or something, test if it's being run at the top level in the CLI and quit, special case the CLI input so if only `quit' is entered, it quits. Heck, maybe just prefill the `quit()' on the next line so I just have to hit return. Do anything but instruct me to do what you should have done in the first place.

Re: CLI Guidelines – A guide to help you write better command-line programs

#36

Post by kitotik »

rhencke wrote: post #25
_underfl0w_ wrote: post #19

Earlier quoted context omitted.

Maybe I'm suffering from similar syndrome, but I'm under 30 in human Earth years. However, I very much agree with you and would take it a step further to say that programmatically opening the browser with the help flag is also very unwelcome (I'm looking at you, git >.> )

It is your choice, in Git: git config --global help.format man

TIL! Thanks for that.

Re: CLI Guidelines – A guide to help you write better command-line programs

#37

Post by reaperducer »

mmalone wrote: post #18
kitotik wrote: post #16

This is a great resource, thanks for the effort. I strongly disagree with the “ Don’t bother with man pages” advice. It’s extremely annoying when tools don’t provide a manpage. The overhead of opening up a browser to reference command is cumbersome and highly annoying. There are tools such as pandoc that make generating manpages from various source formats very easy. Perhaps it is just my grouchy old man syndrome…

They're not saying you shouldn't provide command-line help. Just that you should deliver them through a `help` subcommand and/or through a `--help` flag (like `git` does) because people don't find man pages and because man pages don't work on every platform.

Why not both?

Write the help for the more verbose of the two, then trim it back for the other.

Everyone gets what they want.

Re: CLI Guidelines – A guide to help you write better command-line programs

#38

Post by reaperducer »

zokier wrote: post #24

> The command line of the past was machine-first > Traditionally, UNIX commands were written under the assumption they were going to be used primarily by other programs Is there any real factual basis for these claims? I find them hard to believe, considering the origins of UNIX and the fact that shell was the primary (or even only) user interface for the system, and it was pretty much from day 1 designed as an inter…

My recollection is that non-programmers followed the instructions in the binder, which told them how to log in, and then how to start the program they needed. Very basic stuff. Actual commands were the province of programmers.

Re: CLI Guidelines – A guide to help you write better command-line programs

#39

Post by resonantjacket5 »

whelming_wave wrote: post #34
ucarion wrote: post #8

Earlier quoted context omitted.

Since you bring up Docker, this little behavior has always baffled me: $ docker image ls -h Flag shorthand -h has been deprecated, please use --help But: $ docker image -h ls Flag shorthand -h has been deprecated, please use --help Flag shorthand -h has been deprecated, please use --help Flag shorthand -h has been deprecated, please use --help What's up with that? I'm guessing cobra nonsense, because everyone ends up…

I know you're talking about how it's repeated three times, but something else here really bothers me. I understand if they're deprecating it because they plan to replace it with something else, but if they don't then I'll be pretty disappointed. From their docs, it looks like some of their other subcommands have shorthands which conflict with `-h'? Fine, I guess, but that just means when `-h' does work it'll shoot pe…

I mean if you did that how would you access 'quit' if it is defined? It's a bit more complicated than it seems.

Though I get your general point.

Re: CLI Guidelines – A guide to help you write better command-line programs

#40

Post by jen20 »

kitotik wrote: post #16

This is a great resource, thanks for the effort. I strongly disagree with the “ Don’t bother with man pages” advice. It’s extremely annoying when tools don’t provide a manpage. The overhead of opening up a browser to reference command is cumbersome and highly annoying. There are tools such as pandoc that make generating manpages from various source formats very easy. Perhaps it is just my grouchy old man syndrome…

Absolutely - I can't buy into the "don't write man pages" idea.

For many years I've had this function in my RC files for macOS:

    pman() { man -t "$@" | open -f -a Preview; }
It opens the given man page in Preview, typeset beautifully. No such thing is available for random text printed to the console, nor is a console pager (as recommended by this article) an acceptable substitute for this.
Post reply on HN