All jobs

Upgrade Go Modules Weekly for a Cobra CLI

Yes. Each week the agent bumps Cobra, Viper and the rest of go.mod, handles the Go version a bump forces, runs the tests and opens one PR, or says why not.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

In a Go command-line tool the dependency list is short and the consequences of moving it are not. In a Cobra CLI like spf13/cobra-cli, go.mod has two requirements, github.com/spf13/cobra v1.6.1 and github.com/spf13/viper v1.12.0, under a go 1.15 directive, and go.sum runs to several hundred lines because that Viper release pulls in remote configuration backends and encoders the tool never uses. The agent reads those two files, then .github/workflows/test.yml, whose test-unix job builds on Go 1.14 through 1.17 on Ubuntu and macOS and whose lint job installs Go 1.17, and the Makefile, where make test runs richgo test -v ./... after go get -v ./.... It also reads how the code uses each library: cmd/root.go binds flags and reads a YAML file through Viper, and the tests under cmd/ compare generated projects against golden files in cmd/testdata.

It takes the two libraries one at a time, because they ask different things of the module. Cobra's current release still declares go 1.15 in its own go.mod, so go get github.com/spf13/cobra@latest followed by go mod tidy changes the requirement and its indirect lines and nothing else; that is the first commit. Viper is the second, and it is where the upgrade stops being mechanical. Its current release declares go 1.23.0, and the Go command will not select a module that needs a newer language version than the main module states, so the same go get rewrites the go directive in this repository's go.mod. From that commit on the tool no longer builds with the four Go versions the CI matrix names.

The agent treats that as the decision it is. It does not quietly edit the matrix to make the run green. It makes the Viper bump its own commit, adds a second commit that moves the test-unix matrix and the lint job to Go versions at or above the new directive, and writes in the pull request that merging the pair raises the minimum Go for anyone who runs go install on the tool. Then it checks what Viper dropped along the way. The newer go.mod no longer requires hashicorp/hcl, magiconair/properties or gopkg.in/ini.v1, which the old one did, so the agent greps for SetConfigType and config file extensions and confirms this tool reads only YAML, and it looks at each Viper call in cmd/ against the release notes between the two versions.

After every commit it runs go build ./..., go vet ./... and go test ./..., then make test with richgo installed so the Makefile path is exercised too, and the golden comparisons in cmd/ decide whether generated projects still come out byte for byte the same. It builds the binary, runs cobra-cli init and cobra-cli add serve in a scratch module, and compiles what was generated against the upgraded Cobra. It records the size of go.sum before and after and runs govulncheck ./... on both ends to show which advisories the upgrade closed.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Upgrade the Go modules of this Cobra CLI. Read go.mod, go.sum, .github/workflows/test.yml, .github/dependabot.yml, the Makefile, every file under cmd/ including the tests and testdata, and tpl/main.go first. Upgrade github.com/spf13/cobra to its latest release with go get and go mod tidy as one commit. Upgrade github.com/spf13/viper as a second commit and state what happens to the go directive; if it rises, update the Go versions in the workflow in a third commit and say plainly that this raises the minimum Go for users. Check every viper call in cmd/ against the release notes between the old and new versions, and confirm which config formats the code reads, since newer Viper releases dropped some encoders from the core module. After each commit run go build ./..., go vet ./..., go test ./... and make test with richgo installed. Build the binary, run init and add in a scratch module and compile the generated project. Report the line count of go.sum and the output of govulncheck ./... before and after. Open one pull request with a table of module, old version, new version and commit. If the tests fail after a bump, drop that bump, quote the failure and keep the rest.",
  "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

One pull request with up to three commits. The first moves Cobra and changes only go.mod and go.sum. The second moves Viper, and with it the go directive and most of go.sum, which shrinks because the remote backends are gone from the dependency graph. The third edits .github/workflows/test.yml so the matrix and the lint job use Go versions the module can still build with. The description holds the version table, the old and new go directive in bold, the results of build, vet and tests after each commit, the generated-project check, the go.sum line count on both ends and the two govulncheck reports.

A reviewer decides one thing the agent cannot: whether raising the Go floor is acceptable for the tool's users today. If it is not, they revert the second and third commits and merge the Cobra bump alone, which is why the commits are separate. They also check that no golden file under cmd/testdata changed, since a change there would mean the upgraded libraries altered what the tool generates.

The session's transcript, from GET /o/{org}/sessions/{id}/messages, has every go command with its output, including the exact line where go get reported the directive change.

Run it on every Monday morning

An automation in the Project with this prompt and a schedule trigger, cron set to 0 8 * * 1 and timezone to yours, runs it weekly. Once the first run has cleared the backlog, most weeks produce a small pull request of patch bumps or none at all, and the run's result says which.

A team with many CLIs starts them from its own scheduler instead: one POST /o/{org}/sessions per repository with an API key, each with a request_id that is a UUID v5 of the repository name and the ISO week, so a retried job returns the run it already started. Runs past the key's concurrency limit are created queued and start as slots free, so the batch needs no retry loop.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

Why run it on Rush?

A dependency bot can open the Viper pull request on a repository like this one, but it bumps a version and cannot decide that four entries in a CI matrix have to go. The work that unblocks it is judgement plus commands: read what the bump forces, split it so a maintainer can take half, prove the tool still generates the same files. The agent does that in its own sandbox with a current Go toolchain and keeps the output of every step in the run's record.

For a CLI the proof matters more than the diff. A code generator can compile and still emit something different, so the run builds the binary, generates a project and compiles it, and reports the vulnerability scan on both sides of the change. None of that needs a maintainer's laptop, and ten tools can be brought up to date at the same time, each in a separate sandbox with a separate pull request.

Frequently asked questions

Why did the go directive in go.mod change?

Because a dependency now requires a newer Go than the module declared. Since Go 1.21 the go line is a minimum that the toolchain enforces, and go get raises it to satisfy the modules you select. The agent reports the old and new value and puts the bump that caused it in its own commit.

Can I upgrade Cobra without upgrading Viper?

Yes, and the pull request is arranged for exactly that. The Cobra bump is the first commit and stands alone; reverting the later commits leaves a tool on the new Cobra, the old Viper and the old Go floor.

Does it run go get -u on everything?

No. A blanket go get -u ./... moves every indirect module at once and makes a failure hard to attribute. The agent upgrades the direct requirements one at a time, lets go mod tidy settle the indirect ones, and tests between steps.

Will the generated project templates be updated too?

Only if you ask. The templates in tpl/ and the golden files describe what the tool writes for its users, which is a product decision. This run checks that they still produce a project that compiles and leaves their content alone.

More Cobra jobs

The same job on other stacks

More jobs like this: Upgrade dependencies weekly

Keep reading