When the man(1) Comes Around

apropos(1) of nothing

When you open up a command line and type man claude you will get the error:

No manual entry for claude

The same is true for man codex, man ollama, man gemini, and man openclaw.

These are terminal-native tools, built by people who live in the terminal for people who live in the terminal. AI work has embraced command line development. They have gorgeous TUI interfaces with custom spinners and formatted text and inventive inputs. But they do not have man pages.

Man pages have one of the largest unbroken lineages in computing. Jerry Saltzer wrote RUNOFF in 1964 at MIT to format his doctoral thesis on CTSS — the Compatible Time Sharing System¹. When CTSS evolved into Multics, RUNOFF came along. When Bell Labs left Multics and Ken Thompson started building Unix on a PDP-7, roff — a RUNOFF descendent — was one of the first programs ported over. Joe Ossanna extended roff into nroff and troff. Kernighan rewrote it in the C programming language. The roff family became the typesetting backbone of Unix, and the manuals they produced — man pages — became the contract between a tool and its user. Type man and the tool you want to understand, and you get the same structure for every tool. No network call needed, no browser necessary. The documentation is right there on the machine, formatted by a typesetting system that predates the operating system itself.

Generated by Nano Banana

This lineage has extended well into the BSD family and Linux. OpenBSD’s mandoc is arguably the best man page toolchain ever built, and their documentation culture treats self-documenting tools as a point of pride. But the ecosystems that that produce most modern CLI tools — Node, Python, Rust — don’t share that culture. The build tooling doesn’t encourage it². Ryan Tomayko, an early GitHub engineer, built ronn in 2009. “The opposite of roff”, ronn let you write man pages in Markdown and generate proper roff output. I’ve used it in my own projects, and it worked well. But maintenance on it has stopped, and forks of it have fizzled.

The web won. Developers reach for --help or open a browser tab, and man pages became something old timers (like me) shipped.

Here come the agents

Suddenly, the absence of structured documentation matters again. AI agents parse --help output constantly, and every tool formats that differently. Some use GNU-style long flags, some use subcommand trees, some dump paragraphs of unstructured prose. An agent encountering a new CLI tool has to pattern-match against ad hoc conventions every single time. Man pages don't have this problem. The section structure is standardized. An agent parsing a man page knows where to find the flag list, the usage pattern, the exit codes. No scraping, no guessing, no context window burned on a docs site that may or may not have clean HTML. And agents can write the format competently — the roff macro language is semantic markup, and structured transformation of semi-structured input is exactly the kind of task LLMs handle well. An agent could introspect a tool, synthesize a man page, and store it locally. Now every other process on the system has a standardized, apropos searchable, offline reference.

We've actually started reinventing this without calling it what it is. Anthropic's CLAUDE.md and AGENTS.md — structured local reference files that tells agents about project context — is a bespoke solution to a problem that man(1) has addressed since 1971. The impulse is right: agents need local, structured, offline documentation. The format already exists. It's been sitting in /usr/share/man for fifty years.

Introducing mansplain

So I built mansplain. Point it at a tool’s --help output or README and it generates a well-formed mdoc(7) man page via any OpenAI-compatible API — OpenAI, OpenRouter, a local model through LM Studio, whatever you got.

mansplain generate --name jq -o jq.1
man ./jq.1

It also has a convert command — inspired directly by Tomayko’s ronn — that compiles ronn-format Markdown to mdoc deterministically. No LLM, API key, or network needed. Write the man page source in Markdown, keep it in version control, compile to mdoc in your build step.

curl -fsSL https://raw.githubusercontent.com/mwunsch/mansplain/main/install.sh | sh

Critically, mansplain also ships as a SKILL.md agent skill. This teaches any compatible coding agent — Claude Code, Cursor, Codex, CoPilot, etc. — how to write proper mdoc(7) man pages as part of its normal workflow. The skill works without the binary installed. The agent uses its own model and the full project context to generate the page, which typically produces better results than a standalone LLM call because the agent has the source code, not just the help text. If coding agents already know how to scaffold a README.md for a CLI project, they should know how to write a man page too³.

npx skills add mwunsch/mansplain

The infrastructure is already there. MANPATH, section numbering, discovery with apropos, cross-references. It's a local, offline knowledge graph for command-line tools, built decades before anyone was worrying about context windows and token costs. It was easy to forget about it because browsers became the de facto way to find information for humans, and because authoring them was unpleasant.

Agents don’t have that excuse.

1. RUNOFF is written in all caps because bits were expensive in 1964. Five- and six-bit character encodings were common; mixed-case filenames were a luxury.

2. Rust’s clap has clap_mangen for generating man pages from argument parser definitions. I’m not sure how many crates use it in practice.

3. mansplain ships its own man page, generated and validated by itself. Eat your own dog food. Ship your own man page.