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

61–70 of 217 posts

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

#61

Post by trasz »

klodolph wrote: post #41

I think we should abolish different prefixes for short/long flags except for core POSIX programs (like ls, cp, rm, mkdir, etc.) In other words, "-flag" should be interchangeable with "-flag". The ONLY reason I can think of why you would not recognize "-flag" as equal to "--flag" is because you want to recognize it as "-f -l -a -g", which makes sense for programs like ls, but for 99% of newer programs, don’t do it. Ju…

Thing is, being able to concatenate options together saves a lot of typing.

(And honestly, —long-flags are rarely useful in practice. Unless you have no man page to figure out what the single letter options do.)

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

#62

Post by pwg »

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:

    command --help 2>&1 | less
to cause the help text to actually be piped into less.

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

#63

Post by brownjohnf »

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 the era also still actually printed mechanically, so keeping command length short was a major ergonomic win for round trip speed.

As a sibling comment mentions, these commands were (are) commonly composed into scripts. As the name implies, however, a script is just a playbook for a series of commands to run. Given the terminals of the era, I'm sure short commands/variables/etc. were appreciated in scripts as well, but it seems to me that the primary motivation for optimizing input speed would be the use of these commands in an interactive environment.

A few examples of these core short program names: ls, cat, cp, rm, wc, uniq, cmp, diff, od, dd, tail, tr, etc.

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

#64

Post by pdkl95 »

A few additions to these recommendations:

> Show full help when -h and --help is passed

It is also a good idea to support --version

    $ make --version
    GNU Make 4.1
    Built for x86_64-pc-linux-gnu
    Copyright (C) 1988-2014 Free Software Foundation, Inc.
    License GPLv3+: GNU GPL version 3 or later 
    This is free software: you are free to change and redistribute it.
    There is NO WARRANTY, to the extent permitted by law.
> Use standard names for flags, if there is a standard.

In the interest of consistency across tools, I recommend consulting the Table of Long Options from the GNU Coding Standards.

https://www.gnu.org/prep/standards/html_node/Option-Table.ht...

Some long options that are particularly helpful, when appropriate:

    ‘dry-run’
         ‘-n’ in make.

    ‘null’
        ‘-0’ in xargs.
Also, options that increase safety:

    'no-clobber'
        ‘-n’ in mv
        # do not overwrite an existing file

    'overwrite'
        ‘-c’ in unshar
        # even better than --no-clobber, require explicit
        # permission before overwriting existing files
edit:

Never try to be "smart" or "magic" and guess what the user intended! DWIM can appear useful at first, but we've known for a long time that DWIM behavior is dangerous[1].

[1] https://news.ycombinator.com/item?id=15628014

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

#65

Post by timsneath »

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.

What a fantastic tip. Thanks for sharing!

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

#66

Post by u801e »

scbrg wrote: post #32
mmalone wrote: post #26

Earlier quoted context omitted.

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 invoc…

> A simple line in the summary -h gives that says: For more information, read the man page: man foo

Interestingly enough, GNU utilities include a message in each man page that tells you to run info for more detailed information :)

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

#67

Post by brandmeyer »

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.

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

#68

Post by hultner »

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.

I also appreciate man pages, hate it when they are missing. The (Free)BSD man-pages are truly great, I’d never have to google anything if others held the same standard.

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

#69

Post by zelly »

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 dangerous commands

- separate the interface into a tree of subcommands (Go/Docker/AWS style) rather than a flat assortment of flags

- if you are displaying tabular data, present an ncurses interface

- (extremely important) shell completion for bash and zsh

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

#70

Post by Aeolun »

pdkl95 wrote: post #64

A few additions to these recommendations: > Show full help when -h and --help is passed It is also a good idea to support --version $ make --version GNU Make 4.1 Built for x86_64-pc-linux-gnu Copyright (C) 1988-2014 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. > Use sta…

Depends on what you are doing. If it’s just a transformation or display of data, there’s no reason not to do what the user meant.
Post reply on HN