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

71–80 of 217 posts

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

#71

Post by Aeolun »

kevincox wrote: post #43
dllthomas wrote: post #29

Loving this! As a nit: > Let the user escape. Make it clear how to get out. (Don’t do what vim does.) If your program hangs on network I/O etc, always make Ctrl-C still work. If it’s a wrapper around program execution where Ctrl-C can’t quit (SSH, tmux, telnet, etc), make it clear how to do that. For example, SSH allows escape sequences with the ~ escape character. I find it confusing that vim is considered less disc…

I agree, if you press Ctrl-C vim (with default settings) literally tells you how to quit. `\n~` in SSH is completely unrecoverable.

If you are already using SSH in a situation where ‘exit’ doesn’t work, it becomes more reasonable to assume the user will know.

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

#72

Post by Aeolun »

thomasbacklund wrote: post #53

Nice read, makes me happy to see people invest in CLI. "Humans first"... How about "Humans with Tools first" ? :) I would say that ALL logging should go to stderr (level should be --configurable of course), so that when running a container for example I can capture all the logging easily on stderr. Also that [WARN], [ERROR], etc tags are quite nice to have in there when grep'ing over it.. Just saying :) I would very…

It would be nice to see an example of space.sh usage somewhere on the landing page. I was intrigued by “through 10 firewalls” but not quite enough to go to the documentation and look it up.

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

#73

Post by throwaway201103 »

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…

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.

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

#74

Post by hamburglar »

woodruffw wrote: post #57

These are some pretty good guidelines! Many thanks to the authors for writing them up. Some nitpicks (what would HN be without nitpicks?): > If your command is expecting to have something piped to it and stdin is an interactive terminal, display help immediately and quit. I disagree with this advice: being able to spoon-feed input into a program is extremely useful, and is part of the "conversational" CLI paradigm th…

> being able to spoon-feed input into a program is extremely useful, and is part of the "conversational" CLI paradigm that the authors mention above. Commands that silently block on `stdin` are frustrating, but the right solution is to check `isatty(3)` and print an informational message rather than killing the program entirely

This was the one thing I was coming here to nitpick. I use the "blocking stdin" behavior regularly to pipe copy/pasted text through various commands (various openssl subcommands, for example) and would be very annoyed if a program decided on its own that I shouldn't be doing that. At most, it should print a message like "Reading from stdin..." or something on stderr, but even that seems like introducing noise to hold the hands of people who don't understand the pipe paradigm.

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

#75

Post by throwaway201103 »

brownjohnf wrote: post #63
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…

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…

These old commands are also terse because the user was very often working at a teletype at 110 baud, or some other very slow type of terminal.

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

#76

Post by WalterBright »

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…

What I do is with the -man switch:

    command -man
it opens the browser on the manual page for the command, such as for dmd it's https://dlang.org/dmd-windows.html

The result so convenient I added -man to the other command line tools. I thought about adding clickable urls to the error messages, but it just made the output too cluttery.

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

#77

Post by legends2k »

brandmeyer wrote: post #67

Great doc! I disagree about abandoning manual pages. I always reach for `man foo` even before `foo --help`. Missing detail: Exit codes should be restricted to a range of 0..255 inclusive. Many POSIX system calls only forward the low-order 8 bits of the exit code to a parent process.

+1 I look at programs not supplying man pages as carelessly coded ones with little discipline.

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

#78

Post by [deleted] »

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…

[deleted]

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

#79

Post by 0x445442 »

The command line, in terms of the terminal emulator, really needs to evolve to more of a Meta-X mini-buffer pattern.

People keep circling around the sweet spot which is a fixed location command input area that outputs, in addition to text streams, any variety of multi-media.

On one end you've got a set of people doing heroic designs in the terminal with all variety of UTF-8 characters. On the other end you've got things like Jupiter Notebook.

What I'm looking for is something like the Mattermost UI without the chat aspect being front and center. Or Emacs, but with the ability to embed Youtube videos in a buffer.

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

#80

Post by Shared404 »

_underfl0w_ wrote: post #19
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…

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 >.> )

Under 20 and agree as well, on both accounts.
Post reply on HN