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

1–10 of 217 posts

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

#2

Post by bfirsh »

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 the 1980s.

On this search I found a superb blog post by Carl about CLI naming [1]. He must be the only person in the world who cares about CLI design and is actually a good writer, so we teamed up. We also were joined by Aanand, who did loads of work on the Docker CLIs; Eva, who is a technical writer, to turn our scrappy ideas into a real piece of writing; and Mark, who typeset it and made a super design.

We love the CLI, but so much of it is a mess and hard to use. This is our attempt to make the CLI a better place. If you’re making a tool, we hope this is useful for you, and would love to hear your feedback.

Some of it is a bit opinionated, so feel free to challenge our ideas here or on GitHub! [2] We’ve also got a Discord server if you want to talk CLI design. [3]

[0] https://replicate.ai/

[1] https://smallstep.com/blog/the-poetics-of-cli-command-names/

[2] https://github.com/cli-guidelines/cli-guidelines

[3] https://discord.gg/EbAW5rUCkE

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

#3

Post by raywu »

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…

Thanks for these resources! Definitely relate. CLI is the original chatbot

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

#6

Post by EE84M3i »

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.

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

#7

Post by mmalone »

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.

Yea, like, imagine if posix pipes and command-line flags could be typed.

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

#8

Post by ucarion »

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 wrapping cobra's weird API differently...

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

#9

Post by uhoh-itsmaciek »

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…

This is great, thank you! Under pagers, maybe add a note to respect PAGER if set? I prefer relying on terminal scrollback in some situations, and e.g. in psql often set PAGER=cat. Git respects this, too.

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

#10

Post by vageli »

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

Yea, like, imagine if posix pipes and command-line flags could be typed.

Powershell offers this I believe.
Post reply on HN