2026 · web service + CLI
why
paste in a shell command, get a plain-English explanation of what it does.
why
most "explain this command" tools forward your command to an LLM and hope for the best. that works, but it's non-deterministic: the same command can get different, sometimes wrong, explanations, and there's no record of why a flag was called dangerous. why splits the problem so the facts and the phrasing come from different places.
the problem
an LLM asked "what does --hard mean" has to guess from training data, and guesses vary. but the meaning of --hard isn't a matter of opinion: it's documented behavior that can live in a knowledge base. the problem was architectural, not model-shaped: stop asking the LLM for facts, and start asking it only to phrase facts you already verified.
architecture
two layers. a deterministic, rules-based parser breaks the command into a structured object, tool, subcommand, flags with meanings, args, and effects, from YAML knowledge files. no AI involved: same input, same output, always. then an LLM takes that structured breakdown and turns it into plain English. if the LLM is unreachable, the endpoint still returns the structured breakdown with the explanation left null.
POST /api/explain
{ "command": "git reset --hard HEAD~1" }
→ { command, explanation,
explanationError, confidence }
/* confidence: "verified" (matched the
knowledge base) or "inferred" (best-
effort LLM guess, clearly caveated) */a Spring Boot backend owns the knowledge base and the explanation service, with a Node CLI and a React single-page frontend as thin clients over the same endpoint.
what i learned
the separation holds up beyond this project: whenever an LLM sits in a pipeline, decide explicitly which parts are allowed to be probabilistic and which must be exact, then enforce the boundary in code. graceful degradation falls out naturally once the deterministic layer can stand alone: the tool is still useful with no API key, it just explains less prettily.
what broke
effects used to include every effect for a subcommand, so git reset --soft showed a discards-changes effect that belonged to --hard. the fix was scoping effects to the subcommand's baseline plus only the effects tied to flags actually passed. a good reminder that a knowledge base has the same bug surface as any other data model.
what's next
more tools in the knowledge base, streaming explanations, and per-effect risk scores, so "this flag is dangerous" comes with a number attached.
all projects