man tells you about one command. --help tells you about one invocation. Neither explores a tool you don't already know.
$ mandible docker
A tree of every command, subcommand and flag on the left. The selected one's documentation on the right.
Tip
Try running mandible mandible
Linux and macOS, on both x86_64 and arm64. Windows is not supported. The process
containment described above relies on POSIX process groups, and native Windows tools
use conventions (/?, PowerShell's own help system) that this project does not yet
speak.
| Platform | Download |
|---|---|
| Linux x86_64 | tar.gz |
| Linux arm64 | tar.gz |
| macOS Apple Silicon | tar.gz |
| macOS Intel | tar.gz |
.deb and .rpm packages are attached to every release.
Each archive ships a matching .sha256 checksum.
cargo install mandibleThere is no per-tool logic anywhere in this project. No if tool == "docker", no
vendored catalogue of hand-written definitions. That approach is convenient for a
week and unmaintainable ever after. It is always slightly out of date, and it is
wrong in ways you cannot see from the outside.
The insight it runs on instead: help text isn't written by hand, it's generated, and only a small closed set of generators exists. mandible works out which framework produced a tool's output, then applies that framework's grammar. For example:
| Rust | clap (v2, v3/v4) |
| Go | cobra, urfave/cli, stdlib flag |
| Python | argparse, click, docopt |
| JavaScript | commander, yargs, oclif |
| Java / .NET | picocli, System.CommandLine |
| Others | GNU argp/getopt_long, busybox, Symfony Console, OptionParser/Thor, BSD-terse |
Tip
You can also try to probe executable files: mandible scripts/custom.py
That claim is measured, not asserted. cargo xtask coverage runs the pipeline against
every executable on your PATH and scores each one: sources used, framework
96F9
detected,
nodes, flags, percentage described.
It also carries a structure-sanity column, which exists because a coverage number
alone can be gamed by the very failure it should catch. %described once reported a
tool as fine at 100% while 39 of its 40 subcommands had been fabricated out of wrapped
prose. A metric that improves when the tool gets worse is worse than no metric.
CI gates every change against a fixed tool list, and sweeps the whole PATH
separately for the broad picture.
Coverage is not accuracy, though, and the honest number is lower than a green badge
suggests. A frozen, randomly drawn queue of real tools gets reviewed by a human against
each tool's own --help text — the sample is committed before any verdict is recorded,
so it cannot be redrawn once the results look bad. The most recent draw (seed 5,
43 tools judged) puts the parser at 58.1% fully correct, 95% CI [43.3%, 71.6%];
tools the pipeline itself rates ok score 80.0% [60.9%, 91.1%]. Repeat-review of the
same tools agreed 11 times in 16, so treat any single figure as approximate, and any
trend between draws as partly reviewer drift.
mandible is useful today and wrong often enough that you should check anything
surprising against the tool's own --help.
Tip
Something parses wrong? Run mandible --report <tool> and paste the output
into an issue. That takes two
minutes and is a complete contribution on its own.
? lists every binding and the footer keeps the important ones on screen, so this
section is deliberately short: arrows or hjkl to move, / to search, Tab
between panes, y to copy the selected flag, q to quit.
Search is the part that is not self-evident, because its two modes answer
different questions. names matches command names literally, so every row you see
contains what you typed. everything searches flags, summaries and descriptions
fuzzily, so gco finds checkout. / opens the first, and pressing it again
switches to the second.
Anything mandible gets wrong about a tool, you can correct locally. Drop a TOML file
at ~/.config/mandible/overrides/<tool>.toml:
summary = "my better one-line description"
[[flags]]
long = "verbose"
short = "v"
description = "a description that actually explains it"
[[node]]
path = ["build"]
summary = "corrections apply to subcommands too"These are yours and are never committed to this repository.
[!TIP] An override fixes a tool for you today. Consider also opening an issue: the real fix belongs in a framework grammar, where it improves every tool built with that framework at once.
| Variable | Effect |
|---|---|
NO_COLOR |
Disable colour. TERM=dumb and piped output do the same |
MANDIBLE_ASCII=1 |
Force the ASCII glyph set, for terminals that mangle Unicode |
MANDIBLE_CONFIG_DIR |
Override the config directory outright |
MANDIBLE_LOG |
Tracing filter, written to stderr |
$ mandible --doctor gh
framework: cobra (from artifact)
nodes: 29
flags: 2 (100.0% described)--doctor reports which framework was identified, which sources contributed, and how
much of the tool was understood. It turns "mandible is wrong about tool X" into "the
cobra grammar mishandles Y", which is a bug someone can actually fix.
spec.md |
Design authority: the source model, the safety policy, and the measurement behind every non-obvious decision |
AGENTS.md |
The invariants table. Every entry names the failure it prevents |
If a tool renders wrong, that is worth reporting even if you never look at the
code. Run mandible --report <tool> and paste the output into an issue. Your
tool's version and its exact help text vanish when you upgrade, and nobody else
can recover them. Everything after that can be done later by anyone.
There is a second thing you can do that is hard for us to do ourselves. Every
accuracy figure here comes from one Ubuntu machine on ARM, so whatever is
installed on your PATH is probably software this project has never seen. The
built-in audit tool samples your own commands, shows you the parse next to the
real help text, and records what you think of each one:
$ cargo run -p xtask -- audit sample --seed 42 --sample 20
$ mandible --review 42Attach the resulting audit/42.toml to an issue. Twenty tools is plenty.
CONTRIBUTING.md covers both, plus writing tests and
changing the parser.