Help! I need somebody! --help, not just anybody! Every tool that never had a manual page
View all articlesDustin Kirkland
SVP, Engineering
Chainguard
Dustin Kirkland SVP, Engineering
The documentation that isn’t there
“Help, I need somebody. Help, not just anybody.” (The Beatles, 1965)
Last week we launched man.cgr.dev: every manual page in Chainguard OS, version-exact, rendered for people and served to agents over MCP. At the end of that post I said the next problem is the tools that never shipped a manual page at all.
That turns out to be most of the tools people reach for today: crane, helm, kubectl, terraform, cosign, nearly anything written in Go or Rust in the last 10 years. They have no man page. Their documentation is whatever they print when you run them with --help.
That’s fine for a person at a shell. It’s a real problem for an agent. To read --help, something has to install the package and run the binary. Inside a minimal container image the tool may not even be there, and installing it to find out which flags it takes is a heavy, slow way to answer a question. So the agent guesses, from training data, for a version it cannot name.
The Beatles had this one right in 1965: help, but not just anybody’s. An agent needs the help for the exact version of the tool in front of it, from the package it is actually running. So we built that.
What we built
Every night, we install every package in Chainguard OS and run every executable in it with --help.
That’s about 40,000 packages across all three of our repositories, and more than 76,000 executables. More than 63,000 of them print something useful, and that output is now on man.cgr.dev, next to the manual pages, at the path the executable actually has on disk:
man.cgr.dev/help/usr/bin/pmm-agent(from an enterprise package)
The address is the full path, /usr/bin/ffmpeg rather than ffmpeg, because names collide. A quarter of executable paths in the distribution are provided by more than one package: several ffmpeg versions, several JDKs, a dozen Pythons. The page picks the default and lists every other package that provides the same path, each at its exact version. And like every manual page, every help page has a permanent, version-pinned address and a plain-text form.
Where a tool has both, we put them together. The tmux page shows its --help output beside its manual page, with the options from both merged into one list. Each option says where it came from: --help, the manual page, or both. When the two disagree — for example, a flag the manual page documents but the binary no longer accepts — we say so rather than picking one quietly. Manual pages now carry a small “--help output” link of their own, so the two are one click apart in either direction.
For agents: three new tools
The MCP server at man.cgr.dev/mcp grows from five tools to eight:
get_help a tool's --help output, at an exact version
describe_tool everything we know about one executable: usage, options,
exit codes, examples, from --help and the man page together
get_option one flag: what it does, what it takes, and where that came from
So the actual questions an agent asks get direct answers:
“Does tar have a flag for zstd?”
get_optionreturns--zstd, found in both--helpand the manual page, so high confidence.“What does exit code 1 mean for grep?”
describe_toolreturns no lines were selected, from the EXIT STATUS section of the page.“Show me kubectl’s help.”
get_helpreturns it, 40 lines at a time, so a large tool’s output does not swamp the context window.
Help text is third-party text
There is a catch with feeding program output to a model: The program wrote it, not us. Help text is untrusted input, and a prompt injection hidden in some tool’s --help would otherwise reach your agent wearing our credibility.
So we treat it as data, everywhere. Every piece of package-authored text an MCP tool returns, help output and manual page alike, is fenced between randomly generated markers and labeled as third-party content that the model should read rather than obey. Terminal escape sequences and control characters are stripped before anything is stored. Package metadata that we pass along, such as licence and homepage, has to look like what it claims to be, or we leave it out.
How we run 76,000 programs we didn’t write, every night
The design follows the same rule that held for manual pages: If it is on the site, it came out of a package we built and signed.
Each package is installed on its own, with only the dependencies it declares, into a fresh throwaway root filesystem in memory. Then each executable it owns is run inside a bubblewrap sandbox: no network, a read-only filesystem, its own namespaces, a short timeout, and a cap on output. We try the usual spellings (--help, -h, help, -help, --usage) and keep the one that reads most like help.
The output is bound to the signed package it came from. Every capture carries the checksum of its apk. The ingest service refuses anything whose checksum is not in the repository’s signed APKINDEX, which ingest fetches itself rather than accepting from the runner. A runner can fail, but it cannot add a document for a package we did not ship.
The whole distribution takes about 16 minutes for os/ on one 64-core VM, and about an hour and a half for everything. The nightly run is incremental: a package whose own version and installed dependencies are unchanged keeps yesterday’s result. That saves less than you might hope, because shared libraries like glibc and Python are rebuilt most days, and every rebuild sends each package above it round again; on a typical night about a third of packages carry forward. Once a week, on Saturday night, a full run starts from scratch. New versions are kept alongside the old, the same way manual pages are, so after its first four nights the corpus already holds more than 71,000 help documents.
The bonus: a nightly test of the whole distribution
Installing every package on its own and running every program in it turns out to be a remarkably good test of a Linux distribution.
The first full run found, in os/ alone, about 1,700 scripts whose interpreter is not a declared dependency (a Python script in a package that does not depend on Python works only by luck), and several dozen packages whose install scripts fail when installed alone. These are exactly the bugs that hide in a distribution, because almost nobody installs one package into an empty root and runs everything in it. Now we do it every night, and the results go straight back to our packaging work.
Try it
Humans: man.cgr.dev/help/usr/bin/crane, search for any tool at man.cgr.dev, or browse all of them at man.cgr.dev/help/
Agents:
claude mcp add --transport http chainguard-manuals https://man.cgr.dev/mcp, or point any MCP client athttps://man.cgr.dev/mcpEvery help page is also available as plain text: append .txt to its permanent address (for example man.cgr.dev/os/crane/latest/help/usr/bin/crane.txt)
Found something wrong or missing? Won’t you please, please help us, and tell us!
Share this article
Articles connexes
ingénierieCI in 2027: Why the future of coding needs instant back-pressure
ingénierieGitHub Actions down? No problem. Green with Chainguard Checks.
ingénierieIt’s a man’s, man’s, man’s world: Every manual page in Chainguard OS, now readable by your agent
ingénierieThis Shit is Hard: Nobody has ever been pwned by Helvetica…or have they?
ingénierieThis Shit is Hard: Building a vulnerability database from private reports
ingénierieThis Shit is Hard: Building forkstore