Think outside the box

explainshell – match command-line arguments to their help text

A Linux system comes with a whole collection of system reference manuals (known as man pages). There’s a man page for each command or program.

The system’s man pages contain a wealth of useful information. But sometimes it’s hard to see the wood for the trees. Even experienced users can be bamboozled by the sheer complexity of some man pages. Many tools have been in development for decades and have, over time, had feature upon feature added.

explainshell is a tool (with a web interface) which parses man pages, extracts options and explains a given command-line by matching each argument to the relevant help text in the man page. It stores processed man pages in a document-oriented database.


To run explainshell locally, it’s best to use Docker, a set of platform as a service (PaaS) products that use OS-level virtualization to deliver software in packages called containers.

The system we tested explainshell is running Ubuntu 23.10 which didn’t have Docker running. Let’s install that first.

$ sudo apt install docker-compose

Besides installing Docker, the command automatically creates a docker group in Ubuntu.

When you install Docker, the docker command must be run with the security privileges of root (using sudo) or by a user in the docker group.

As you can see, the user sde is a member of the sudo group but not the docker group.

We use the usermod command to add our username to the docker group, and activate the change with newgrp. Re-running the id command shows sde is now a member of the docker group.

We’ll use curl to download the database dump to /tmp/ as it doesn’t need to be permanently saved. It’s a small download (approximately 70MB).

$ curl -L -o /tmp/dump.gz

Clone the project’s repository:

$ git clone

Change into the newly created directory:

$ cd explainshell

Now we can build the containers:

$ docker-compose build

Start them:

$ docker-compose up

Running locally on port 5000

We’re now running explainshell locally on port 5000.

The final step is to load the man pages.

$ docker-compose exec -T db mongorestore --archive --gzip < /tmp/dump.gz

Next page: Page 2 – In Operation and Summary

Pages in this article:
Page 1 – Introduction and Installation
Page 2 – In Operation and Summary

Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments