explainshell is a command-line documentation tool that parses manpages and matches shell arguments to their help text.
The tool solves the problem of understanding what each flag and argument in a complex command does by extracting structured option data from manpages and then contextually matching tokens in a user-supplied command line to that documentation. It parses the input command into an abstract syntax tree using bashlex, walks through interesting nodes like command invocations and shell operators, and attempts to match each token against known options for the relevant program. The results are rendered with Flask, either through a web interface or for local use.
The tool suits developers and system administrators who frequently work with complex command-line tools and want quick inline explanations without manually consulting manpages. It works best for programs with well-structured manpages that follow standard conventions. The project includes a web service at explainshell.com, but can also be run locally. Local operation requires building a SQLite database from manpage archives; the project sources manpages from Ubuntu archives and manned.org, with all sources committed as a git submodule. The extraction pipeline supports multiple strategies: parsing roff macros directly or delegating to an LLM, which returns line ranges into the original text rather than generated descriptions, preventing hallucinations.
Development activity shows consistent maintenance with regular updates to the codebase. The project actively incorporates improvements to its extraction pipeline, including support for LLM-based option extraction as an alternative to roff parsing. The tool maintains a live database distributed through GitHub releases, indicating ongoing operational commitment to the web service. The architecture has evolved to support multiple manpage sources and distro versions through a namespace-based storage scheme, suggesting the maintainers are expanding coverage and flexibility.
