explainshell
match command-line arguments to their help text
A Python web app that breaks apart any shell command and shows you what each flag and argument does, pulling the explanation directly from the relevant Linux manual page.
explainshell is a Python-based web tool that takes a shell command and explains what each part of it does. If you paste in something like tar -xzvf archive.tar.gz, it breaks the command apart and shows you the relevant help text for each flag, pulled from the manual page for that command. The goal is to make terminal commands readable for someone who does not have every option memorized.
The tool works by keeping a local database of processed Linux manual pages. Each manual page is analyzed to extract the list of options it documents and their descriptions. When you submit a command, explainshell parses it into a syntax tree using a library called bashlex, then walks through each node in that tree, matching commands and flags to stored descriptions. The results are rendered in a web interface built with Flask.
Building the database is a separate offline step. You can either download a prebuilt copy or process man pages yourself using a command-line manager tool. The extractor supports two methods: parsing the raw formatting macros in the man page directly, or calling an LLM (such as a GPT model via the OpenAI API) that reads the page as markdown and identifies which line ranges correspond to which options. The LLM approach does not write new descriptions; it only picks out slices of the original text, so the explanations always come from the actual man page wording, not generated content.
The SQLite database uses three tables: one for the raw compressed man page source, one for extracted options and metadata, and one that maps command names to the right man page entry. A single man page can have multiple mappings when it covers several subcommands or aliases. The live database for the public site is published as a GitHub release so you can download it without re-running extraction.
You can run explainshell locally by cloning the repo, setting up a Python virtual environment, downloading the database, and starting the Flask server on port 5000. A test suite covers linting, unit tests, and end-to-end checks.
Where it fits
- Paste a complex tar, grep, or curl command into the web UI and instantly see what every flag does without reading the full man page.
- Run explainshell locally to explain shell commands using a prebuilt or self-built SQLite database of processed man pages.
- Use the LLM-powered extraction mode to build a man page database that accurately identifies which text describes which option.