All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

More jobs like this: Hand off a long task

Keep reading