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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
The same job on other stacks
- Generate Man Pages for a Cobra CLI (Cobra)
- Add a Man Page to a Go CLI (Go CLI)