[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/