5 ms·
Best Practices for Inclusive CLIs
- usrn 4y agoWhy "inclusive?"
- gtirloni 4y agoWhat are some libraries that already follow most of this advice? I see cobra used in Go fairly often but I don't know if it's the best option.
- jamal-kumar 4y agoAll I care about is if weird stdout messes with scripts at all and gives proper error codes out for consumption by scripts as well. A lot of these guidelines are doubly useful to not only human readability but machine readability.
- lucasfcosta 4y agoI’m the author of the post Rohan mentions here. I must say I thought this was an amazing critique. It was respectful, thoughtful, and well-structured. Thank you, Rohan. You’ve got excellent points and great references too. Much appreciated.
- Seirdy 4y agoThank you for the kind words. You made my day.
- agumonkey 4y agoElegantly accessible webpage too :)
- hvdijk 4y ago> Conform to tools that share a similar niche. If you’re using Rust to make a fast alternative to popular coreutils: model its behavior, help-text, and man pages after `ripgrep` and `fd`. I'm surprised by this. Why wouldn't you model the behaviour after grep and find? The fact that ripgrep uses a different regular expression syntax than grep is my main problem with it; if there were a utility with the functionality of ripgrep, but the RE syntax of grep, I would switch over in a heartbeat.
- burntsushi 4y agoWhat syntax is in grep that you miss from ripgrep? Anyway, there are a lot of different ways to interpret the OP here. Honing in on "use the same regex syntax as grep" seems strange. Maybe they just mean: if you want to see how man pages are produced in Rust programs, then take a look at how these programs do it. Rather than something about the specific content that should go in it. Notice also that the OP started this thought with "alternative to coreutils" program. Rather than a "clone of a coreutils program."
- hvdijk 4y agoIt's nothing missing, it's just different for no clear reason, and that means remembering different syntaxes depending on which tool I am using at the moment. The one I use most: GNU grep and git grep use `\<` and `\>` for word boundaries, with ripgrep that produces "error: unrecognized escape sequence" and I have to use `\b` instead. (Note: GNU grep and git grep do support `\b` too.) > Maybe they just mean: if you want to see how man pages are produced in Rust programs, then take a look at how these programs do it. I do not think that is what they mean. A man page looks the same to the end user no matter what tools are used to produce it. > Notice also that the OP started this thought with "alternative to coreutils" program. The start of the thought was "Conform to tools that share a similar niche." ripgrep and fd being implemented in Rust are details that are not relevant to an end user. For ripgrep, the "tools that share a similar niche" would not be "tools that are implemented in Rust", it would be "tools that search in files using regular expressions", and I would be happier with a tool that matches the other tools that I use. So actually I completely agree with the author's principle, I just think it was a bad example.
- burntsushi 4y ago> I do not think that is what they mean. A man page looks the same to the end user no matter what tools are used to produce it. And you can look to ripgrep to learn how to produce one! And in particular, how to do it without duplicating docs. In any case, my point is that maybe there is a more expansive viewpoint here that makes sense instead of honing down on to something hyper specific. > It's nothing missing, it's just different for no clear reason, and that means remembering different syntaxes depending on which tool I am using at the moment. Right, so you want a POSIX compatible tool because POSIX is what you're used to and you don't want to use any other interface. Which is fine. Keep using the old stuff. I don't see any good reason to exactly imitate POSIX when I can go build something that I think is better without being constrained by POSIX. For example, I think just having \b is better than having both \< and \>. > I just think it was a bad example. I don't. There's a lot that tools like ripgrep and fd do that the old tools don't do that turn it into its own niche. Like enabling "smart" filtering by default and other things that many consider to be quality of life improvements. So if you're in that niche, then looking to those tools for what they do is a good idea.
- kkfx 4y agoBeware a thing: the strong point of CLIs vs GUIs was and still is IPCs or the ability to pipe I/O from a single-purpose program to another. Rich textual output for better human interaction means the need of a "quiet mode" for easy piping, something many forget. In interactive terms though the reasons for CLIs wane quickly: document-UI, some have called "2D CLIs" serve us far better in mean, see Emacs vs Unix classic. In that case CLIs are just a tool to call "functions" and see their return values. For inclusivity also consider a thing: blind people who use screen readers migh have troubles in document UIs so they might prefer CLIs but those made for being audio-based, decorations and co does not help.
- Klasiaster 4y agoFor good processing of the output it makes sense to add a flag like "--json", otherwise people have to come up with their own parsing that makes assumptions of the output and breaks as soon as the output is changed slightly, e.g., by adding a new field.
- kkfx 4y agoI hope not. CLIs are meant for interactive usage, quick passages with simple key-value or crafted regexp are far better than ANY pre-made DSL, JSON is not for humans. CLIs are for human. The "integration" issue of CLIs is the classic Unix issue respect of Smalltalk systems, LispM etc: unix choose to be a container-ship for individual container instead of a unique ecosystems where programs are just functions/method of a common app. Such issue can't be solved hammering our genitals with JSON, YAML or something else, it's already well solved by OS designs like the aforementioned systems. A unique language, perhaps flexible enough to make new ones (like Racket, but any Lisp can essentially do the same easily) if needed, but still an OS-framework-operating-environment as a unique application where anything live inside. The reason we do not have that on scale is simply commercial: it's far more profitable the divide et impera vs crafting unique systems where being open is the most natural, sometimes mandatory, way to go...
- JoeyBananas 4y agoDrawing any kind of border around the --help output? There's something very wrong with that.
- yakshaving_jgt 4y agoI’m personally not a fan of it, but it seems unfair to label it as “very wrong”. I prefer that people have the freedom to make design choices like this.
- its_bbq 4y ago> How “unique” is your tool’s output? Output should look as similar to other common utilities as possible, to reduce the learning curve. Keep it boring. I actually disagree with this. When skimming through long logs looking for errors I find it really useful that output from different tools look different at a glance. It helps me narrow down into where I'm looking for.
- motohagiography 4y agoWould there be any value in creating a document spec for CLI help output? Once there was something, individual projects could adopt it - or not, but it would be toward the goal of a future CLI ux that supports something like NL2Bash (https://github.com/TellinaTool/nl2bash https://github.com/TellinaTool/nl2bash) where we can create natural language interfaces to OS based services.
- timcavel 4y ago