[fermienrico]

The biggest problem with CLI is discoverability as the article points out. Looking at Docker CLI, there are like a bazillion commands and it takes forever to read through the docs to find out what exactly to use. Furthermore, there are some commands that depend on the others being there - that breaks the composability.

Back to discoverability, is there a way to make CLI "more discoverable"? Reading the man page doesn't count. Like can we combine the advantages of CLI with the discoverability of GUIs? I wanna have the cake and eat the whole thing.

[njharman]

GUIs are a discoverability nightmare.

I've always found --help (or help <command> for tools breakin the "standard") and man pages massively more discoverable than any gui.

There are two well known entry points "--help" and "man". There has been much convention standardization with operating system guis, still they have many, many possible entry points. not all programs use same ones, use in same way. And webapps/pages are complete non-convention chaos.

both --help (but not "help <command>" (a reason they are "wrong") and man are 1 level deep and show you the entire ui, all at once. That is definition of discoverable! One action, i've discovered everything.

GUIs are deeply nested. And context sensitive so it may not even be possible to see actions until certain condition is met. The definition of opaque and undiscoverable.

[crazygringo]

> GUIs are deeply nested. And context sensitive so it may not even be possible to see actions until certain condition is met.

This is a feature, not a bug.

For me, browsing 20 pages of --help or man is a discoverability nightmare. I don't want to wade through arcane option after arcane argument.

The GUI gives me a well-organized top-level understanding of the program: organized menus, and organized panes (panels/palettes/tabs/etc.). Then I can drill deeper into dialog boxes and tool settings as needed.

It's far more efficient to quickly browse a GUI to figure out the lay of the land, than it is to wade through what is essentially the reference manual of a CLI tool.

Reference manuals are the opposite of discoverability.

[cuddlybacon]

> This is a feature, not a bug.

Seconded.

The hard part of CLIs is discovering what is possible in the current context. You can almost take for granted that a GUI will do this for you. CLI not only won't, but will often fail to discuss this in the man page.

While there are exceptions (eg tmux), I find most man pages are written for someone who already knows how the command works but forgot a particular detail.

[cvlasdkv]

> While there are exceptions (eg tmux), I find most man pages are written for someone who already knows how the command works but forgot a particular detail.

Isn't that a function of how much work is put into man pages vs. the GUI? I'd be hesitant to claim that if you took the same number of hours in writing a GUI and put it into writing better documentation that we'd be in the same place we often are with poorly documented tooling.

[camgunz]

CLIs and GUIs aren’t an either/or proposition. They each implement very different paradigms; OP goes over them pretty reasonably. You’re not supposed to discover a CLI; you’re either supposed to remember the 4 things you do all the time (see git) or script it and build your own interface/program (see coreutils or stuff like troff). It’s an entirely different UI. Arguing that CLIs aren’t discoverable misses the point just as much as arguing that GUIs aren’t composable. They’re not supposed to be.

[hhas01]

“CLIs shouldn’t be discoverable because they’re not supposed to be discoverable.”

Imagine if we applied the same defeatist tautological thinking to our other written materials: books wouldn’t have TOCs or indexes, the Web wouldn’t have search engines, and so on.

10,000 years of the written word, yet nothing is learnt. SMH.

Maybe if text-based interfaces did provide good, safe discovery they wouldn’t have been beaten into a cocked hat by GUIs for 99% of users. And this is despite GUI being something of a UX trap itself (as CLI fans are happy to point out), becoming ever moreso as personal computing moves beyond traditional physical point-and-click and expands into voice control.

Honestly, there’s more text smarts in a modern smartphone’s txt-ing interface than in today’s “cutting edge” of 1970s CLI design.

Is it really about providing good UI/UX, or about preserving the entrenched power structures of the computing world status quo?

--

“It’s a curious thing about our industry: not only do we not learn from our mistakes, we also don’t learn from our successes.”—Keith Braithwaite

[camgunz]

It's not a tautology, it's choosing how something works. Try it with other things:

"Guitars shouldn't have reeds because they're not supposed to have reeds"

"Cars shouldn't have pitch controls because they're not supposed to have pitch controls"

> Maybe if text-based interfaces did provide good, safe discovery they wouldn’t have been beaten into a cocked hat by GUIs for 99% of users.

This isn't so much CLI vs. GUI but interactive vs. non-interactive. Think CLI vs. TUI. Then (hopefully, I guess) you'll realize that it's a deliberate difference in paradigm vs. one or the other being superior.

Indeed, this is the entire point of OP. Reification of the interaction means making that interaction first-class, and CLIs do this by making the interaction the invocation, which you can then manipulate. You can't (mostly, w/o some kind of session scripting tool or w/e) do that in a GUI or TUI.

Kind of a lot of heated discussion about this but, it doesn't seem like it's that big a deal.

[cma]

I rarely wade through it and just search for what I'm looking for. Typing '-i' (in the session, not as a param) will make the search case insensitive if using 'less'.

[crazygringo]

That's great, but that's not discoverability, that's searching for something you know/hope/suspect is already there.

Discoverability is about having what you can do be presented to you in the first place. It's the very opposite of looking things up. The information comes to you in a contextual way, instead of you having to go searching for it.

[themacguffinman]

So the solution is to use another separate CLI utility that you have to read the manual for, and memorize '-i' as an option for it?

[cma]

I wouldn't consider less a pure CLI utility, since it puts the terminal more into a screen mode.

[craftinator]

Same reason I stay away from text books and stick to picture books and comics! Text is boring and tedious, pictures are cute and fun!

[stnmtn]

Don't think this is a fair comparison. You can drill down quickly to learn new actions you didn't know before in a GUI. That's a whole lot harder to do in a CLI

[old-gregg]

> GUIs are a discoverability nightmare.

Badly made GUIs are. I started my career developing desktop software. Both Apple and Microsoft used to publish guides for building proper GUIs for their platforms. Our UX designers and PMs were enforcing those vigorously.

On Windows, every feature had to be represented in the menu of the main window. See, right there, by going (not even clicking on) every menu item you will learn about existence of every feature. Photoshop is still like that.

Most frequently used actions deserved two additional things: a hot key and a toolbar button. Each toolbar button had to have a tooltip. See? Right there, by going over the toolbar one could quickly learned the most important features.

Using windows, splitters, panes, tree views and tabs - there was logic behind those choices, and having standardized set of UI controls allowed users to learn software much more rapidly.

Modern web "applications" are crude by comparison. There's no standardized way to discover anything. Is it a button? Is it a dropdown? Is it just a strange background to display an error? Things auto-hide and auto-appear for no reason, you have to move mouse around (or practice every swipe variation you're familiar on mobile). Hotkeys are an afterthought, even resizing the browser or even scrolling sometimes breaks things.

I am not going to name names, but we tried to use one of web-based conferencing apps a few years ago. The UI it offered for joining a call (the URL you'd include into a meeting invite) was so bad that nearly 30% of people could not find out how to join. That's basically the only thing that page needed to provide, yet their UX people managed to obfuscate it so much that users sat waiting & thinking that something is about to happen instead of clicking the "join" button... Ughh.

There's so much demand for software right now, every industry needs more... There is severe shortage of talent for everything, from engineers to UX designers and product managers. Eventually there will be an equilibrium and we'll have professionals design and program GUIs again.

I am a CLI-first person, but there's no doubt in my mind that a well-done GUI massively flattens the learning curve for a new app.

[jsrcout]

I fondly remember Apple's Human Interface Guidelines for the Macintosh, and software that followed it. Even if you'd never seen a given application before you could easily discover its features and how to operate it.

Having said that, I think CLI programs tend to not get enough credit for discoverability. It's just a different kind of discoverability (man $program, $program --help).

[falcolas]

> Badly made GUIs are.

So pretty much every browser out there? Without knowing ahead of time from random pilfering through various menus, how can you tell if your browser is up-to-date or not?

How do you find the extensions page? Or is it add-ons? Depends, I guess.

How do I figure out which tab of (potentially) hundreds is consuming CPU and memory?

I won't claim that CLIs are better, but GUIs are definitely not made for discoverability these days.

[Tagbert]

I blame Chrome pissing on the menus for how hidden most functions are. Once they hid the menus, the others fell in line.

[millimeterman]

Counterpoint: the vast, vast majority of users never do any of that. I’m sure Google collects tons of analytics on how people use Chrome and the current design is tailored to fit the needs of the majority. Common functions like tabs, the address bar, and maybe bookmarks are front and center while everything is shoved into menus to declutter the top-level UI.

[Austin_Conlon]

Why past tense for guidelines from Apple? They're here: https://developer.apple.com/design/human-interface-guideline....

[lokedhs]

They may still be published, but GUI guidelines are generally not followed anymore. The rise of Electron applications is just one reason why this happened.

[bulletsvshumans]

In some ways CLIs are great for discoverability, because they force everything into the familiar "list of commands" paradigm. GUIs can be either much better or much worse for discoverability, because the layout techniques that let GUIs surface important or contextually relevant functions are the same techniques that let GUIs hide the function you need behind six layers of B.S.

See this article (full disclosure: written by me) that talks a bit more about some of the tradeoffs between CLIs and GUIs from a UX perspective: https://medium.com/design-ibm/real-developers-dont-use-uis-d...

There's also this interesting project that attempts to bring some of the discoverability and other benefits of graphical UIs to CLIs: https://github.com/IBM/kui . Would love to see more work in this area.

[ketzo]

GUIs can be a nightmare. They can also be a way to digest all the tools at your disposal without ever going to a help page. I think there’s definitely a lot to be said for that, particularly for people less used to a command line environment (and I don’t mean my dad trying to play Tetris, I mean a second-year CS student who is still getting used to Terminal).

[viraptor]

> both --help (...) and man are 1 level deep and show you the entire ui, all at once

Have you seen git's help/man? That's at minimum 2 levels deep.

[imtringued]

Yes and that is much better than a one level deep manual.

[ben509]

Don't forget "whatis" as your standard third entry point on Unix.

macOS does have a standard Help menu, and you can even live search from within it; it'll find a command within the menus and show you where it is, even if it's deeply nested. Or it will search through help topics if the application provides them.

> And context sensitive so it may not even be possible to see actions until certain condition is met.

That's gotten worse as developers have jammed more and more features into applications, to where they can't lay out their commands in the traditional menus.

We somewhat dodged a bullet in this regard. Apple and Microsoft both did experiments in component software back in the '90s, with Object Linking and Embedding on Windows and OpenDoc on the Mac.

They flopped for a variety of reasons, but one was the insane complexity of the UI: any object in a document was now potentially a mini application and had to negotiate control of the UI with other objects.

[morty_s]

Yes. This. Man And help pages are great (and grep-able, ripgrep-able ha).

No ads. No pay wall. Damn I love man pages.

[IanCal]

> all at once. That is definition of discoverable! One action, i've discovered everything.

We should make information more discoverable by putting libraries on a single scroll, then it's just one single page.

[ithkuil]

This! And also even once you find something in a GUI how do you record that and share to somebody else (including you in the future)? I had more success providing a non-technical person eith runbooks with shell commands to copy paste into a terminal to deal with common problems; we tried with GUIs but it was always very hard to work with over the phone (it was also long time ago, and in an airgapped env)

[downerending]

Not to mention that GUI designers have a penchant for moving things around in the interface on every release. So even if you knew where that thing was, you don't necessary know now. Consider Microsoft Office, for example. Ugh.

[frosted-flakes]

Microsoft Office has barely changed since Office 2007 and the introduction of the Ribbon. They screwed up the File menu by making it full-screen†, but apart from that I can't see anything to complain about.

† The original 2007 "Office" menu like in File Explorer or Paint is loads better.

[downerending]

It could be that the interface is so confusing and horrible that it only seems different each time I dig into it.

Each time I take a new job, I have to slog around in the config screens trying to figure out how to turn off all of Outlook's !@#$ing awful "corrections" that send my email in variable-width fonts and change my '--' strings into em dashes and so on, thereby destroying my emails to users. Every time I do this, it seems like the layout of this awful pile of config dialogs has rearranged itself. Is it just PTSD?

[frosted-flakes]

Yeah, well, Outlook is a different story. The Ribbon interface isn't really suited to a mail client, and Outlook has so much historical baggage that makes it ridiculously hard to use. I try my best to not use it, so I don't know how much it's changed.

But Word, PowerPoint, and to some extent, Excel? The Ribbon is really well thought-out and easy to use. It feels intuitive in a way that the old bloated menus never did. And the command search feature is actually really useful, and teaches you where a command is located so you can just go straight there next time.

[downerending]

This is hopelessly pedantic, but Outlook is (now) part of Microsoft Office. And matters to me the most since it's the only part of Office I hardly ever use.

[ses1984]

Maintaining backwards compatibility isn't a problem that's unique to GUIs.

[downerending]

At least in Unix/Linux, I doubt the reshuffling of command flags and arguments is more than one percent of what happens in GUI programs. And it's probably far less.

Command-line people take backward compatibility very seriously. GUI designers seem to think it doesn't matter, because oh, everything's so easy to find. Fie on that.

[kondu]

Yep. CLIs often also have a predictable interface. (Help is almost always -h or --help, version info is -v or --version, etc). On a GUI you'll have to play around a bit more and search for functionality.

[imtringued]

CLIs are not guaranteed to have a predictable interface at all. The flag prefix isn't standardized at all. On Windows you see the awkward / prefix. On Linux you will see a random mix between -- or - and the way values are specified is also random. Sometimes it is --flag value at other times it is --flag=value or just -f value or -f=value with no fully written out counterpart. If there was actually a standard that every CLI application followed (or the format was parsed by the shell instead and applications simply receive the parsed array of arguments) then you could make this argument. I would love it if this were true but that isn't the world we live in.

[frosted-flakes]

Half the time, -v seems to be a shortcut for --verbose. Or is it -V? Either way, it's not consistent or very predictable.

[ulisesrmzroche]

You call a flat list with a thousand items of tiny text discoverable?

It’s not.

[giovannibonetti]

Tab completion really helps with that

[c-smile]

> GUIs are a discoverability nightmare.

Which GUI?

[ken]

Every touch-based one, for starters. I don't know what I can tap, or what will happen if I tap them. Or long-tap, or double-tap, or lightly-tap. Or what the various swipe directions mean, or how swipe-from-edge differs, or the differences between a 1-, 2-, and 3-finger swipe. And nobody ever guessed how to "undo" on iOS without being told.

[mcqueenjordan]

I find CLIs to be more discoverable -- tab completion, help text, etc. represents a (relatively) standardized form of discovery. GUIs on the other hand may have cryptic icons, be arranged differently from each other, and have various hidden functionalities.

I'm not saying we can't make CLIs more discoverable, but I simply hold the opposite opinion: They already win out over GUIs on discoverability.

I think they lose out on /accessibility/ to most users, unfortunately.

[tfehring]

None of the features of CLIs that you described qualify as discoverability IMO. Tab completion, etc. only work if you know the name of the command that you need, and few to no CLI utilities or commands are named well.

Say you need to remove duplicates from a list, for example. If you happen to know that the utility to do that is called `uniq` then it's useful that you can use `man uniq` to see the available options, but if you don't already know the name of the utility you're looking for, you're stuck Googling for it. (The name `uniq` isn't obvious but at least it's intuitive. For the many commands that are neither obvious nor intuitive, good luck.)

Compare that to, say, Excel, where if you press Alt,A to bring up the Data tab there's a nice, big button labeled Remove Duplicates, with an M on it to indicate that the full keystroke sequence for that command is Alt,A,M (fewer keystrokes than ` | uniq` even with tab completion, for what that's worth). So in addition to accessibility, there's also discoverability.

[nerdponx]

is there a way to make CLI "more discoverable"

I've thought about this a lot. The answer, I think, is to have a "reverse index" of tasks that you can do with the tool and their corresponding commands or recipes.

For example, man pages are typically organized alphabetically by option or subcommand. I'm envisioning a section of documentation - maybe a separate man page or just something on a website - that looks like this (e.g. for rsync):

    I want to ...

      Transfer files within the local filesystem
          rsync dir1/ dir2
      Transfer files within the local filesystem & create a new directory
          rsync dir1 dir2         # Note the lack of trailing slash on dir1
      Preserve access times
          Use -t/--times
      Recurse into directories
          Use -r/--recursive
      < etc >

You can construct a lot of interesting recipes in this format. Rsync, Make, Find, Git, Docker, and many others all could benefit from this kind of treatment.

Such a document would be:

- Browsable and therefore discoverable

- Easy to search with plain text (can be optimized by making sure key words are inserted in the description text)

- A useful reference if you can't remember this or that specific incantation

[teyc]

Powershell has a common language, common help system, common logging framework. It's a very nicely done project.

You can

    Get-Help Update-ItemProperty -Example

to get some samples.

It is introspectable, so command line completion of argument parameters just work.

I even saw web based and windows based gui that can probe any powershell command and provide a rudimentary UI with field level help.

You can even find the relevant commands e.g.

    Get-Command -Noun PSDrive

gets you all the commands that can act on a PSDrive object.

[nerdponx]

This is really useful, thanks for that. Unfortunately I can't bring myself to use Powershell because of the sheer verbosity of the command line (might as well just use Python, in my opinion), but I really like a lot of their design choices.

[pritambaral]

Isn't that just the EXAMPLES section of a man page?

[sedatk]

Yes but not all CLI tools have it, or have it extensive enough.

[gindely]

But then the solution is just "better documentation". Every time the solution is just "don't suck", i think it's fair to say that the solution won't work.

For instance, in the past decade or so, the quality of guis have gone so far downhill, that is now commonplace for advanced users to have no idea that certain features exist because they're only exposed if you swipe like so and then tap this logo that doesn't look like a button. the technical knowledge exists for how to design usable graphical user interfaces, but "make better UIs" is not a high priority for businesses and the people they hire.

cli's have a certain advantage that many cli's are open source and technically not beholden to business interests (altho they may be defacto), and they're not fashionable amongst those for whom empowering users is a curseword, so "don't suck" is theoretically possible, but i don't know that it's particularly likely.

[nerdponx]

Sort of? Most "examples" are just scattershot random functionality that the author deemed important, with little consideration for actual use. GNU Parallel is a notable exception, albeit a somewhat disorganized one.

[whilenot-dev]

I use tldr[0] for that.

[0]: https://github.com/tldr-pages/tldr/

[zomglings]

Tab completion makes CLIs more discoverable.

It still places some responsibility on the developer of the command line tool to expose a reasonable interface. But if they do so, users can learn the interface by tab-ing their way to glory.

The Google Cloud SDK (gcloud command-line tool) is a really great example of this. It was the first cloud infrastructure I worked on and I learned how Google Cloud worked by tab-completing gcloud commands and reading the --help pages.

AWS CLI is an example of when too much complexity is exposed to the user. They have similar tab completion functionality, but they provide such fine grained control that it is hard to use it to learn the services themselves.

[slightwinder]

> Looking at Docker CLI, there are like a bazillion commands and it takes forever to read through the docs to find out what exactly to use.

Is this really a problem of CLI or just an example of a complex application? If we take for example something like excel or photoshop, then you can't easily figure what to do, even if the doc is directly embedded inside the UI.

> Back to discoverability, is there a way to make CLI "more discoverable"? Reading the man page doesn't count.

Why? It's an additional step, but can count as basic knowledge, similar to how someone needs to know how a mouse works and what the buttons do, before they can start using a GUI.

> Like can we combine the advantages of CLI with the discoverability of GUIs?

No, the moment you embedd the discoverabilty of GUI it stops being a CLI. TUI exist, and they do offer the same elements as GUI, just with less flexibility because text and so. But TUI serves a different purpose. You can't automate spatial interfaces as you can automate a cli. You need a dedicated way for allowing this, which is the main reason why CLI is so popular.

What you could do is defining many many APIs and protocols and guidelines, then define your interface in some generic way which allows you to automatic spin out a discoverable interface as also a useful automation-interface. But who wants that? That is extra work.

[jakear]

The hundreds of millions of people that use excel with limited to no training would likely beg to differ with the proposition that it isn’t discoverable. I’ve never taken an excel class or read basic excel docs, yet I know how to do basic excel things. That’s literally impossible in a CLI.

Similarly, how many people have trouble saving and quitting a word document? What about vim?

[gindely]

I have trouble saving a word document nowadays, since they close the document when you want to save or print. (You press file, and now the document has been closed and replaced by some menu. I do not know if my actions will apply to the document that I had had open before the program helpfully closed it and makes me feel very uncertain. I do not like to use Word for this reason. It is completely unfathomable to me why of all menus, the File menu is the menu that closes your document. I thought it should be the one to help you interact with it most.)

[frosted-flakes]

The File menu doesn't close the document, it just covers it. That's why it's terrible, and I don't know why they ever introduced it when Word 2007 already had a perfect solution. Word 2007 had a small menu exactly like File Explorer and Paint that was actually usable and didn't change the context.

[slightwinder]

So the first app you ever used in your life was excel and nobody ever explained you it's purpose? How did you ever learn how the mouse works?

[Firadeoclus]

> No, the moment you embedd the discoverabilty of GUI it stops being a CLI. TUI exist, and they do offer the same elements as GUI, just with less flexibility because text and so. But TUI serves a different purpose. You can't automate spatial interfaces as you can automate a cli. You need a dedicated way for allowing this, which is the main reason why CLI is so popular.

A command line interface can do with very little screen real estate. There's no reason GUI and command line can't coexist, with everything you do in the GUI immediately being reflected in the command line, and vice versa. This combines the context visibility and flexibility of a GUI with automatability and composability of a CLI. And you learn both at the same time.

[funcDropShadow]

> No, the moment you embedd the discoverabilty of GUI it stops being a CLI.

That statement is falsified by the advent of programmable completions. Nothing stops us from integrating context sensitive help into the shell completion mechanism. The shell could display a help text next to each item of a completion list, or you could press keyboard shortcut to get help to the command your cursor is positioned on. shellcheck could highlight a bash command while you are typing it. All that would not change the fact that a shell is a CLI.

[slightwinder]

Completions are very limited in their surface. And you still need to learn where to start to get the completion.

[dcminter]

The VMS operating system had a standardized command line help UX. Typing HELP gave you an overview of commands available (Curses style) and you could drill down into more specific commands from that.

If you knew the command but not the flags then you could add the HELP flag to get more and more specific information.

See page 1-18 and 1-19 of the user guide: https://www.isis.stfc.ac.uk/Pages/vms-user-manual.pdf

We had a VMS cluster at college and I found it to be a very nice approach. Quite a bit better than man pages and a lot more consistent in my opinion.

Some of them had easter eggs tucked away in them of course, such as the Datatrieve Wombat: https://www.ibphoenix.com/resources/documents/history/doc_29...

[doctor_eval]

ISTM that Curses style applications are not really CLIs, but GUIs implemented using character cells instead of pixels.

In a sense, the help pages are a super-thin GUI on top of the underlying CLI.

[downerending]

On the one hand, I recall that fondly. On the other hand, a modern Linux box might have thousands of commands, and I'm not sure that VMS HELP could handle that well.

[a1369209993]

It sounds almost exactly like the unix (1)man command actually, and, well:

  $ ls /usr/share/man/man1/ | wc -l
  2997

I'd say that qualifies as thousands (plural).

[downerending]

The difference, as I recall it (and it's been decades), is that VMS HELP tries to display all of the commands in a curses-like screen. That kind of works for a few hundred commands, but not thereafter.

Unix has things like 'man -k', but those ultimately output into a pager, which is well-designed to deal with quite long lists.

I do miss HELP and EDT, but they're hopelessly outmatched by modern tools.

[a1369209993]

> VMS HELP tries to display all of the commands in a curses-like screen. That kind of works for a few hundred commands, but not thereafter.

Ah, yes, point. I was more pointing out that it's possible to "handle that well" (or at least not terribly; unix is like democracy), rather than any disagreement over how well HELP itself handled it in practice.

[jsrcout]

And VMS' printed documentation was fantastic. You could practically learn C by reading the compiler doc. It really went above and beyond.

[wodenokoto]

I think autocomplete and sub commands can help a lot with discoverability.

I don't want to praise the Google Cloud CLI, but one nice thing is you can do something along the lines of

    $ gcloud <tab>
    -> list of services you want to manipulate
    $ gcloud servicename <tab>
    -> list of action you can do to service
    $ gcloud servicename actionname --help
    --> detailed information on how to apply that action

It isn't perfect - you don't get this behaviour out-of-the-box with every shell - but it is a lot better than reading a man page with a list of a million flags.

[closeparen]

Tab completion and fuzzy finding are at least pointed in the right direction. Subcommand structure is also relatively easier to discover: you can walk the tree and see what the other options are at each node. Much more discoverable than having a lot of top-level flags.

Finally, I think the architecture of man pages is all wrong: examples should always be primary, exhaustive descriptions of every little option are reference material and a last resort.

[ashton314]

tldr [0] fills the missing piece you mention: good examples of common actions. (Though I use the Rust implementation tealdeer [1])

[0]: https://github.com/tldr-pages/tldr [1]: https://github.com/dbrgn/tealdeer

[wnevets]

My patience is so bad when it comes to cli discoverability I just skip to googling what I want to do.

[funcDropShadow]

Without patience you can master nothing. I hope you are fine with that.

[imtringued]

Half the battle is knowing whether something exists or is possible.

[wnevets]

for most cli, I am.

[nucleardog]

> is there a way to make CLI "more discoverable"?

The first time I used Cisco’s IOS was pretty eye-opening to me, and I was thoroughly confused why something like that wasn’t present everywhere. (The only other place I’ve seen it is in MikroTik’s CLI.)

For those not familiar, at any point anywhere you can simply type a question mark and it will tell you all the valid inputs (commands, arguments, etc) at the exact spot your cursor is at and then put you right back where you were ready to continue typing.

You could discover a lot — not only what you were searching for, but related functionality — just by throwing a ‘?’ at it whenever you didn’t know what to type next.

Of course it helped that everything was named in a very straightforward manner. Something like this is never going to help you to discover a new Unix command because many are “cleverly” named. But once you find one you’ll be able to use it without ever referencing a manual page.

[Someone]

MPW Commando still hasn’t been beaten, IMO. See my earlier comment at https://news.ycombinator.com/item?id=22499855

It may not scale to meta commands such as docker and terraform, though.

You’ll also need something to figure out which commands might help you do whatever you want to do. Apropos and locate help a bit there, but IMO need improvement.

https://pypi.org/project/howdoi/ is an attempt at that. I’ve never used it, so I don’t know how good it is.

In some sense, I guess stackoverflow is the best we have to make the CLI more discoverable.

[jsrcout]

Commando - now that was a fantastic tool. Thanks for reminding me.

[hinkley]

We like to talk about 'organic' in tech but to farmers that meant "pig shit" up until a few decades ago.

The Docker and Git CLI both grew organically. Each new feature had to fit into the gaps between the old features without reusing the same terminology, and sometimes the easiest spot to implement something is not the spot you would first guess it should be. So it gets tacked on somewhere else to avoid coupling.

Rewriting an interface is difficult, and some people do it too often ('upgrade treadmills') or try to avoid doing it at all.

[raspyberr]

People who are less confident with technology almost never try out things in GUIs in case they break. Those more confident tend to click on things just to see what they do. If a CLI user knows that they can type "--help" at the end of a command to start learning what it can do, I think that's a lot more "discoverable" than GUIs for less confident people.

Although what situation are you in where a not-confident person is even using a CLI?

[enitihas]

There can be an option --interactive. So if you type "ls --interactive", you get a fuzzy search prompt, where you can enter free form text, which can be matched against the main page description of each option, and the options can be surfaces in a scored manner. This will be similar to the search bar under the help menu in macos, which is something I use a lot to find out location of options. Might work for a lot of apps.

[trasz]

This probably won't work with Unix shell, but some CLIs (JunOS comes to mind) have a context help that's shown when you press "?". But note it's not "?<CR>", you don't need to press enter; merely inputting a single "?" character shows possible things you can append to the command line at that point.

[a1369209993]

That's not a CLI, that's a TUI. Eg, Dwarf Fortress does this.

[trasz]

How it’s not a CLI? There is a command line, you type in commands.

[a1369209993]

> But note it's not "?<CR>", you don't need to press enter

"Responds to individual keypresses" vs "responds to complete lines" is pretty much the defining feature of TUI vs CLI.

> you type in commands.

KEY_SLASH+MOD_SHIFT is a UI event, not a command.

[trasz]

If that were true, bash wouldn’t be a CLI, due to <TAB>.

What I’m describing is definitely a CLI. You type in commands, such as “show version”. It’s just a bit smarter about command completion and context help.

[Cthulhu_]

+1 on the thing with Docker, all I want is a "start" command to go through that dockerfile I just wrote (also with some effort). At the moment it feels like I have to build it, then build it again but with a tag or name, then look up that same tag or name again and find the right command to actually run a container, oh and then there's a bunch of old versions of that container still taking up space but if you don't actually google for "how to clean up old docker containers" you'd have no clue how to find them.

Is there a docker frontend for idiots like me somewhere?

[inetknght]

> The biggest problem with CLI is discoverability

I don't agree. Discoverability's a big problem with "modern" GUIs too.

> is there a way to make CLI "more discoverable"? Reading the man page doesn't count

Why doesn't reading the man page count? I've learned a hell of a lot more about CLI tools by reading their manual than I have by ... oh wait GUIs often don't come with a manual.

[funcDropShadow]

>> The biggest problem with CLI is discoverability

> I don't agree. Discoverability's a big problem with "modern" GUIs too.

Absolutely, nowadays you have to discover which part of the screen is clickable, you have to discover where they hid that stupid hamburger menu. The menus of the mac and Amiga were so, you could find them blindly with your mouse. On endless scrolling pages you often cannot skip ahead you have to scroll and wait, scroll and wait, scroll and wait, until the browser hangs.

[FroshKiller]

Personally, I feel like verb-based CLIs get, like, four verbs max. I don't like Swiss Army knives. Do one thing, and do it well.

[uhoh-itsmaciek]

Maybe any CLI that's complex enough to have subcommands should have an "apropos" [1] subcommand to help with discoverability...

[1]: https://www.man7.org/linux/man-pages/man1/apropos.1.html

[bch]

> The biggest problem with CLI is discoverability [...] there are like a bazillion commands and it takes forever to read through the docs...

I think that’s a design issue - what GUI element (menus, buttons, ...) is going to solve this in a way that couldn’t also be applied to the CLI?

[funcDropShadow]

docker is an especially bad case of CLI UI. 1. Details of parameters changed quite often in the early times of docker. 2. Docker does not provide man pages, just a very terse --help output. 3. The --help output is often similar to the provierbial Javadoc comment of a Java getter, i.e. it is just a repetition of the parts of the name in different order with more noise. It usually doesn't answer any important questions about the tool. Just look at these:

      --dns list                       Set custom DNS servers
      --dns-option list                Set DNS options
      --dns-search list                Set custom DNS search domains
      --domainname string              Container NIS domain name
      --entrypoint string              Overwrite the default ENTRYPOINT of the image
  -e, --env list                       Set environment variables
      --env-file list                  Read in a file of environment variables
      --expose list                    Expose a port or a range of ports

None of these comments clarify the syntax or precise meaning of the parameters to the flags. Does it mention you can map internal to external ports with --expose? No, it doesn't but it would be really helpful to be able to look up the syntax.

You claimed man pages do not help. I disagree. To me man pages have the following advantages over web based documentation.

- A locally installed man page usually matches the version of the installed tool.

- I don't have to search for the correct web page or even software project that is the source of an installed program.

- It works offline.

- No SPA bullshit (hello docker and kafka) in documentation that slows down browsing, adds time wasting scroll animations, and often breaks navigation (Implementing the back and forward button in a SPA is not helpful if you loose your scroll state when navigating)

- Sometimes you have to use older software, i.e. because you want to recompile your college project with a matching compiler. Then it is really useful to have the documentation matching to your tools. Or you maintain certified firmwares, which were released and certified some years ago, then you have to use that software.

I am sure you are aware of the advantages of Web based documentation so I skip them.

update: [typos and formatting]

[kitotik]

Really good autocompletion replete with helper/explanatory text can help a lot with CLI discoverability.

[SomeoneFromCA]

You may find "fish" shell interesting.

[prima-facie]

There are a few things you can do.

1. Get a better shell with good auto-completion. I find bash to be lacking in this regard. I use fish but others like zsh.

2. Use a helper command like `tldr`[1]. It's not perfect and certainly not a replacement for a proper manual page, but it helps when in the middle of work.

[1]: https://github.com/tldr-pages/tldr-python-client

[xerxesaa]

I personally like using the "tldr" command line tool. It gives a short overview of the most common commands.

https://github.com/tldr-pages/tldr/

[sadfklsjlkjwt]

Tab completion on small commands that don't have a kitchen sink of options...

I've never read the manual for the GCP command line tools but I've used them extensively.