Command Line Interface Guidelines
An open-source guide to help you write better command-line programs, taking traditional UNIX principles and updating them for the modern day.
This is the source code for the guide. To read it, go to clig.dev.
Join us on Discord if you want to discuss the guide, or just chat about CLI design.
Contributing
The content of the guide lives in a single Markdown file, content/_index.md. The website is built using Hugo.
To run Hugo locally to see your changes, run:
$ brew install hugo
$ cd <path>/<to>/cli-guidelines/
$ hugo server
To view the site on an external mobile device, run:
hugo server --bind 0.0.0.0 --baseURL http://$(hostname -f):1313
License
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
Broken (non-portable?) ls flags example
At one point, the guidelines suggest that if it were written today,
ls
might have the default flagslhFGT
. This doesn't work for me in Ubuntu 20.04:(but more importantly: awesome guide, thanks for putting it together)
Do not accept secrets via environment variables
I don't think this is at all controversial, is it?
mysql
accepted aMYSQL_PWD
env var forever, and it's finally been deprecated and will eventually be removed.From their docs:
Best way to extend/superset these guidelines?
Hi! As it turns out, y'all releasing this was super timely, as I was working with some folks at my job on coming up with some CLI guidelines that we could use organizationally and for our public tool. What I'm wondering is more your thoughts on how you imagine people extending or building on top of these:
I'd love to hear about what y'all think. This is a fantastic, amazing document and I definitely think it's the right thing to build anything on top of.
Clamp maximum font size
On a 3440x1440 monitor at full screen, the body text size is ~41.28px (
1vw * 1.2rem
, where1vw = 34.40px
), which is pretty hard to read. The font size at >1600px could be clamped at 20px, rather than its current1vw * 1.2rem
.Add docker pull multiple progress bars example
While an animated illustration will be great, when ready, for now this static snapshot of the progress bars can be helpful for readers who may not be using Docker and do not know what the article is talking about.
The example captures a good mix of states of various progress bars:
argparse for Python argument parsing?
I was surprised to not see argparse in the list of python cli libraries. Is there a particular reason why it is deemed not-great? Personally, the biggest thing it has going for it is that it's built in to Python, so you can use it for all your custom python scripts without needing to install third-party libraries.
Document FORCE_COLOR
Document use of FORCE_COLOR variable which forces enablement of coloring and ignore the detection logic.
There are other similar option used like CLI_COLOR, PY_COLORS but that one is by far the most popular option. This complements the NO_COLOR option with missed to cover for the opposite use-case when it was designed.
Adding a CLI argument parser for Deno
Deno is a Javascript and TypeScript runtime, this pull request adds a link to a CLI argument parser (officially supported as it is part of Deno's standard library)
Args/flags: Use a cross-platform example for the set of default flags ls(1) might use if designed today
Change the
ls -lhFGT
example tols -lhF
. These flags are supported by macOS, Linux (GNU coreutils), NetBSD, and OpenBSD. Details at https://github.com/cli-guidelines/cli-guidelines/issues/39#issuecomment-984232908. Thanks for considering this PR!Fixes #39.
Add a CLI argument parser for Perl
Thanks for this set of guidelines --- it's clear that a lot of hard work has gone into the philosophy and guidelines! Would you be willing to add Perl's standard argument parser to the list? Thank you for considering this PR!
Provide a repository with example implementations
This is a fantastic resource, but from what I've found, it's not necessarily easy or straightforward in some languages to implement these solutions. Rather than requiring every developer to re-implement these guidelines from scratch in their language of choice, I would recommend creating a repository of implementations that provide support for this using the language's standard library.
I would recommend using the Builder creational design pattern, as discussed on https://refactoring.guru/design-patterns/builder, to allow developers to control which features they support. I really appreciate the hard work and dedication of the team, and would love to implement these guidelines, but without more concrete resources, I've found at times it's unrealistic. Any solutions, example implementations, etc. would be very useful in my opinion for developers hoping to support this and be a good steward.
Permalinks don't open to the right spot in Firefox
Just came across an odd navigational issue.
When I open a new tab in Firefox 105.0.3 on a Mac and go to https://clig.dev/#environment-variables, I end up in different places depending on what machine I'm using. It appears to be some sort of race condition, because on one machine I end up in Errors, and on the other I end up in the Output section.
Other notes:
@ThinkMake any idea what may be happening here?
Localization for Chinese version
Hi team,
This CLI guideline is a good reference for designing CLI tooling. I am willing to help translate it into Chinese and promote it in the local community. May I start to work and contribute to this?
"Increase information density—with ASCII art!" is problematic for accessibility
There is an item in the Output section that reads:
Unfortunately, while ASCII art can be great for improving information density for some users, it is generally problematic for accessibility and inclusivity:
I think it would be preferable to rewrite the ASCII art item along these lines:
I considered adding this as a comment on #5, but I thought this felt more immediately actionable when taken on its own, so I made it a separate issue.
Add explanation about syntax
Add explanation about syntax.
Building a syntax for a CLI is important because it gives a strong foundation for the CLI.
It provides the following advantages:
This commit explains how a syntax for a CLI can be establisihed, and the advantages.
Limitation: need more examples.
Signed-off-by: Myoung-Jun Lee [email protected]
"Make it easy to type." harms its credibility with "apple" vs. "orange"
This is too subjective to recommend in such an unqualified fashion.
I'd take
apple
overorange
any day because, now that you've brought them to my attention, I find that apple is significantly easier to type than orange... party because I'm still training my left hand to touch-type and partly because I actually find that doubled letters are easier to type.In fact, before I finished reading through your citation and concluded that you made that example out of whole cloth, the combination of that flawed example and the title "The Poetics of CLI Command Names" was giving me the false impression that Carl Tashian was some wishy-washy person who is not to be trusted because he gives subjective advice and claims it's objective.
That said, I am curious why I and whoever wrote that have such different subjective experiences. Is it possible they're using a membrane keyboard or a laptop? I'm using a buckling-spring board, which is about as full-travel and tactile as you can get.