All jobs

Migrate a Rust CLI From structopt to clap 4 Derive

Yes. An agent ports structopt derives to clap 4 and compares the old and new binaries flag by flag, so changes in parsing, --version and exit codes are caught.

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

What the agent does

structopt is in maintenance mode and its derive macro lives on inside clap, so the port looks like renaming attributes. The agent treats it as a change to a program's public interface instead, because the command line is what users and scripts depend on. Before editing, it builds the current binary and records its behaviour: the full --help text of the program and of every subcommand, the output of --version, the parsed result of each example in the README, and the exit code for a bad flag. In a tool like gsquire/topngx, a top for NGINX logs, that surface is defined in src/main.rs by four derives: an Options struct with eight flags and an optional subcommand, a SubCommand enum with six variants (avg, info, print, query, sum, top), and two argument structs, Fields and Query.

The rename itself is quick. #[derive(StructOpt)] becomes Parser on Options, Subcommand on the enum and Args on the two structs. #[structopt(...)] becomes #[command(...)] on a type and #[arg(...)] on a field. short = "w" and short = "t" become the characters 'w' and 't', rename_all = "kebab-case" goes because it is the default, and Options::from_args() on line 346 becomes Options::parse(). Cargo.toml swaps structopt = "0.3" for clap with the derive feature. It compiles, and cargo test passes, because the repository's only tests are in src/nginx.rs and none of them runs the binary.

Then the agent runs the recorded commands against the new binary, and the rename turns out to have broken the README. The documented example is topngx query -q 'select * from log where bytes_sent > 100' -f request_path bytes_sent. Under structopt a Vec<String> option accepts several values after one flag. In clap 4 the same field takes one value per occurrence, so the command now ends with error: unexpected argument 'bytes_sent' found. The fix is num_args = 1.. on that field, and the agent adds it only where the old binary accepted several values. The second difference is -V: structopt added a version flag on its own, clap 4 adds one only when the type says #[command(version)], and without it topngx -V is an unexpected argument. The third is the exit status for a usage error, which moves from 1 to 2 and cannot be configured away with an attribute.

The agent fixes the first two, documents the third, and writes the checks down as integration tests so the interface is pinned from now on: one test per README example and one for --version. It reports the help text as a diff, since clap 4 prints Usage: and Commands: where the old output had USAGE:, FLAGS: and SUBCOMMANDS:, and drops the author line by default. Last, it reports what left Cargo.lock. Here structopt 0.3.15 was the only reason the lockfile held clap 2.33.1 with ansi_term, strsim 0.8 and textwrap 0.11. It also notes that atty stays, because main.rs calls atty::isnt directly on line 206.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Migrate this Rust command-line program from structopt to clap 4 with the derive feature. First install what the build needs (check the CI workflow for system packages) and build the current code. Record the present interface: --help for the program and for every subcommand, --version and -V, the exit status and message for an unknown flag and for a missing required argument, and the parsed arguments for every example command in the README (add a temporary debug print of the parsed struct if needed, and remove it afterwards). Then port: StructOpt to Parser, Subcommand and Args as appropriate, structopt attributes to #[command] and #[arg], string shorts to chars, from_args to parse. Replace the dependency in Cargo.toml and update Cargo.lock. Rebuild and replay every recorded command. For each difference decide: restore the old behaviour (for example num_args for an option that accepted several values after one flag, #[command(version)] for the version flag, explicit author or about), or document it if clap 4 cannot reproduce it (help layout, exit status 2 for usage errors). Do not rename, add or remove any flag or subcommand. Add integration tests that run the built binary for each README example and for --version. Run cargo fmt, cargo clippy and cargo test. Open a pull request with a table of every recorded command, old result and new result, the help diff, and the list of crates removed from Cargo.lock. List other unmaintained dependencies you noticed without changing them.",
  "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 Cargo.toml, Cargo.lock and the derive block at the top of src/main.rs, and adds a tests/ file that runs the binary. The centre of the description is the replay table: each command, what the structopt build did and what the clap build does. Rows that matched need no reading. Rows that differed carry the attribute that restored the old behaviour, or a note that the difference is deliberate and where it is documented.

A reviewer checks the two attributes that were added on purpose, num_args = 1.. on the fields option of Query and version on Options, and reads the short list of accepted differences: the help layout and exit status 2. If scripts in your organisation test for exit status 1 from this tool, this is where you find out before a release. The README's usage block, which shows the old help text, is updated in the same pull request from the new binary's actual output.

Run it on every Monday morning

A dependency in maintenance mode is a standing item for a weekly upgrade pass. Add an automation on the Project with a schedule trigger, a cron for Monday morning in your time zone, and a prompt that first checks Cargo.toml for structopt and stops with a one-line report when it is gone. The first run opens the pull request; later runs find nothing to do.

For several CLIs, keep one automation per Project with the same prompt. Each run works in its own sandbox on its own clone, so they do not wait on each other, and the automation's max runs per hour is the cap on how many start together.

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

Why run it on Rush?

Nothing in a compiler or a unit test suite knows what your program's command line used to accept. The only way to catch a parsing change is to keep the old binary, build the new one, and run the same commands through both. The agent does that in a sandbox where it can hold two builds side by side, and the outputs of both sets of runs are kept, so every row of the table in the pull request points back to commands that were executed.

It is also the kind of upgrade that gets postponed because it has no deadline. As a scheduled run it costs no one an afternoon, and what comes back is not a diff you must trust but a diff with the interface comparison attached and tests that hold the result in place.

Frequently asked questions

Why does my Vec option only take one value after the port?

structopt let a Vec<T> option consume several values after a single flag. clap 4 reads one value per occurrence, so -f a b stops at a and treats b as a stray argument. Add num_args = 1.. to the field to restore the old form; -f a -f b works either way.

Where did --version go?

structopt generated -V and --version from the crate version without being asked. clap 4 derive generates them only when the type has #[command(version)]. The same applies to the author line and the description, which come from Cargo.toml only when you name author and about.

Should I go through clap 3 first?

It is not required. The clap 3 derive is the closest to structopt, since that is where structopt's macro was folded in, and going through it can split the work on a very large CLI. For a program with a handful of derives, porting straight to clap 4 and comparing behaviour is less work than two migrations.

Will the help output be identical?

No. clap 4 uses a different layout and wording, and the agent does not try to rebuild the old text with a custom template unless you ask. It attaches the diff so you can decide, and updates any help text pasted into the README.

More jobs like this: Upgrade dependencies weekly

Keep reading