9 ms·

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 re

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.

mcqueenjordan 6y ago
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 6y ago
  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.
enitihas 6y ago
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.
inetknght 6y ago
> 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 6y ago
  >> 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.
dcminter 6y ago
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 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_295 https://www.ibphoenix.com/resources/documents/history/doc_29...
- downerending 6y ago
  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 6y ago
    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 6y ago
      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 6y ago
        > 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.
raspyberr 6y ago
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?
kitotik 6y ago
Really good autocompletion replete with helper/explanatory text can help a lot with CLI discoverability.
- SomeoneFromCA 6y ago
  You may find "fish" shell interesting.
trasz 6y ago
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 6y ago
  That's not a CLI, that's a TUI. Eg, Dwarf Fortress does this.
  - trasz 6y ago
    How it’s not a CLI? There is a command line, you type in commands.
    - a1369209993 6y ago
      > 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 6y ago
        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.
hinkley 6y ago
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.
slightwinder 6y ago
> 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 6y ago
  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?
  - slightwinder 6y ago
    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?
  - gindely 6y ago
    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.)
uhoh-itsmaciek 6y ago
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 https://www.man7.org/linux/man-pages/man1/apropos.1.html
Someone 6y ago
MPW Commando still hasn’t been beaten, IMO. See my earlier comment at https://news.ycombinator.com/item?id=22499855 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/ 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 6y ago
  Commando - now that was a fantastic tool. Thanks for reminding me.
njharman 6y ago
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.
- deleted 6y ago
  [deleted]
- ithkuil 6y ago
  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)
- ketzo 6y ago
  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).
- downerending 6y ago
  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.
bch 6y ago
> 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?
closeparen 6y ago
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 6y ago
  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 https://github.com/tldr-pages/tldr [1]: https://github.com/dbrgn/tealdeer https://github.com/dbrgn/tealdeer
nerdponx 6y ago
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
- pritambaral 6y ago
  Isn't that just the EXAMPLES section of a man page?
  - sedatk 6y ago
    Yes but not all CLI tools have it, or have it extensive enough.
    - gindely 6y ago
      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.
wnevets 6y ago
My patience is so bad when it comes to cli discoverability I just skip to googling what I want to do.
- funcDropShadow 6y ago
  Without patience you can master nothing. I hope you are fine with that.
  - wnevets 6y ago
    for most cli, I am.
  - imtringued 6y ago
    Half the battle is knowing whether something exists or is possible.
funcDropShadow 6y ago
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]
FroshKiller 6y ago
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.
zomglings 6y ago
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.
nucleardog 6y ago
> 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.
sadfklsjlkjwt 6y ago
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.
wooptoo 6y ago
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 https://github.com/tldr-pages/tldr-python-client
Cthulhu_ 6y ago
+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?
wodenokoto 6y ago
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.
deleted 6y ago
[deleted]
xerxesaa 6y ago
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/ https://github.com/tldr-pages/tldr/

mcqueenjordan 6y ago

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 6y ago
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.

enitihas 6y ago

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.

inetknght 6y ago

> 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 6y ago
>> 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.

dcminter 6y ago

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 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_295 https://www.ibphoenix.com/resources/documents/history/doc_29...

downerending 6y ago
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 6y ago
  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 6y ago
    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 6y ago
      > 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.

raspyberr 6y ago

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?

kitotik 6y ago

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

SomeoneFromCA 6y ago
You may find "fish" shell interesting.

trasz 6y ago

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 6y ago
That's not a CLI, that's a TUI. Eg, Dwarf Fortress does this.
- trasz 6y ago
  How it’s not a CLI? There is a command line, you type in commands.
  - a1369209993 6y ago
    > 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 6y ago
      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.

hinkley 6y ago

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.

slightwinder 6y ago

> 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 6y ago
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?
- slightwinder 6y ago
  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?
- gindely 6y ago
  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.)

uhoh-itsmaciek 6y ago

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 https://www.man7.org/linux/man-pages/man1/apropos.1.html

Someone 6y ago

MPW Commando still hasn’t been beaten, IMO. See my earlier comment at https://news.ycombinator.com/item?id=22499855 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/ 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 6y ago
Commando - now that was a fantastic tool. Thanks for reminding me.

njharman 6y ago

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.

deleted 6y ago
[deleted]
ithkuil 6y ago
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)
ketzo 6y ago
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).
downerending 6y ago
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.

bch 6y ago

> 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?

closeparen 6y ago

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 6y ago
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 https://github.com/tldr-pages/tldr [1]: https://github.com/dbrgn/tealdeer https://github.com/dbrgn/tealdeer

nerdponx 6y ago

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

pritambaral 6y ago
Isn't that just the EXAMPLES section of a man page?
- sedatk 6y ago
  Yes but not all CLI tools have it, or have it extensive enough.
  - gindely 6y ago
    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.

wnevets 6y ago

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

funcDropShadow 6y ago
Without patience you can master nothing. I hope you are fine with that.
- wnevets 6y ago
  for most cli, I am.
- imtringued 6y ago
  Half the battle is knowing whether something exists or is possible.

funcDropShadow 6y ago

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]

FroshKiller 6y ago

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.

zomglings 6y ago

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.

nucleardog 6y ago

> 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.

sadfklsjlkjwt 6y ago

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.

wooptoo 6y ago

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 https://github.com/tldr-pages/tldr-python-client

Cthulhu_ 6y ago

+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?

wodenokoto 6y ago

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.

deleted 6y ago

[deleted]

xerxesaa 6y ago

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/ https://github.com/tldr-pages/tldr/