Repolode
Submit
idank

idank/explainshell

A web tool and Python library that explains shell command lines by matching each argument to its manpage help text.

View on GitHub
Stars
14,297
Forks
854
Open issues
57
Last commit
2 months ago

What is it?

explainshell takes a shell command line such as a pipeline with flags and arguments, parses it into an AST with bashlex, and matches each token to the option descriptions extracted from the corresponding manpage. The result shows which part of the command does what, which is useful when reading unfamiliar one-liners.

The project parses manpages using roff macros or an LLM-based extractor that returns line ranges into the original source text, so the help text shown is sliced from the manpage rather than generated. Processed manpages are stored in a single SQLite database, and a Flask web interface renders the matches. It also handles shell operators such as pipes and && as separate nodes.

The repository includes a manager CLI for extracting, diffing and inspecting manpage data, plus evaluation harnesses for LLM extraction and mandoc markdown rendering. The live database is distributed through GitHub releases, and its content is subject to the upstream licenses of each manpage.

Key features

  • 01Matches each argument in a shell command to its option description from the manpage.
  • 02Parses command lines into an AST so pipes, && and other shell operators are handled.
  • 03Extracts options from roff macros or with an LLM that returns source line ranges.
  • 04Stores processed manpages in a single SQLite database with a web interface built on Flask.
  • 05Provides a CLI for extracting, diffing and querying manpage data.

Use cases

  • Understanding an unfamiliar one-liner or pipeline before running it.
  • Reviewing shell commands in scripts or documentation.
  • Building a self-hosted command reference backed by manpage data.
  • Evaluating or comparing LLM-based manpage option extraction.

Quick start

  1. 1

    Clone the repository

    git clone https://github.com/idank/explainshell.git
  2. 2

    Install Python dependencies (in a virtualenv, as the README describes)

    pip install -r requirements-dev.txt
  3. 3

    Download the live database

    make download-latest-db
  4. 4

    Run the web server, then open http://localhost:5000

    make serve

Things to know

  • Code is GPLv3-licensed, so derivative distributions must also be GPLv3.
  • The released database contains upstream man pages under their own licenses, so redistributing it requires your own license compliance review.
  • Extracting new manpages requires access to an LLM provider such as Codex or an OpenAI API key.

Topics

#shell#manpage#command-line#bash#sqlite#flask#llm#cli

FAQ

What is explainshell?
A web tool and Python library that explains shell command lines by matching each argument to its manpage help text. explainshell takes a shell command line such as a pipeline with flags and arguments, parses it into an AST with bashlex, and matches each token to the option descriptions extracted from the corresponding manpage. The result shows which part of the command does what, which is useful when reading unfamiliar one-liners.
Is explainshell free to use? What license does it have?
explainshell is open source under the GPL-3.0 license. Check the license terms before using it in commercial products.
Is explainshell still maintained?
Updated within 6 months. The last commit to explainshell was on Aug 26, 2026.
What can I use explainshell for?
Understanding an unfamiliar one-liner or pipeline before running it. Reviewing shell commands in scripts or documentation. Building a self-hosted command reference backed by manpage data. Evaluating or comparing LLM-based manpage option extraction.
How do I install explainshell?
Clone the repository: git clone https://github.com/idank/explainshell.git Install Python dependencies (in a virtualenv, as the README describes): pip install -r requirements-dev.txt Download the live database: make download-latest-db Run the web server, then open http://localhost:5000: make serve
Where can I get explainshell?
The source code and installation instructions are on GitHub: https://github.com/idank/explainshell

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects