# Generate a Man Page for a Rust CLI With clap_mangen

Yes. An agent adds a clap_mangen flag beside your completion generator, commits the man page, ships it in the archives and deb, and checks it stays current in CI.

[Run this on Rush](https://cloud.getrush.ai/run/add-man-page/rust-cli/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent clones the repository into its own cloud sandbox and reads how the CLI already describes itself. In a tool like dandavison/delta, `Cargo.toml` names the package `git-delta` at version `0.20.1` with a `delta` binary, `clap 4.3.14` with the `derive` feature and `clap_complete 4.4.4`, and no `build.rs`. `src/cli.rs` defines `Opt` with `#[derive(Parser)]` and a `#[command]` attribute setting `name`, `about` and `version`, and every option carries a doc comment that clap turns into help text, many of them pointing at a `STYLES` section. One of those options is `--generate-completion <SHELL>`, handled in `src/main.rs` by `subcommands::generate_completion::generate_completion_file`, which calls `cli::Opt::command()` and hands the command to `clap_complete::generate`; `cli.rs` keeps a list of such pseudo-flags, `IGNORED_OPTION_NAMES`, so they are skipped when options are processed for other purposes. There is no man page anywhere in the repository.

Release packaging shows where one would go. `etc/ci/before_deploy.sh`, run by `.github/workflows/cd.yml` for seven targets, has a `pack` function with a comment reading `manpage, readme and license` that copies only `README.md` and `LICENSE` into the archive, and a `make_deb` function that installs the binary under `usr/bin`, writes a `copyright` file and a `DEBIAN/control`, and installs nothing under `usr/share/man`. `verify-release.yml` downloads the `deb` assets, installs one on `debian:12` and checks `delta --version`. The `Makefile` has a `shell-completion` target that runs the release binary with `--generate-completion` for bash, fish and zsh into `etc/completion/`, and `manual/src/tips-and-tricks/shell-completion.md` documents that flag.

The agent follows that pattern exactly. It adds `clap_mangen` to `[dependencies]`, a `--generate-man-page` option on `Opt` beside `--generate-completion`, a `src/subcommands/generate_man_page.rs` that builds the command with `Opt::command()` and renders it with `clap_mangen::Man` to stdout, the branch in `main.rs` that calls it, and the name in `IGNORED_OPTION_NAMES`. It adds a `man-page` target to the `Makefile` that writes `etc/man/delta.1` from the release binary, runs it and commits the result, because `cd.yml` cross-compiles five of its seven targets with `cross` and a man page generated at package time would need to run a foreign binary. `before_deploy.sh` then copies `etc/man/delta.1` into the archive where its comment already expected one, and `make_deb` installs it gzipped under `usr/share/man/man1/`.

To keep the committed page from going stale, the agent adds a step to the `integration_tests` job in `ci.yml`, which already builds the release binary on Ubuntu and macOS, that runs `--generate-man-page` and diffs the output against `etc/man/delta.1`, failing with the diff when an option's help changed without the page being regenerated. It adds a check to `verify-release.yml` that the installed `deb` contains `usr/share/man/man1/delta.1.gz` and that `man -w delta` finds it. A new `manual/src/tips-and-tricks/man-page.md` is added to `SUMMARY.md` next to the completion tip. In the sandbox the agent runs `cargo build --release`, `make man-page`, `man -l etc/man/delta.1` to render it, `cargo test`, `cargo clippy` and `cargo fmt -- --check`, the three commands `CONTRIBUTING.md` names.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a generated man page to this Rust CLI. Read Cargo.toml, the clap definitions, how the existing completion generator is wired, the Makefile, the release packaging script and the CI workflows first. Add clap_mangen and a --generate-man-page option that mirrors --generate-completion, including any list of pseudo-flags the code keeps. Add a Makefile target that writes the page under etc/man from the release binary, run it and commit the page. Ship the page in the release archives and gzipped in the deb, add a CI step that regenerates it and fails on a diff, and add a release verification that the deb installs it. Document the flag in the manual. In your sandbox run the build, the target, render the page, and the tests, clippy and fmt check. Open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch that changes `Cargo.toml` and `Cargo.lock`, `src/cli.rs`, `src/main.rs`, `src/subcommands/mod.rs`, adds `src/subcommands/generate_man_page.rs` and `etc/man/delta.1`, and changes the `Makefile`, `etc/ci/before_deploy.sh`, `.github/workflows/ci.yml`, `.github/workflows/verify-release.yml` and two files under `manual/src/`. The description shows the rendered first screen of the page from `man -l`, the `cargo test` summary, and clean `clippy` and `fmt` runs.

The run's record keeps the release build, the generation, the render and every check with its output, so a reviewer can see the page was produced from this repository's own clap definitions and that the pseudo-flag list and the diff check were exercised.

Before merging, a reviewer reads the page for the sections clap_mangen produced from the doc comments and decides whether a hand-written `SEE ALSO` or examples section is worth adding through clap_mangen's section API, confirms the archive and `deb` changes against the asset list `verify-release.yml` expects, and runs the release workflow on a snapshot tag if the repository has that habit.

## Run it on every CLI repository

Start this once from a terminal with `POST /o/{org}/sessions`, this body and the repository in `resources`. The run keeps going in its sandbox after you close the window, and a follow-up through `POST /o/{org}/sessions/{id}/messages` can add an examples section or a second page for a subcommand without rebuilding. After the merge, the CI diff step does the ongoing work: a help text change that forgets to regenerate the page fails with the diff.

A maintainer of several Rust CLIs starts one run per repository from a script with the same body, each with its own `request_id`, a UUID, so a retried start returns the run it already began; the key's `webhook_url` receives `run.completed` for each with a `session_url` from which the handler reads the pull request link.

## Why run it on Rush?

A man page written by hand is out of date by the second release. Generating it from the same clap definitions that produce `--help` makes the two agree, but wiring that into a release that cross-compiles for seven targets, a `deb` built by a shell script and a verification workflow takes reading all of them. The agent reads them, follows the shape the completion generator already set, and proves the result by building, rendering and testing in its sandbox.

The sandbox has the Rust toolchain and `man`, the full record of every command stays with the run, and the release workflow is never triggered. Several CLIs can be done at once, each with its own pull request and its own rendered page.

## Frequently asked questions

### Why commit the generated page instead of building it at release time?

Because the release workflow builds five of its seven targets with `cross`, and a page generated at package time would have to run an ARM or musl binary on the x86 runner. A committed page is packaged by the existing script on every target, and the CI step that regenerates and diffs it keeps it from going stale.

### Will the page include the STYLES section and other long help?

clap_mangen renders what clap knows: the `about`, every option with its doc comment, and any `after_help` or `long_about` text the command sets. Sections that exist only in the online manual are not pulled in; the reviewer can add them through clap_mangen's custom section API, and the description points at where.

### Does this change the binary's behaviour?

Only by adding one pseudo-flag that prints the page and exits, in the same way `--generate-completion` already does. The agent adds it to the list of names the options code ignores, so it does not appear where that list is consulted, and `cargo test` and the end-to-end tests run unchanged.

### How does the deb get the page?

The packaging script's `make_deb` function gains an `install` of the gzipped page under `usr/share/man/man1/`, and the release verification job that already installs the `deb` on Debian 12 gains a check that the file is present and that `man -w delta` resolves to it.

## More Rust CLI jobs

- [Add a Minimum Supported Rust Version Check to a Rust CLI](https://getrush.ai/run/add-msrv-check/rust-cli/)
- [Add a Nix Flake to a Rust CLI](https://getrush.ai/run/add-nix-flake/rust-cli/)
- [Add Shell Completions to a Rust CLI](https://getrush.ai/run/add-shell-completion/rust-cli/)

## The same job on other stacks

- [Generate Man Pages for a Cobra CLI](https://getrush.ai/run/add-man-page/cobra/)
- [Add a Man Page to a Go CLI](https://getrush.ai/run/add-man-page/go-cli/)

## More jobs like this: Hand off a long task

- [Post a Rendered Manifest Diff on Every PR to an Argo CD Repository](https://getrush.ai/run/add-manifest-diff-to-ci/argo-cd/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
