# Generate Man Pages for a Cobra CLI

Yes. An agent adds a hidden docs command built on cobra/doc, generates man pages and Markdown for every subcommand, keeps them current in CI, and opens a PR.

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

## What the agent does

The agent reads the command tree before it documents it. In a Go CLI like spf13/cobra-cli, `go.mod` declares `go 1.15` with `github.com/spf13/cobra v1.6.1` and `github.com/spf13/viper v1.12.0`; `main.go` calls `cmd.Execute()`; `cmd/root.go` defines `rootCmd` with `Use: "cobra-cli"`, a `Long` description, persistent flags `--config`, `--author`/`-a`, `--license`/`-l` and `--viper`, Viper bindings for `author` and `useViper`, and `rootCmd.AddCommand(addCmd)` and `AddCommand(initCmd)` from `cmd/add.go` and `cmd/init.go`. `cmd/golden_test.go` compares generated projects with `cmd/testdata/*.golden`, the `Makefile` has `fmt`, `lint` (golangci-lint), `test` and a `gox` cross-build, and `.github/workflows/test.yml` runs `make test build` on Ubuntu and macOS across Go 1.14 to 1.17 plus a MINGW64 job. The only documentation a user can reach is `cobra-cli --help`; there is no `docs/` directory and no man page.

Cobra ships its generator in the same module as the library, `github.com/spf13/cobra/doc`, so `go.mod` gains no new requirement and `go mod tidy` only adds the `go-md2man` and `yaml` entries the package needs to `go.sum`. The agent adds `cmd/docs.go` with a `docs` command marked `Hidden: true` so it stays out of the help listing, taking `--dir` (default `./docs`) and `--format` with `man` and `markdown`. For `man` it calls `doc.GenManTree(rootCmd, &doc.GenManHeader{Title: "COBRA-CLI", Section: "1", Source: "cobra-cli", Manual: "Cobra Manual"}, dir)`, which writes `cobra-cli.1`, `cobra-cli_add.1`, `cobra-cli_init.1` and the `cobra-cli_completion*.1` pages for the completion command cobra adds on its own; for `markdown` it calls `doc.GenMarkdownTree(rootCmd, dir)`. The agent sets `rootCmd.DisableAutoGenTag = true` and a fixed `Date` in the `GenManHeader`, because the Markdown footer and the man page's `.TH` line otherwise carry the generation date and every regeneration would show a diff.

The generated files are committed under `docs/man/` and `docs/md/`, and a `docs` target in the `Makefile` regenerates both. `cmd/docs_test.go` runs the generator into `t.TempDir()`, asserts the expected file names exist and that `cobra-cli_add.1` mentions the inherited `--author` and `--license` flags, which is the part people forget persistent flags produce. In `test.yml` the agent adds one step after the tests that runs `make docs` and `git diff --exit-code docs/`, so a flag added without regenerating the pages fails the build. `golangci-lint` runs on the new file like the rest of `cmd/`.

The agent runs `go build ./...`, `go test ./...`, `make docs` and `man -l docs/man/cobra-cli.1` in its sandbox and includes the rendered first screen in the pull request. `README.md` gets an "Installing the man pages" section (`cp docs/man/*.1 /usr/local/share/man/man1/`, then `man cobra-cli`). The golden tests, the license templates in `cmd/license_*.go` and the `tpl/` directory are untouched.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Generate man pages for this Cobra CLI. Read go.mod, main.go, every file in cmd/, the Makefile and the CI workflow first. Add a hidden docs subcommand that uses the cobra/doc package to write a man page tree and a Markdown tree into a directory flag, with DisableAutoGenTag set and a fixed header date so regeneration is stable. Commit the generated docs, add a Makefile target that regenerates them, a Go test that generates into a temp dir and checks the file names and that persistent flags appear in subcommand pages, and a CI step that regenerates and fails on a diff. Run go build, go test, the regeneration and render one page with man -l, and include the output. Add a README section on installing the pages. Do not touch the golden tests or the license templates. 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 `cmd/docs.go`, `cmd/docs_test.go`, `docs/man/*.1` and `docs/md/*.md`, and changes `cmd/root.go` (`DisableAutoGenTag` and the `AddCommand`), `Makefile`, `.github/workflows/test.yml`, `README.md` and `go.sum`. `go.mod` is unchanged.

The description lists the generated page names, quotes the `go test` summary, the `git diff --exit-code docs/` result after a second regeneration, and the first lines of `man -l docs/man/cobra-cli.1`. The commands and full output are in the transcript at `GET /o/{org}/sessions/{id}/messages`.

Before merging, a reviewer reads one man page for wording that came from a `Short` or `Long` string written for `--help` and not for a manual, decides whether the completion pages should be kept, and whether generated files belong in git or in the release archive. A follow-up message to the same session can move generation into the release workflow instead.

## Run it on every Go CLI released without documentation

A team that ships several Cobra tools starts one run per repository with one `POST /o/{org}/sessions` each, the repository in `resources` and this prompt as `input`. Each run reads its own `rootCmd` and subcommands, so a tool with twenty commands gets twenty pages and a tool whose root already sets `DisableAutoGenTag` gets no duplicate line.

Send a `request_id`, a UUID v5 of the repository's full name, so a retried call returns the run it already started. The key's `webhook_url` reports when each run the key starts finishes, with the run's final answer in `result`.

## Why run it on Rush?

The generator is a two-line call; the work is choosing where it lives, keeping the output stable across runs, making persistent flags show up in every page and stopping the pages from drifting behind the flags. The agent reads the command tree and the CI matrix, generates in its own sandbox, regenerates a second time to prove the diff is empty, and keeps every command's output.

The pull request carries the generator, the pages, the drift check and a rendered page, so review is reading a diff rather than installing `go-md2man` and a man path locally. Several CLIs can be done at once, each in its own sandbox with its own pull request.

## Frequently asked questions

### Does this add a dependency?

No module is added to `go.mod`; `cobra/doc` is part of the `cobra` module the CLI already requires. `go.sum` gains the checksums for the packages `doc` imports, which `go mod tidy` writes.

### Why commit the generated pages instead of building them at release time?

Committed pages are reviewable and show in the diff when a flag changes, and the CI drift step guarantees they stay current. If you package with GoReleaser or a Makefile install target, say so and the agent generates into the archive at release time instead and keeps the drift check.

### Will the hidden command show in --help or in completions?

`Hidden: true` keeps it out of the help listing and out of shell completion suggestions, but `cobra-cli docs` still runs when typed. If you would rather have no runtime command at all, say so and the agent generates from a `go run ./tools/docs` program with a build tag instead.

### What about the completion command's pages?

Cobra adds a `completion` command with `bash`, `zsh`, `fish` and `powershell` subcommands to any root that has subcommands, and `GenManTree` writes a page for each. The agent keeps them because users do run `man cobra-cli-completion-zsh`; say so in the prompt if you want them filtered out.

## More Cobra jobs

- [Add an SBOM to the Release of a Cobra CLI](https://getrush.ai/run/add-sbom-to-release/cobra/)
- [Add a --version Flag to a Cobra CLI](https://getrush.ai/run/add-version-flag/cobra/)
- [Migrate a Cobra CLI to golangci-lint v2](https://getrush.ai/run/migrate-golangci-lint-v2/cobra/)

## The same job on other stacks

- [Add a Man Page to a Go CLI](https://getrush.ai/run/add-man-page/go-cli/)
- [Generate a Man Page for a Rust CLI With clap_mangen](https://getrush.ai/run/add-man-page/rust-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/)
