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

51–60 of 217 posts

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

#51

Post by jdporter »

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…

Hit us up on Twitter.

Eh, I think not.

The "commands" I create are, most often, small tools for my own use, so I don't worry about making the names short. I always try to make the name a verb, or include a verb, e.g. "fetchbookmarks", "deleteduplicates"; one exception would be in the case of converters, in which case "convert" is implicit, e.g. "csv2xml" or whatever; and there may be other cases where the verb is implied. The Huffman Coding is important, though, and I have made some tools I use a lot, so I gave them short names. I use gvim a lot, and the wrapper I wrote for it (which does smart finding - it will load foo.cpp wherever it is under your cwd, as long as there's only one) I named g. I don't expect to distribute this tool, so I don't care. :-)

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

#52

Post by 1337shadow »

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…

Or have help show something like a man page such as google/python-fire or yourlabs/cli2

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

#53

Post by thomasbacklund »

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 much recommend The Art of UNIX programming, by Eric S. Raymond [0]

I used it extensively when developing Space.sh [1] (which was an insane shell script adventure purifying for the soul, but taxing on the brain).

Going full termie is the best choice I've made, thanks for a good read! \o

[0] http://www.catb.org/esr/writings/taoup/html/ (There is a PDF available somewhere too) [1] https://space.sh/

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

#54

Post by colejohnson66 »

cle wrote: post #45
resonantjacket5 wrote: post #39

Earlier quoted context omitted.

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.

You just access it, it's just a normal variable. $ python3 Python 3.8.6 (default, Nov 18 2020, 23:56:33) [GCC 9.3.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> quit Use quit() or Ctrl-D (i.e. EOF) to exit >>> q = quit >>> quit = "foo" >>> quit 'foo' >>> quit() Traceback (most recent call last): File " ", line 1, in TypeError: 'str' object is not callable >>> q() $

Wait... So it’s possible to make it so you can’t use `quit()`? Just overwrite it without saving it?

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

#56

Post by cle »

colejohnson66 wrote: post #54
cle wrote: post #45

Earlier quoted context omitted.

You just access it, it's just a normal variable. $ python3 Python 3.8.6 (default, Nov 18 2020, 23:56:33) [GCC 9.3.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> quit Use quit() or Ctrl-D (i.e. EOF) to exit >>> q = quit >>> quit = "foo" >>> quit 'foo' >>> quit() Traceback (most recent call last): File " ", line 1, in TypeError: 'str' object is not callable >>> q() $

Wait... So it’s possible to make it so you can’t use `quit()`? Just overwrite it without saving it?

Yes. You can still send an EOF to quit (ctrl+d), or do "raise SystemExit()" which is all quit() does anyway:

    >>> print(inspect.getsource(quit.__call__))
        def __call__(self, code=None):
            try:
                sys.stdin.close()
            except:
                pass
            raise SystemExit(code)

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

#57

Post by woodruffw »

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

> Check general-purpose environment variables for configuration values when possible

Consider adding `$IFS` to this! Commands that support different output models based on `isatty(3)` often neglect to support `$IFS`, making them more difficult to use in pipelines. This is especially handy in pipelines that need to deal with messy or untrusted inputs; I regularly use `IFS` with the ASCII field escape bytes.

> Don’t bother with man pages.

Please do bother with them! Nobody needs to write raw roff or troff in 2020; there are plenty of high quality manpage generators[1][2][3] that will turn your Markdown/ReST/whatever documentation into sensibly formatted manpages. manpages are much easier to search than the medley of pseudo-formats that CLI tools choose to render their `--help` outputs with.

[1]: https://github.com/rtomayko/ronn

[2]: https://pandoc.org/

[3]: https://www.sphinx-doc.org/en/1.4/man/sphinx-build.html

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

#58

Post by Aeolun »

tpoacher wrote: post #55

> "Don’t bother with man pages. [...] Not enough people use man pages [...] your time is best spent improving web docs and built-in help text." I couldn't disagree more.

I really do not enjoy reading man pages though. tldr or —help is much more likely to contain the info I want on the first screen.

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

#59

Post by actuallyalys »

mdoms wrote: post #15

There's some excellent content here. Unfortunately it is hidden behind an excessively wordy document. You should consider bringing in a ruthless editor to cut this down to about a quarter of it's current length.

What do you think is wordy? It's detailed, but as an occasional editor, I'm not seeing much wordiness. It also makes good use of headers and bolding so readers can skim and skip if they want.

There's definitely imagery, history, and definitions that technically could be cut, but the guidelines would be poorer for it—especially for people with less familiarity with the commandline. I do think they should consider releasing a cheat sheet alongside the full document with just the bolded guidelines.

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

#60

Post by trasz »

Aeolun wrote: post #58
tpoacher wrote: post #55

> "Don’t bother with man pages. [...] Not enough people use man pages [...] your time is best spent improving web docs and built-in help text." I couldn't disagree more.

I really do not enjoy reading man pages though. tldr or —help is much more likely to contain the info I want on the first screen.

That is usually a sign of functionality bloat, not a problem with man pages as such.
Post reply on HN