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

211–217 of 217 posts

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

#211

Post by alpaca128 »

brabel wrote: post #168
alpaca128 wrote: post #113

Earlier quoted context omitted.

Icons in GUIs are commonly used for interactive elements. Most CLI tools are not interactive, they just produce some output and the user expects that output to be easy to parse and compatible with as many terminals as possible. You can easily output tables, bullet lists and many other things just with basic symbols supported everywhere. If your CLI program requires installing fontawesome or breaks in a terminal multi…

Emojis are part of unicode. No need for font awesome to support emojis. Visit https://emojipedia.org and notice how all emojis have their own code point :)

I merely mentioned fontawesome as one of many possible examples. And as already said, a symbol having its place in unicode does not mean it is available on the computer or in a certain program. For example, in Linux terminals it's not uncommon that at least one optional font installation is required in order to get various emoji to display correctly, let alone other non-western symbols.

Many people use the terminal exactly because it displays fewer kinds of content than e.g. a web browser, which as a side effect simplifies many situations.

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

#213

Post by bfirsh »

bfirsh wrote: post #152
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…

The sentiment was meant to be: "Make `command help` as good as a man page. More people will read that." We didn't mean to suggest to use web pages instead. We also didn't mean not to use man pages at all. We just find more people use the built-in help and web pages, so if you have limited time/resources, it's better spent on those things. In retrospect, perhaps it was worded a bit strongly. I am enjoying the debate,…

More details for any readers here: https://github.com/cli-guidelines/cli-guidelines/issues/57

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

#214

Post by GoblinSlayer »

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…

He doesn't claim that docker cli is well designed, only that he worked on it. Docker cli is pretty bad indeed, tar tier. Its web docs are also an example of butchered web 2.0.

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

#215

Post by GoblinSlayer »

throwaway201103 wrote: post #73
pwg wrote: post #62

Earlier quoted context omitted.

I did not see a personal pet-peeve of mine: If a user of your CLI tool has explicitly requested the built-in help text via --help (or an equivalent switch that requests help) then that help text shall be output on stdout. It always peeves me to do: command --help | less only to find that the explicit request for help (the --help switch) has output the help text on stderr, and I then have to redo the invocation: comma…

Your CLI should also have a man page, installed in the standard way. IMO, -? or --help should be fairly terse, ideally one screenful or less. More complete documentation should go in the man page. Edit: wrote this before I read "Don’t bother with man pages." Strongly disagree. Relying on web docs leaves your users in the lurch if they are working on a system with no external network.

I write docs as a plain text file (in /usr/share/doc), works everywhere, view with anything in any way you want, locally or in the web, no converters needed.

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

#216

Post by dllthomas »

AlphaSite wrote: post #148
matt_kantor wrote: post #136

Earlier quoted context omitted.

I'm not who you replied to, but I hardly ever need to use tilde escape sequences to quit ssh. I just terminate the session from inside itself with the `exit` command.

The most common case I’ve hit issues is the remote server is down or blocked but the connection hasn’t yet terminated so exit is no longer possible.

I've occasionally had things crash in ways that have swallowed ctrl-c. More recently I've learned to still try ctrl-z in those cases, as that often still works (but not always).

None of this is very common, but I found myself opening another terminal and killing the ssh process probably tens of times before I learned about the ~ escapes.

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

#217

Post by gnubison »

klodolph wrote: post #183
gnubison wrote: post #171

Earlier quoted context omitted.

> And in the end, CLIs are for humans first. I don't think that CLIs are more suited to either humans or computers. CLIs are flexible enough to be effectively used by both. > Usage in practice would be split between -flag and --flag. So what? Well, you're breaking everybody's expectations and many years of conventions by doing it. Saving one dash with every flag and losing the ability to combine short options is just…

> I don't think that CLIs are more suited to either humans or computers. CLIs are flexible enough to be effectively used by both. Either a human is sitting at a terminal typing commands, or a human is sitting at a text editor writing a shell script, or a human is writing a program which runs other commands. In all cases, it's a bunch of strings pasted together and the computer can't typecheck it, so we need to make s…

Perhaps short options are unreadable. But if I see a shell script that contains a long option with only one dash, I will definitely be confused... I don't think that saving a dash makes a shell script more readable. It definitely doesn't improve the situation enough to justify messing with people's preconceived ideas.

I don't even know what to say about your assumption that I'm biased because of my username. One might even claim that you're the narrow minded person to be judging people's biases based on three letters in their username.

Which programs don't allow you to combine short options? Other than perhaps hastily written shell scripts. getopt(3) is POSIX AFAIK so there's not really any excuse for POSIX programs to not handle combined short options.

Post reply on HN