# Migrate a Go CLI From urfave/cli v1 to v2

Yes. An agent ports a Go command-line tool from urfave/cli v1 to v2, proves every short flag still works, and opens a pull request with both outputs.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-urfave-cli-v1-to-v2/urfave-cli/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts by listing what the tool asks of the library. In a tool like jmespath/jp the whole program is `jp.go`, and it imports `github.com/urfave/cli` with no version suffix. It declares five flags as struct values with v1's combined names (`"compact, c"`, `"filename, f"`, `"expr-file, e"`, `"unquoted, u"` and `ast`), one of them with `EnvVar: "JP_UNQUOTED"`. It sets `app.Author` and `app.Email` to empty strings, uses an action of type `func(c *cli.Context)` that returns nothing and calls `os.Exit` itself, and treats `c.Args()` as a slice with `len(c.Args())` and `c.Args()[0]`. `go.mod` says `go 1.17` and pins `github.com/urfave/cli v1.22.5`.

Before touching anything it builds the unchanged binary and records what it prints for a fixed list of commands: `--version`, `--help`, each flag in its long and short form, the environment variable, an unknown flag, and a flag placed after the expression. Then it changes the import to `github.com/urfave/cli/v2` and lets the compiler say what broke. On this file that is five kinds of error: `app.Author undefined`, `cli.BoolFlag does not implement cli.Flag (method Apply has pointer receiver)`, `unknown field EnvVar`, the action that cannot be used as `cli.ActionFunc`, and `c.Args()` passed to `len`. The fixes are mechanical: flags become pointers, `EnvVar` becomes `EnvVars` with a slice, the action returns an `error`, and the argument checks become `c.Args().Len()` and `c.Args().First()`.

The part the compiler does not report is the flag names. A v2 flag still accepts `Name: "compact, c"` and the program builds. `--compact` works, but `-c` now answers `flag provided but not defined: -c`, and the help output lists only the long form. Every short option in the tool is gone and no build step says so. The agent splits each one into `Name: "compact"` and `Aliases: []string{"c"}`, then runs every short flag against the new binary instead of trusting the diff.

Last comes the Go version. The newest v2 release, v2.27.7, declares `go 1.18` and uses generics, and `go mod tidy` leaves `go 1.17` in this repository's `go.mod`, so nothing local complains. With a Go 1.17 toolchain the build stops inside the library with syntax errors in its `sliceflag.go`. That matters here because `.github/workflows/run-tests.yml` runs `make` on Go 1.15, 1.16 and 1.17. The agent names the two ways out, raising the matrix and the `go` line or pinning v2.4.0, which does build on 1.17, and takes the one the prompt asks for. It then runs what `make` runs: the bats cases in `test/cases/search.bats` and the JMESPath compliance runner, `test/jp-compliance`.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Port this Go command-line tool from github.com/urfave/cli v1 to github.com/urfave/cli/v2. First read go.mod, every file that imports the library, the Makefile, the test scripts and the CI workflow. Build the unchanged binary and record its output and exit code for: --version, --help, every flag in long and short form, every environment variable a flag reads (with a valid and an invalid value), an unknown flag, no arguments, and a flag placed after the positional argument. Then switch the import path, fix each compiler error, and split every combined flag name such as \"compact, c\" into Name plus Aliases, because v2 compiles the old form and silently drops the short flag. Do not change behaviour that is the same in both versions, even if it looks like a bug; list it instead. Check which Go version the chosen v2 release needs against the go directive and the CI matrix; raise both to the lowest version that builds and say so, do not pin an old v2 release. Run go vet, go mod tidy and the repository's own tests. Repeat the recorded commands on the new binary and put both outputs side by side in the pull request, with every line that differs explained.",
  "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

A pull request that changes `jp.go`, `go.mod`, `go.sum` and the Go versions in the workflow matrix. `go mod tidy` replaces the v1 requirement with `github.com/urfave/cli/v2` and brings in one new indirect module, `github.com/xrash/smetrics`, which v2 uses for its flag suggestions. The description holds the compiler errors in the order they appeared and the table of recorded commands for the old and new binaries.

Most rows of that table are identical, and the ones that are not are the review. Boolean flags gain `(default: false)` in the help text, the usage line loses `[arguments...]`, and a usage error starts with `Incorrect Usage:` where v1 printed `Incorrect Usage.`. An unparseable `JP_UNQUOTED=yes` used to print nothing at all; v2 prints a message that names the variable and the flag. Anyone who parses this tool's help or error text in a script reads those rows first.

The description also lists what the agent left alone because both versions do it: a flag written after the expression is not parsed, combined short flags such as `-cu` are rejected, and an unknown flag prints a usage error but exits 0, because the program ignores the error `app.Run` returns. The reviewer decides whether any of those becomes a follow-up, and confirms that dropping Go 1.15 through 1.17 from the matrix is acceptable for the people who build this tool from source.

## Run it on every Linear issue labelled cli-v2

A team with several small Go tools usually has this migration filed once per tool. Connect Linear under Settings → Connections, then add an automation to the Project that holds the tool's repository, with a `linear` trigger on `linear.issue.labeled` for the label you pick and the prompt above saved as its prompt. When a member of your Rush org adds the label, a run starts in that repository. The issue arrives after the prompt as event text, so a note in the issue such as "keep Go 1.17" is something the agent reads but the saved prompt still decides.

To move a batch without Linear, send the body above to `POST /o/{org}/sessions` once per repository, each with a `request_id` that is a UUID v5 of the repository name so a retried script starts nothing twice. Runs past the key's `max_concurrent` answer `202` with `status: "queued"` and start as slots free.

## Why run it on Rush?

This migration fails quietly. The code compiles, the tests that exist pass, and a short flag that operators have typed for years stops existing. The only way to see it is to run the binary before and after with the same arguments, and that is what the agent does in a sandbox of its own, where building two copies of a tool and running a few dozen commands costs nobody's laptop time. Each command and its output is kept in the run's transcript, so the table in the pull request can be checked against what was really printed.

The Go version question is the same kind of problem. A laptop with a current toolchain builds the port without a warning, and the first sign of trouble would be a red matrix job on an old Go. A run that reads the workflow file and the library's own `go.mod` puts that decision in the pull request description before anyone pushes.

## Frequently asked questions

### Why do my short flags stop working after moving to urfave/cli v2?

Because v1 read `Name: "compact, c"` as a long name and a short name, and v2 does not. In v2 the short form goes in `Aliases: []string{"c"}`. The old spelling still compiles, which is why the loss shows up only when someone runs `-c`.

### Which Go version does urfave/cli v2 need?

The current release, v2.27.7, declares `go 1.18` in its `go.mod` and uses generics, so Go 1.17 cannot compile it. v2.4.0 declares an older version and builds on 1.17. The agent checks the release it picks against your `go` directive and your CI matrix, because `go mod tidy` does not raise the directive for you.

### Should I go straight to v3 instead?

It is a separate job. A v3 line exists (v3.14.0 at the time of writing) and changes more than v2 did. Moving to v2 first gives you a small, reviewable diff and a recorded baseline of the tool's behaviour, which is the thing a later v3 port needs most.

### Will the agent fix bugs it finds on the way?

Not unless the prompt says to. In this tool an unknown flag exits 0 in both versions, and the agent reports that as existing behaviour. Mixing a behaviour change into a library port makes the before and after table useless as evidence.

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

- [Migrate a Vue 3 App From Vuex to Pinia](https://getrush.ai/run/migrate-vuex-to-pinia/vuex/)
- [Migrate From Winston to Pino in a Node.js Service](https://getrush.ai/run/migrate-winston-to-pino/winston/)
- [Move JWTs From localStorage to httpOnly Cookies in an Express API](https://getrush.ai/run/move-jwt-to-httponly-cookies/jsonwebtoken/)
- [Remember Window Size and Position Between Launches in a Tauri App](https://getrush.ai/run/persist-window-state/tauri/)
- [Plan a Linear Issue Against a Django Codebase](https://getrush.ai/run/plan-linear-issues/django/)
- [Plan a Linear Issue Against a Go Codebase](https://getrush.ai/run/plan-linear-issues/go/)

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