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

171–180 of 217 posts

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

#171

Post by gnubison »

klodolph wrote: post #126
jooize wrote: post #123

Earlier quoted context omitted.

Strongly disagree. Be consistent, avoid ambiguity, reduce risk of uncertainty. The convention has the feature of combining flags, but there's more. Making -flag and --flag equivalent means combining flags is not possible without potential collisions, and the distinction would become less obvious overall. Usage in practice would be split between -flag and --flag. Enable such inconsistency for what benefits?

Yes, I agree… be consistent and avoid ambiguity. Combined short flags are the most ambiguous of all. Usage in practice would be split between -flag and --flag… so what? They shouldn’t mean different things, because it is too easy for humans to miss the extra -. And in the end, CLIs are for humans first.

> 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 not a good trade off.

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

#172

Post by oars »

jen20 wrote: post #40
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.

Thank you for sharing this tip!

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

#173

Post by dTal »

nocman wrote: post #169
jen20 wrote: post #40

Earlier quoted context omitted.

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.

For those on Linux you can do this with: f=$(mktemp);man -t "$@" > "$f" && ( {some-pdf-viewer} "$f" ; rm "$f" ) ... replacing '{some-pdf-viewer}' with whatever PDF viewer works for you. There is probably one that will take the document on stdin, but I am not aware of one. I realize I'm late to the party here, but thought is was worth posting anyway. (edited for typo)

With BSD man (default on Void Linux) you can do:

MANPAGER= man -T pdf

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

#174

Post by airstrike »

johnisgood wrote: post #164
airstrike wrote: post #90

Earlier quoted context omitted.

Also the font size is hardcoded so zooming in does nothing other than making scrolling terrible

It works for me. I can decrease the font size the usual way.

Still doesn't work for me in Firefox on Windows

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

#175

Post by EE84M3i »

rmetzler wrote: post #131
EE84M3i wrote: post #6

It's kind of crazy that we still don't have a standard computer readable way for a program to describe it's argument structure in a computer readable way that could be used for command line autocomplete. E.g. something like an extra section in the binary that describes how arguments are processed.

I think it would be probably easier to have a convention of programs to output their autocompletion options similar to how github.com/urfave/cli does. https://github.com/urfave/cli/tree/master/autocomplete

There still needs to be some out of hand signal that it accepts that option otherwise you would pass it to tools that don't and cause undefined behavior.

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

#176

Post by pimlottc »

pwg wrote: post #62
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…

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…

THANK YOU. Showing the usage documentation when the user has explicitly asked for it /is not an error/.

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

#177

Post by zelly »

brabel wrote: post #105
zelly wrote: post #69

My advice as a user of CLI: - no emojis please, ever - if you want to make it look nice, use ANSI escape codes for color rather than emojis. even then, don't use color alone to convey meaning because it will most likely get destroyed by whatever you're piping it to. - please take the time to write detailed man pages, not just a "--help" screen - implement "did you mean?" for typos (git style) and potentially dangerou…

> - no emojis please, ever Why not? Do you also don't want to see icons in GUIs?

It's not portable. It looks really bad on a terminal emulator that does not support emojis (at least half of the ones out there esp on Linux). There are dozens of emoji fonts which all look different. You never know what your user is going to see. If your users are only using macOS and Terminal.app, then it may not be so bad, but if you are building a command line application, then I should be able to use it from a text-only console on an old system, VM, or embedded device. Don't assume all your users are going to be using it from a Macbook Pro or Ubuntu.

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

#178

Post by anamexis »

alpaca128 wrote: post #116
brownjohnf wrote: post #63

Earlier quoted context omitted.

I think the common terseness of many of the core suite of original unix tools actually reflects a strong focus on human, not machine, ergonomics. I still appreciate the speed and ease of typing them, and like many other aspects of the CLI, it's optimized for users who know it well and use it heavily. Once you're familiar with the names, it's not challenging to remove that mv = move, wc = wordcount, etc. Terminals of…

I find it interesting how GUI and CLI drift apart so far in this area. Powerful GUI software for specialised tasks is often overloaded with buttons and toolbars everywhere because the user needs to be able to click them. The terminal is the complete opposite, instead of clicking through menus to find the right option(or use a ton of keyboard shortcuts) you have to know what to type. But it's also very efficient and f…

That's true, but I think GUI drifts back when you consider the arcane keyboard shortcuts a good GUI has for power users.

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

#180

Post by solatic »

nocman wrote: post #169
jen20 wrote: post #40

Earlier quoted context omitted.

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.

For those on Linux you can do this with: f=$(mktemp);man -t "$@" > "$f" && ( {some-pdf-viewer} "$f" ; rm "$f" ) ... replacing '{some-pdf-viewer}' with whatever PDF viewer works for you. There is probably one that will take the document on stdin, but I am not aware of one. I realize I'm late to the party here, but thought is was worth posting anyway. (edited for typo)

You should be able to avoid using mktemp by:

pman='some-pdf-viewer <(man -t "$@")'

Post reply on HN