# Migrate a Python CLI From optparse to argparse

Yes. An agent ports each option to argparse, compares help text, parsed values and exit codes with the old parser, and opens a PR listing every difference.

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

## What the agent does

The agent reads the parser as a contract before it rewrites it. In a downloader like everdrone/nts, `nts/cli.py` builds one `OptionParser` with the usage string `Usage: %prog [options] args` and four options: `-o`/`--out-dir` with `type="string"` and `metavar="DIR"`, and three `store_true` flags, `-v`/`--version`, `-q`/`--quiet` and `-a`/`--albumize`. `parser.parse_args()` returns the options and a list of leftover arguments, which the command treats as URLs or files of URLs. With no arguments it prints a message and the help and exits with status 1. `setup.py` installs the function as the `nts` console script.

Before changing code it captures the old behaviour as data. It runs the existing command with `--help`, `--version`, no arguments, an unknown option, an option missing its value, and options placed between positional arguments, and saves each output and exit status. The repository has no tests, so this table is the safety net, and the agent turns it into a small pytest file that drives the parser directly.

The port is mostly renaming: `ArgumentParser`, `add_argument`, `type=str` or nothing in place of `type="string"`, and a positional `nargs="*"` argument for the URLs. The differences that bite are in the details. argparse runs every help string through `%` formatting, and the `--out-dir` help mentions `%USERPROFILE%\Downloads`, so an unescaped port raises `ValueError: unsupported format character 'U'` the moment a user asks for `--help`; it needs `%%`. The usage string must use `%(prog)s` and lose its `Usage: ` prefix, which argparse adds itself. And where optparse accepts `nts -q first.txt -a second.txt`, argparse's `parse_args()` rejects the second positional as unrecognized; `parse_intermixed_args()` restores the old behaviour.

Then it decides what to keep on purpose. The hand-written `--version` branch becomes `action="version"` with the version read from `nts/downloader.py`, which prints the same line and exits 0. The no-arguments check stays as written, with `nargs="*"`, because switching to `nargs="+"` would change the exit status from 1 to argparse's 2 and replace the project's message. The agent reruns the table against the new parser and reports each row as same or different.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Migrate this command-line tool from optparse to argparse without changing how users call it. Find every OptionParser, add_option, parse_args, OptionGroup, callback action and use of parser.error or print_help. Before editing, run the existing command with: --help, the version flag, no arguments, an unknown option, an option that needs a value without one, options placed before, between and after positional arguments, and a literal -- followed by an argument that starts with a dash. Save each stdout, stderr and exit status as a table. Port the parser to argparse. Keep every option string, dest, default and metavar. Escape literal percent signs in help strings and convert %prog and %default to argparse's %(prog)s and %(default)s. Turn leftover positional arguments into a declared positional argument, and choose nargs so that the behaviour with zero arguments, including the message and exit status, stays what it was. If the old parser accepted options interleaved with positionals, use parse_intermixed_args. Convert a hand-written version flag to action='version' only if the output and exit status stay the same. Add tests that call the parser with each case in the table. Run the table again against the new parser and report every row as same or different, with the old and new output for the different ones. Update any help text pasted into the README. Do not change option names, add subcommands or fix unrelated bugs; list those instead. 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

A pull request with the rewritten parser, a new test file, and a README change. The README matters here because nts pastes its help output into `readme.md`, and argparse lays help out differently: a lowercase `usage:` line, an `options:` heading, `--out-dir DIR` in place of `--out-dir=DIR`, and a section for the positional argument. The agent regenerates that block from the new parser and does not hand-edit it.

The description holds the before and after table. Most rows read same. The rows that differ are named with both outputs, so the reviewer decides whether each is acceptable. One example is a literal `--` followed by a dash-prefixed argument: optparse hands it through as a positional, and on Python 3.11 `parse_intermixed_args()` reports it as unrecognized. That is an edge most tools never hit, and it is the reviewer's call, not something to discover after release.

The agent also lists what it noticed and did not touch. In `cli.py` the Windows default for the download directory is assigned and then overwritten two lines later, and `os.path.abspath` is applied to the raw option so the `expanduser` result above it is discarded. Both predate the migration and both would change behaviour if fixed, so they go in the description as findings.

## Run it on every repository that still imports optparse

An organisation with many internal scripts can do this as a batch from a terminal. Search your code host for `from optparse import`, then start one run per repository with this request and that repository's URL in `resources`. From an MCP client such as Claude Code or Cursor connected to Rush's MCP server, that is one `create_session` call per repository followed by `wait_for_sessions`, which waits up to 50 seconds per call for one or several sessions to settle.

An API key runs at most its `max_concurrent` runs at once, 4 by default, within the plan limit of the member who created it. Runs past that are still accepted with status `queued` and start in order as slots free, so the batch needs no retry loop. Send a `request_id` that is a UUID v5 of the repository name with each start, and a script that is interrupted and run again gets the runs it already started back instead of duplicates.

## Why run it on Rush?

A parser migration is easy to write and tedious to verify, because the contract is the command's behaviour under every odd invocation and nobody remembers all of them. The run does the tedious part: it executes the old command and the new one in its own sandbox, case by case, and the transcript keeps both outputs. The `%USERPROFILE%` crash is a good example of what that catches. Nothing fails at import or in normal use; only `--help` breaks, and a reviewer reading the diff would likely not see it.

Handing this off from a terminal also fits the size of the job. It is too small to schedule and too fiddly to do well between other tasks, and there are usually several such scripts. Each run works on one repository in isolation, installs that project's own dependencies, and comes back with a pull request and a table, so reviewing ten of them is ten short reads.

## Frequently asked questions

### Is optparse going away?

It still imports without a warning on current Python, so nothing forces the move today. The reasons to migrate are practical: argparse handles positional arguments, subcommands and required options itself, and tools that generate shell completion or documentation generally read argparse parsers. The agent does the port when you ask for it and does not present it as urgent.

### Will my users have to change how they call the tool?

The prompt forbids it, and the before and after table is how that is checked. Option names, defaults and exit statuses for the tested cases stay the same. The differences that remain, usually help layout and one or two edge cases around `--`, are listed in the pull request for you to accept or reject.

### What happens to optparse callback actions?

argparse has no `callback` action. A callback that validates or converts a value becomes a `type=` function, and one with side effects becomes a custom `Action` subclass. The agent ports each one individually and adds a test for it, since callbacks are where the two libraries differ most.

### Does it handle abbreviated long options?

Both parsers accept an unambiguous prefix such as `--out` for `--out-dir`, so existing abbreviations keep working. The agent includes one abbreviated call in its table to confirm that for your options, and mentions `allow_abbrev=False` only as an option you could choose later.

## More jobs like this: Hand off a long task

- [Migrate a grammY Bot From Long Polling to Webhooks](https://getrush.ai/run/migrate-polling-to-webhooks/grammy/)
- [Migrate Puppeteer Scripts to Playwright](https://getrush.ai/run/migrate-puppeteer-to-playwright/puppeteer/)
- [Migrate a SolidJS App from Rollup to Vite](https://getrush.ai/run/migrate-rollup-to-vite/solidjs/)
- [Migrate a Python Project from setup.py to pyproject.toml](https://getrush.ai/run/migrate-setup-py-to-pyproject/python/)
- [Move a Slack Bolt App From Socket Mode to HTTP](https://getrush.ai/run/migrate-socket-mode-to-http/slack-bolt/)
- [Migrate an Echo and GORM API From SQLite to Postgres](https://getrush.ai/run/migrate-sqlite-to-postgres/echo/)

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