explainshell

# [explainshell.com](http://www.explainshell.com) - match command-line arguments to their help text

[![CI](https://github.com/idank/explainshell/actions/workflows/ci.yml/badge.svg)](https://github.com/idank/explainshell/actions/workflows/ci.yml)
[![Deploy](https://img.shields.io/github/actions/workflow/status/idank/explainshell/do-deploy.yml?label=deploy&logo=digitalocean&logoColor=white)](https://github.com/idank/explainshell/actions/workflows/do-deploy.yml)

explainshell is a tool (with a web interface) capable of parsing manpages, extracting options and
explaining a given command-line by matching each argument to the relevant help text in the manpage.

## How?

explainshell is built from the following components:

1. manpage reader which extracts metadata (name, synopsis, aliases) from a given manpage (manpage.py)
2. an options extractor that parses roff macros or uses an LLM to extract options (extraction/)
3. a storage backend that saves processed manpages to sqlite (store.py)
4. a matcher that walks the command's AST (parsed by [bashlex](https://github.com/idank/bashlex)) and contextually
   matches each node to the relevant help text (matcher.py)

When querying explainshell, it:

1. parses the query into an AST
2. visits interesting nodes in the AST, such as:
   - command nodes - these nodes represent a simple command
   - shell related nodes - these nodes represent something the shell
     interprets such as '|', '&&'
3. for every command node we check if we know how to explain the current program,
   and then go through the rest of the tokens, trying to match each one to the
   list of known options
4. returns a list of matches that are rendered with Flask

## Running explainshell locally

```bash
# Clone repository
$ git clone https://github.com/idank/explainshell.git
$ cd explainshell

# Set up Python virtualenv
$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install -r requirements-dev.txt

# Download the live db
$ make download-latest-db

# Or parse a manpage
$ python -m explainshell.manager extract --mode llm:codex/gpt-5.6-sol/medium manpages/ubuntu/26.04/1/tar.1.gz

# Run the web server
$ make serve
# open http://localhost:5000
```

## Storage

Processed manpages live in a single SQLite database (`explainshell.db`) with three tables:

- **manpages**: zlib-compressed manpage source text (typically markdown produced by `mandoc -T markdown`). Keyed by a `source` path in the format `distro/release/section/name.section.gz` (e.g. `ubuntu/26.04/1/tar.1.gz`).
- **parsed_manpages**: extracted options, synopsis, aliases, and behavioral flags for each manpage. Options are stored as a JSON list.
- **mappings**: maps command names to `parsed_manpages` rows (many-to-one, with a score for preference). A single manpage can have multiple mappings - one per alias and one per sub-command form (e.g. `git commit` maps to the `git-commit` manpage).

The `source` path is the primary key across both `manpages` and `parsed_manpages`, and doubles