"to maximize its utility and accessibility"

March 14, 2023 11:35 AM

Command line interface guidelines: a "guide to help you write better command-line programs, taking traditional UNIX principles and updating them for the modern day." Related conversations: "The Poetics of CLI Command Names" (pretty opinionated; previously), "UX patterns for CLI tools" (aiming to cover "how these UX patterns help developers replicate the valuable characteristics of most good GUIs"), "Best practices for inclusive CLIs" (focusing on accessibility), and a Mastodon thread about the benefits of color terminal output. And: some programming languages design their error messages to have better user experience as well. Namely...

The programming language Elm emits human-readable error messages:

• "Compiler Errors for Humans: Rethinking the terminal UX in Elm 0.15.1" (2015): "When we read prose, layout has a major impact on our experience."
• "Compilers as Assistants: Making Elm faster and friendlier in 0.16": " A compiler should not just detect bugs, it should then help you understand why there is a bug."
• "The Syntax Cliff: Teaching syntax with Elm 0.19.1": "I personally think survivorship bias is a huge trap for language designers when it comes to prioritization."

and that's been an inspiration for the helpful, explanatory error messages in the programming language Rust:

• "Shape of errors to come" (2016): "This is the new error format. It's designed around the fundamental observation that errors should focus on the code you wrote. By doing so, you can much more easily see the context of what is going on."
• Rust Compiler Development Guide: Errors and Lints: "...Try not to emit multiple error messages for the same error. This may require detecting duplicates...."

and a new Fortran compiler!

posted by brainwane (31 comments total)

I suspect that the emphasis on human readable error messages is in part a reaction to C++, where the compiler can generate large amounts of its own code in response to the developer's use of generics. If there's an error, it'll include references to code no human was meant to read, so good luck with that.
posted by Spike Glee at 11:58 AM on March 14, 2023 [4 favorites]

From the first link:

The ease of implementation of metaphors was one of the huge advantages GUIs wielded over CLIs. Ironically, though, the CLI has embodied an accidental metaphor all along: it’s a conversation

I like this.

Commands often have different behavior when running in a shell (e.g., ls) so there's no reason they can't be more helpful when appropriate.
posted by ChurchHatesTucker at 12:14 PM on March 14, 2023 [3 favorites]

the CLI has embodied an accidental metaphor all along: it’s a conversation

I watched someone do a demo with ChatGPT last week, and there was actual back-and-forth between the user and the software, refining and improving the query and its results. It really blew me away, because I hadn't seen anyone actually use it for anything besides goofs before.

But thought of another way, the Unix philosophy of connecting commands to other commands with pipes is also a conversation, and probably my favorite thing about a text interface.
posted by wenestvedt at 1:15 PM on March 14, 2023 [6 favorites]

I didn’t realize "commandline is a conversation " wasn’t everyone’s metaphor. Although I have conversations with even slower things; pruning is a conversation…
posted by clew at 1:15 PM on March 14, 2023 [7 favorites]

Is it just me or are the "we're developing a standard for something that's been around forever - ??? - profit" sites coming up a lot more frequently? A junior at work recently came in all fired up about c4model.com. This looks kind of similar, philosophically.

Maybe just my distaste for anyone not-me declaring what "best practices" are.
posted by Tad Naff at 1:26 PM on March 14, 2023 [2 favorites]

As long as I can still look/feel like a wizard when typing in the command prompt, I'm ok with it.

I'm particularly ok for anyone making error messages more meaningful. The amount of time I've wasted staring at an error until it finally dawns on me what the computer is trying to say. Yes, ok, sure, but damn
posted by drewbage1847 at 1:33 PM on March 14, 2023 [2 favorites]

Tad Naff, how is the command line UX guidelines website attempting to make a profit? I also took a look at the C4 model website and it doesn't seem to be a commercial endeavor, either.
posted by brainwane at 1:38 PM on March 14, 2023

Oh, more a feeling that rather than going through the old routes like RFCs or whatever, people are setting up one-off sites to promote homegrown "standards". IIIF.io would be another. Sure, profit isn't spelled out but I can smell training or certification or perish the thought an overhaul of working-fine utilities to conform, thus breaking anything that relies on their output.

But it could be seen alternatively as a "Web 1.0" exuberance to get one's work out there without the gatekeepers being the fun police.
posted by Tad Naff at 2:10 PM on March 14, 2023

Tad Naff, how is the command line UX guidelines website attempting to make a profit?

I think this, ironically, answers Tad's question, lol.

In the good ol' days, everyone knew the joke:

Step 1: Do Something
Step 2: ...
Step 3: Profit!

But people these days have no idea why you expect your Do Something to make money as it's not a commercial venture, because they weren't on MeFi seeing that joke 100x times day for what seemed like a decade plus.

Although in this case, I think it was the text formatting that made it look like Tad was talking about actual profit.

So, kids these days didn't spent 20 years writing UML diagrams on a thousand whiteboards or via a hundred different flowchart applications, and when they search "systems diagram best 2023" they get an article about C4, which they assume is the One True Way.

See also: Hexagonal Architecture.
posted by Back At It Again At Krispy Kreme at 3:03 PM on March 14, 2023 [1 favorite]

I did already know the joke. Every time I have seen anyone use or refer to it, they have been implying that the initiative they are mocking is trying to make a financial profit.

Anyway, have any of you tried Elm or Rust? I've been enjoying the error messages and finding them really helpful as I start learning the language.
posted by brainwane at 3:11 PM on March 14, 2023

I'm just confused about how someone is coding in an email client.
posted by ursus_comiter at 3:23 PM on March 14, 2023 [5 favorites]

As Microsoft discovered, a CLI is a powerful tool and one that shouldn't be neglected. PowerShell is the best damn thing MS has made in a long while.

I think its like gaming. Some things, like FPS games, work best with mouse and keyboard. Other things, like sidescroller action games, work best with a controller. Use the right tool for the job instead of trying to cram everything into a single one size fits all package (looking at you emacs).

Some tasks, I really want a GUI. Some tasks, I really want a CLI.

I still say that Stephenson's essay In the Beginning Was the Command Line is relevant today as long as you ignore the bits which are just an add for the long defunct BeOS.
posted by sotonohito at 4:12 PM on March 14, 2023 [4 favorites]

Elm's compiler errors blew my mind when I was first experimenting. I had never seen such helpful error messages in my life. Cf Haskell compiler errors which are utterly obtuse and really only helpful if you're already familiar with the language.
posted by i_am_joe's_spleen at 5:13 PM on March 14, 2023

sotonohito, so glad someone else remembers In The Beginning Was The Command Line. It's way outdated now, but Stephenson's discussion of abstraction as seen by both a theme park designer and a GUI designer was eye-opening to me, though I'd been both a command line and GUI user for years when I first read it.
posted by lhauser at 5:21 PM on March 14, 2023 [3 favorites]

Oh that takes me back -- In The Beginning Was The Command Line was the first Stephenson I ever read, 20+ years ago.

I started learning Rust using the Rustlings game-type tutorials which uses the error messages as a teaching tool. You get some broken code and use the in-terminal errors as a guide to help you fix it up (in your own preferred text editor), then move on to the next wee bit of code to fix, over and over.

I feel like I remember coming across the mega-helpful Elm error languages several years ago when someone else at Recurse Center showed them to me and I was just wowed. Then Rust kinda took that ball and ran with it. Then, in 2020, my team did user experience research and design to improve pip with way more helpful, readable error messages, including the development work necessary -- building in improved introspection to gather information necessary to provide those messages, etc. I'm not managing that team anymore but the improvements have kept on going; command-line output is just so much more legible and informative and useful than it was before. And the influence of Rust is part of that story, showing us how things could be.

It makes me grateful for all the people thinking and writing about and working on this corner of computing. Passing the baton.
posted by brainwane at 5:37 PM on March 14, 2023 [3 favorites]

I would just like to note that the command line is a powerful and productive place without any programming (well, maybe the occasional alias or one-liner). I let the vast array of *nix tools and utilities do all the work. I just plug them together and spin their dials. My working mantra has long been, "I'm a tool user, not a tool maker."
posted by jim in austin at 7:58 PM on March 14, 2023 [4 favorites]

As a design item, we actually specify a programmable CLI after a prod ops guy had to do over 15,000 button clicks to change a few interfaces via a GUI. The Ops team spent an entire week of doing nothing but clicking buttons.
posted by The_Vegetables at 8:52 AM on March 15, 2023 [3 favorites]

The amount of time I've wasted staring at an error until it finally dawns on me what the computer is trying to say.

Computer says no.
posted by flabdablet at 9:09 AM on March 15, 2023 [4 favorites]

sotonohito: Some tasks, I really want a GUI. Some tasks, I really want a CLI.

But I always want the choice!
posted by wenestvedt at 10:46 AM on March 15, 2023 [1 favorite]

Computer says no.

Now I want to start contributing internationalization patches to open source projects that let them support the new language en_LB.UTF-8, which is identical to en_GB.UTF-8 except that all error, warning and informational messages are rendered as above except kernel panics, which would just read

COUGH
posted by flabdablet at 11:11 AM on March 15, 2023

Perl has/had a module that turned every error message into a Zen koan.
posted by zengargoyle at 11:18 AM on March 15, 2023 [4 favorites]

I really love the command line and I also love errors. Just as a conceptual topic they are much more intersting than a lot of higher-prestige research topics, imo. For me, Elm takes the nice so far it becomes insulting, but in general I am impressed by how accurate they can be. Rust's errors are a fucking nightmare though — errors are hard to type, turns out! — but I know a lot of people are trying to make them better and I look forward to seeing it.
posted by dame at 6:13 AM on March 16, 2023

As Microsoft discovered, a CLI is a powerful tool and one that shouldn't be neglected. PowerShell is the best damn thing MS has made in a long while

It's interesting that this is mentioned in this thread, because I hate the convention for PowerShell native command names. [verb]-[subject] seems simple enough, but the [subject] tends to be wordy and require a lot of typing, and anyway it rejects the whole premise of the article. And PowerShell errors, how they're always printed in red and seem a bit glitchy, always look like something has gone wrong with the shell and not the command. I'm no great CLI expert, but I find it rather off-putting.
posted by JHarris at 1:33 PM on March 16, 2023 [2 favorites]

Oh, more a feeling that rather than going through the old routes like RFCs or whatever, people are setting up one-off sites to promote homegrown "standards". IIIF.io would be another. Sure, profit isn't spelled out but I can smell training or certification or perish the thought an overhaul of working-fine utilities to conform, thus breaking anything that relies on their output.

I can kind of see where you’re coming from but I could not disagree more about IIIF, and would suggest you reconsider in that light. I work at a fairly large library and have spent years putting things online and using other organizations’ collections. The experience used to be terrible: everyone did their own thing, and that meant that nobody’s tools could talk to each other unless people spent time building mapping layers. This shaped one entire project I worked on pretty significantly.

IIIF launched, it was super easy to implement — and things just worked together naturally. I put support into one website and it just worked in the existing applications other people had built. I wanted to replace some custom code in another popular site, tossed another library’s packaging of an IIIF server into an autoscaling AWS ECS Fargate cluster and turned off some servers (IIIF may be too nerdy to be cool but its URLs don’t change). Other people have mentioned including our metadata and images, and they didn’t need to ask for help because their tools supported IIIF.

Yes, it was different and I was a little worried that the semweb influences would lead to unproductive debates but that hasn’t happened and the benefits of removing these rough edges are quite powerful. We’re familiar with the systems we maintain but that knowledge is also a barrier to entry. I think in the case of CLIs that’s especially true because it’s already somewhat unlike what most people are used to and streamlining that process can help get people over the hump to where the benefits really click and sell them on the concept.
posted by adamsc at 7:41 PM on March 16, 2023 [2 favorites]

I'm not a huge fan of the extreme verbosity of powershell commands. OTOH it has a robust autocomplete feature which helps a lot.

Still, I'd rather have a powerful CLI with a sub-optimal command length than no CLI at all or just the incredibly limited oldschool CMD shell.
posted by sotonohito at 6:46 AM on March 17, 2023 [2 favorites]

One of the nice things about shell scripts is that most GUIs give you some way to set one up so that you can drag and drop a bunch of files and/or folders onto your script's icon and the script will then run with the names of all the things you dragged and dropped passed as arguments.

This makes using short shell scripts to automate stuff really convenient when you have specialist batch processing requirements.

The single most irritating misfeature of PowerShell's many irritating misfeatures, from my point of view, is that MS ships it with this capability turned off by default. You cannot, by default, double-click a .ps1 script, or launch it via drag and drop, and have it just run. Nor can you make the PowerShell interpreter accept any file as a script if it isn't named with a .ps1 extension.

I wrote a workaround for this, demonstrating that as a security measure it's utterly worthless. It's just a really annoying little hoop to have to jump through for no sound reason and it's why I still almost always prefer .cmd or .js solutions first for the simple jobs.
posted by flabdablet at 9:30 AM on March 17, 2023 [1 favorite]

One of my failures as a university systems programmer working on infrastructure stuff was writing a single program that did 80% of everything with a command line DSL (think ffmpeg). It was GPT smart, parts were context insensitive, parts weren't, it only had two actual options, it made perfect sense, you could babble into it in a cut-n-paste run-on command line and it would just work.

I could do things in five minutes after being woken up in the middle of the night that took my co-workers an hour. I tried for a good month or so to tell them how to use it. Didn't work, I still had to write and maintain the other score of scripts that I wrote and they used because they couldn't 'grok' my combining them all together.

Of course, the code name for the program was 'grok'. Such a masterpiece.
posted by zengargoyle at 10:11 AM on March 17, 2023 [1 favorite]

If people are going to design a DSL on the command line, it would be polite to give the user the option of sticking the same script in a text file and/or providing a REPL as an alternative. GNU parted does this and I like it a lot. Scripts that get used infrequently benefit hugely from having some kind of inbuilt commenting facility and that's just clumsy to do on the command line.

(DSL = Domain Specific Language, REPL = read-evaluate-print loop)
posted by flabdablet at 10:19 AM on March 17, 2023 [1 favorite]

REPL (sh/bash/etc.) aka CLI was what they did. I wrote those things and documented them and the procedures needed for the situation. My scripts could easily do things like take a host of a list of hosts or a default common list of hosts and check them for both lexical and actual validity against the database of existing things or the proper format for that information.

The whole genesis as it were of 'grok' was actually just cut-n-paste of an email. But I guess you're right in some way, but it becomes more of a BBS door game or text adventure or debugger. "You typed this, you can now do these things" which is surprisingly attractive and I sorta wish I had done that.
posted by zengargoyle at 10:54 AM on March 17, 2023

You are inside a building, a data centre for a large university.

There are some ssh keys on the ground here.
There is a shiny database of existing things nearby.
There are post-it notes here.
There is a button labelled EMERGENCY SHUTDOWN here.
> _
posted by flabdablet at 11:07 AM on March 17, 2023 [2 favorites]

There are two buttons both in protected boxes, on is OH SHIT, the other is DON"T PANIC. I triggered the latter one once when moving a rack of servers on a hand-truck and bumping into a smoke/heat detector. Alarms started going off, mad dash to the Operations Center to hit the DON'T PANIC before power is cut to everything and halon gets dumped. Oops. We moved an entire High Performance Computing Cluster down the road that night and had it back up by morning. I wrote code to make life easy, not to make it Adventure, only one of my co-workers would possibly have enjoyed that. The others wouldn't even have gotten the joke.

But y'know, it would have been waste of time functional to create, but the goal was not needing to make coffee when woken up in the middle of the night and going back in bed.
posted by zengargoyle at 11:52 AM on March 17, 2023 [1 favorite]