
Explain Shell: match command-line arguments to their help text - ColinWright
https://explainshell.com/
======
arendtio
I am not sure how much I will use it, but the tar example will probably become
one of my all time favorites ;-)

[https://explainshell.com/explain?cmd=tar%20xzvf%20archive.ta...](https://explainshell.com/explain?cmd=tar%20xzvf%20archive.tar.gz)

~~~
nemosaltat
In my head I always say “eXtract Zee Files..” I think I read it on a message
board years ago and it stuck.

------
netsharc
I clicked the "tar zcf" example, IMO it's not an explanation that a newbie
would understand, the command is pretty "advanced". But well, it's a useful
replacement to man tar and trying to search "-z", "-c" and "-f".

A cool next step would be to make this a cli, where you type e.g. explainshell
"command" and get this info as a textual output...

~~~
exclipy
It'd be even cooler if you didn't have to type a command and could just hover
over the parts of the command in your terminal to get the relevant docs as
tooltips.

------
etaioinshrdlu
I find this super impressive! It parses man pages into structured data. I
imagine it could also be used on "\--help" output.

I wonder if one could automatically construct GUI's for users based on the
structured data generated. That may make command lines be more discoverable
and have an easier learning curve for new users.

~~~
codetrotter
If you consider pursuing that idea, I highly recommend you check out the
OpenBSD mdoc format.

> mdoc — semantic markup language for formatting manual pages

> The mdoc language supports authoring of manual pages for the man(1) utility
> by allowing semantic annotations of words, phrases, page sections and
> complete manual pages. Such annotations are used by formatting tools to
> achieve a uniform presentation across all manuals written in mdoc, and to
> support hyperlinking if supported by the output medium.

[https://man.openbsd.org/mdoc.7](https://man.openbsd.org/mdoc.7)

Given that OpenBSD is using this language for their manual pages, you would
have a pretty good starting point I think.

The program they wrote for that is called mandoc. From Wikipedia:

> Development began in November 2008 specifically to produce CSS-enabled HTML
> forms of manuals in response to the limitations of groff. [...] mandoc
> became the default formatter of manuals for OpenBSD 4.8, released in
> November 2010. It later became the default formatter in NetBSD, FreeBSD,
> illumos, Void Linux and Alpine Linux, and is also included in DragonFlyBSD,
> MINIX 3, Debian, Ubuntu, Gentoo, and Fedora.

[https://en.wikipedia.org/wiki/Mandoc](https://en.wikipedia.org/wiki/Mandoc)

All of that being said, I think fundamentally that the way of organization
flags and options for command line utilities are quite different from what
you’d typically want in a GUI program.

I use the command line a lot, but mostly you learn a few flags and options
that are useful to you, and for the ones you use more rarely you look it up in
the man page or on the web.

For example, the most obvious way to do what you are talking about would be to
like have the GUI show basically all of the options and flags and arguments
from the man page in one huge form. But that would also be going about it the
wrong way IMO. You end up with using a lot of screen real estate but with a
lot of the information that is shown on screen being irrelevant for day to day
tasks.

If there was a GUI for the command line, one way that I think has potential
but which I have not had time to create yet (hopefully I have a lot of years
left of my life though so I wish to make it one day), is to make it node
based. Like visually it would be like the Blender Node Editor, Unreal
Blueprints, Nuke nodes etc

[https://docs.blender.org/manual/en/2.79/render/blender_rende...](https://docs.blender.org/manual/en/2.79/render/blender_render/materials/nodes/introduction.html)

[https://docs.unrealengine.com/en-
US/Engine/Blueprints/Gettin...](https://docs.unrealengine.com/en-
US/Engine/Blueprints/GettingStarted/index.html)

[https://learn.foundry.com/nuke/content/getting_started/using...](https://learn.foundry.com/nuke/content/getting_started/using_interface/working_nodes.html)

And to make it a fast and efficient thing to use you’d construct reusable
primitives that work like command line utilities but which have their options
set already.

So for example, say I want to run the equivalent of:

    
    
      tar cf - CoolProject/ | pv | ssh workhorse 'cd /var/Projects/2020/ && tar xvf -'
    

The wrong way IMO would be for the user to have to create the whole pipeline
in the GUI each time.

Instead you’d have one or more node primitives that were wrapping one or more
command line utilities (or reimplementing their functionality, or using
underlying libraries, whichever is more convenient and suitable for each
individual node).

Now, how these nodes look and how you form primitives come down to how you
think about a task.

For example, one person might find a single node representation most suitable
for the above given example, where the node is named “Send directory to
workstation”, and it takes as input the local and remote paths as well as the
network name of the remote host.

Or you might imagine that to someone else they would want a two-node setup,
with one node internally calling to _tar cf -_ and the other to the ssh
command above, each of the two nodes taking respective inputs.

And inputs and outputs would be statically typed.

But there is a reason perhaps that I have not gotten around to this yet. Well
two reasons.

One is that it would be time consuming to implement all of that.

The other being that the command line works pretty damn well, all of it’s
warts in spite.

But I definitely think there is room for doing something really nice about the
command line, with a visual workflow, either with nodes like mentioned or with
something else.

Also, in my system the nodes would have the possibility of caching outputs in
them, so that you can tweak a pipeline without having to re-execute the
pipeline as a whole where that is desirable.

------
gigatexal
This is a super handy website, kudos to the hackers that created this.

------
Wowfunhappy
I use this all the time!

I don’t know if it’s feasible at all, but one thing I would love is a version
of this that uses the man pages of alternate Unix OS’s, such as BSD/Darwin.

~~~
skytreader
There's a small dropdown at the left of each command to toggle between
different man page versions. Unfortunately no BSD/Darwin though (at least for
the command I've tried).

------
logicuce
This looks nice. Folks interested in this might also like
[https://tldr.sh](https://tldr.sh). It gives a tldr version of man pages for
popular commands on command line.

