# Add a Man Page to a Go CLI

Yes. An agent writes a man page for your Go CLI from its real flags and exit codes, adds a test that keeps it in sync, ships it in release archives and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-man-page/go-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 where the CLI describes itself today. In a tool like tomnomnom/gron, everything is in `main.go`: a custom `flag.Usage` that prints a synopsis (`gron [OPTIONS] [FILE|URL|-]`), eleven options registered with the standard `flag` package in short and long pairs (`-u`/`--ungron`, `-v`/`--values`, `-c`/`--colorize`, `-m`/`--monochrome`, `-s`/`--stream`, `-k`/`--insecure`, `-x`/`--proxy`, `--noproxy`, `-j`/`--json`, `--no-sort`, `--version`), a table of exit codes 0 to 6 from `exitOK` to `exitJSONEncode`, and four examples. There is a `completions/` directory with Bash and Fish scripts, a `README.mkd` whose Installation section covers release archives, Homebrew and `go install`, and an `ADVANCED.mkd`. Releases run through `.github/workflows/release.yml` with `goreleaser/goreleaser-action@v6` and a `.goreleaser.yml` that only enables a source archive, so binaries and archives use GoReleaser's defaults. No file ends in `.1`.

It writes `gron.1` by hand in man(7) roff, because a CLI with eleven flags and a standard-library `flag` set does not need a generator and a dependency to produce one page. The sections follow the usage text: NAME, SYNOPSIS, DESCRIPTION taken from the first line of `flag.Usage`, OPTIONS with each short and long form and the one-line description the usage prints, EXIT STATUS with the seven codes and their meanings, EXAMPLES with the four from the usage and the `ungron` alias the README recommends, and SEE ALSO pointing at the README and `ADVANCED.mkd`. The agent renders it with `man -l gron.1` and lints it with `mandoc -T lint` in the sandbox until both are clean.

A page that drifts from the binary is worse than none, so the agent adds a test in `main_test.go`: it calls `flag.VisitAll` on the registered flag set and asserts that every flag name appears in `gron.1` as a bold option, and that every option in the page is a registered flag. Adding a flag without touching the page fails `go test`, which `.github/workflows/build.yml` already runs on `stable` and `oldstable`.

Finally it wires distribution. `.goreleaser.yml` gets an `archives` entry that adds `gron.1` and the `completions/` files beside the binary in every archive, keeping the default name template so existing download links in the README stay valid, and the Installation section gains a line showing where to copy the page (`/usr/local/share/man/man1/`). It runs `goreleaser check` and `goreleaser release --snapshot --clean` in the sandbox to confirm the archives contain the page before opening the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a man page to this Go CLI. Read main.go, the flag registrations, the custom usage text, the completions directory, the README installation section and the GoReleaser config first. Write gron.1 by hand in roff with NAME, SYNOPSIS, DESCRIPTION, OPTIONS listing every short and long flag with its description, EXIT STATUS with every exit code, EXAMPLES from the usage text and SEE ALSO. Render it with man and lint it with mandoc until clean. Add a Go test that walks the registered flags with flag.VisitAll and fails if any flag is missing from the page or any option in the page is not a registered flag. Add an archives section to the GoReleaser config that ships the man page and the completion scripts in every release archive without changing archive names, run goreleaser check and a snapshot release to confirm, add an install line to the README, and 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 that adds `gron.1`, changes `main_test.go`, `.goreleaser.yml` and `README.mkd`, and touches no other Go source. The description shows the rendered page as text from `man -l`, the `mandoc -T lint` result, and the file listing of one snapshot archive with the page and completions inside.

The run's record keeps the `go test` run with the new sync test passing on the current flag set and the `goreleaser release --snapshot` output, so a reviewer can see the archive layout without cutting a release to find out.

Before merging, a reviewer reads the option descriptions for tone, since the page copies the terse usage lines and may deserve a sentence more in places, and decides whether packagers downstream, such as a Homebrew formula or a distribution package, should be told the archive now carries a page they can install.

## Run it on every pull request that changes main.go

In the console, an automation in the Project that has the repository, with a `github` trigger on `pull_request.opened`, starts one run per pull request with the event after the prompt. The prompt asks the run to finish at once unless the diff registers, renames or removes a flag, and otherwise to update `gron.1` to match, re-render and lint it, run `go test` so the sync test proves the match, and push the change to the pull request branch with a comment saying which options moved.

From your own tooling, a handler that receives GitHub's `pull_request` webhook sends one `POST /o/{org}/sessions` with the pull request URL in `resources` so the run checks out that branch, with a `request_id` that is a UUID v5 of the pull request id so a redelivery never starts a second run.

## Why run it on Rush?

A man page is mostly transcription, and transcription is where a person skims and a flag goes missing. The agent reads the flag registrations rather than the README, so the page matches the binary, and the sync test it adds makes that true for every future flag too. Rendering with `man`, linting with `mandoc` and building a snapshot release are all things a laptop can do, but they rarely get done for a documentation change; in the sandbox they run every time and the output stays in the record.

The same request fits any Go CLI in an organisation, whether it uses the standard `flag` package, pflag or cobra, because the agent reads whatever the repository has and chooses between a hand-written page and a generated one accordingly, each run in its own sandbox with its own pull request.

## Frequently asked questions

### Why write the page by hand instead of generating it?

For a CLI on the standard `flag` package with a handful of options, a generator adds a build step and a dependency to produce a page you could read in a minute. The sync test gives the guarantee a generator would, that flags and page agree, without the tooling. A cobra or pflag CLI with subcommands is a different case and the agent generates there.

### Will the page ship with releases?

Yes. The `archives` entry in `.goreleaser.yml` includes `gron.1` and the completion scripts in every archive GoReleaser builds, and the snapshot release in the sandbox shows the resulting file list. Archive names keep GoReleaser's default template so nothing linking to a release asset breaks.

### Does Homebrew install it automatically?

Only if the formula is told to. The pull request puts the page in the archive, which is what a formula needs; adding `man1.install` to the formula is a change in the tap or in homebrew-core, outside this repository, and the description says so.

### How does the page stay in sync with new flags?

The test in `main_test.go` walks every registered flag and checks it against the page in both directions. A pull request that adds `--foo` without a matching entry fails `go test` in the existing CI workflow, which runs on every push and pull request.

### What about Windows users?

The page is included in the Windows zip too, where it is inert; `gron --help` keeps printing the same usage text on every platform. Nothing in the binary changes, so there is no runtime cost anywhere.

## More Go CLI jobs

- [Add a Nix Flake to a Go CLI](https://getrush.ai/run/add-nix-flake/go-cli/)
- [Add a Progress Bar to a Go Command-Line Tool](https://getrush.ai/run/add-progress-bar/go-cli/)
- [Add a GitHub Release Workflow to a Go CLI](https://getrush.ai/run/add-release-workflow/go-cli/)

## The same job on other stacks

- [Generate a Man Page for a Rust CLI With clap_mangen](https://getrush.ai/run/add-man-page/rust-cli/)
- [Generate Man Pages for a Cobra CLI](https://getrush.ai/run/add-man-page/cobra/)

## More jobs like this: Turn a Linear label into a PR

- [Add a Message Shortcut to a Slack Bolt App](https://getrush.ai/run/add-message-shortcuts/slack-bolt/)

## 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/)
