# Upgrade Commander.js From v3 to the Latest Version in a Node CLI

Yes. An agent moves a CLI off commander 3: options read through opts(), the named program import, declared arguments, on a major your Node can run.

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

## What the agent does

A CLI written against commander 2 or 3 reads its flags straight off the program object, `program.port`, `program.host`, and every later major has moved away from that. The agent starts by measuring the distance. In a tool like mthenw/frontail, `package.json` pins `"commander": "3.0.1"`, `lib/options_parser.js` builds the program from `require('commander')` with eighteen `.option()` calls and exports it, and `index.js` reads seventeen different properties from it, from `program.args` and `program.urlPath` to `program.uiHighlightPreset`. The same object is passed whole to `lib/daemonize.js`, which rebuilds a command line from `params.host`, `params.port` and the rest, and to `lib/stats.js`, which reads `opts.number`.

It runs the suite first to have a baseline: `npm test` is `mocha -r should --exit test/*.js`, 57 passing on the pinned version. Then it installs the newest commander and runs it again. The failures arrive in layers. The first is `TypeError: program.version is not a function`, because the package no longer exports a ready-made program as its default; the fix is `const { program } = require('commander')`. With that in place, most of `test/daemonize.js` fails, because options are no longer stored as properties and `params.host` is now `undefined`. And partway through, the mocha process exits with `error: too many arguments. Expected 0 arguments but got 1`, because a test passes a file name and the program never declared that it takes any.

The agent tries the smallest change first and reports why it is not enough. Commander offers `.storeOptionsAsProperties()` to keep the old behaviour, and with it the tests fail a different way: `Can not call parse again when storeOptionsAsProperties is true`, since the tests parse the shared program many times. So it does the real port. `options_parser.js` gains `.argument('[file...]')`, and each consumer takes a plain object built from `program.opts()` plus `program.args`, in `index.js` once near the top and in the tests at each `daemonize('script', ...)` call. The four-argument option form used here, `.option('-p, --port <port>', 'listening port, default 9001', Number, 9001)`, still parses, and `--port 80` still yields the number 80.

Last comes the version, which the manifest cannot decide alone. The newest commander is an ES module that requires Node 22.12 or later, and this repository runs on Node 12 in three places: `FROM node:12-buster-slim` in the `Dockerfile`, `node-version: 12` in `.github/workflows/push.yml`, and the `node12-*` targets in the `pkg` block of `package.json`. The newest major whose `engines` field admits Node 12 is commander 9. The agent runs the ported code against both: 57 passing on 9.5.0 and 57 passing on the newest. It pins the one the declared Node can run and states what raising Node would allow. It also reports one thing it found and left alone: `index.js` and `daemonize.js` test `program.uiIndent`, a property no commander version in this range sets for the `--ui-no-indent` flag, before or after the upgrade.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Upgrade commander in this repository from its current major to the newest one this project can run. Read package.json and the lockfile for the installed version, then find where the program is built and every place options are read: properties on the program object, program.args, and any function the program object is passed to. Run the test suite on the current version and record the result. Install the newest commander and run it again; fix failures one layer at a time and quote each error before fixing it. Use the named program import, read options through opts(), declare positional arguments, and keep every flag, default and coercion exactly as it is; do not rename a flag or change a default. Try storeOptionsAsProperties only to learn whether it is sufficient, and do not ship it if the proper port is feasible. Decide the target major from the Node version this repository declares in its Dockerfile, CI workflow, engines field and any packaging config: choose the newest commander whose engines range admits that Node, run the suite on it, and also run the suite on the newest commander to show the port is forward compatible. Do not raise the Node version. Compare the --help output before and after and list any difference. Report any option the code reads that the parser never sets, without changing behaviour. Update the lockfile with the repository's package manager and 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 that touches `package.json`, `package-lock.json`, `lib/options_parser.js`, `index.js`, and `test/daemonize.js`. The description lists the three errors in the order they appeared, each with the change that cleared it, and gives the test counts: the baseline on the old version, the failures on the new one before the port, and the passing run after.

It contains a short table of commander majors against the Node version each requires, taken from the registry, with the row the project's Node selects. A maintainer who wants the newest commander sees exactly which three files pin Node 12 and can decide to raise it in a separate change. The diff of `--help` output is included too. Here the options and their defaults are the same in both, and the only difference is that the newer version wraps long description lines.

A reviewer should run the CLI by hand once with a real log file, because the suite covers `daemonize`, the server builder and the tailer and never executes `index.js` end to end. The description says which paths were covered by tests and which by a manual invocation in the sandbox.

## Run it on every Monday morning

Give a Project that holds your CLI an automation with this prompt and a `schedule` trigger, such as `every` set to `1d` or a weekly `cron`. Most weeks the run finds the dependency current and ends without a pull request. When a new major lands, it does the port while the breaking changes are one release deep instead of twelve.

A team with many small CLIs can start the same job across all of them from a script: one `POST /o/{org}/sessions` for each repository with the body above. Send a `request_id` that is a UUID v5 of the repository name and the week, so a script that is run twice starts each upgrade once.

## Why run it on Rush?

A jump of a dozen majors fails in layers, and each layer hides the next. Working through them means installing, running the suite, reading one error, fixing it and running again, several times over. The agent does that loop in its own sandbox and keeps the output of every pass, so the pull request can show the path from the first `TypeError` to a green run and a reviewer can see that no failure was skipped.

The sandbox also makes the version question cheap to answer with evidence. The agent installs two different majors in turn and runs the same tests on each. On a laptop that usually means a dirty lockfile and a half-finished branch; in a run it is two more commands in a transcript.

## Frequently asked questions

### Why is `program.port` `undefined` after I upgraded commander?

Since commander 7, option values are no longer stored as properties on the command. Read them from `program.opts()`, for example `const options = program.opts()` and then `options.port`. Positional arguments are still on `program.args`.

### Can I use storeOptionsAsProperties() and skip the port?

For a program that parses once, it works. It fails with current commander when the same program is parsed more than once, which is what test suites do. An option whose name matches a method on the command, such as `name` or `version`, also collides in that mode. The agent tries it, reports the result, and does the port.

### Which commander version should I target?

The newest major whose `engines` range includes the Node version you ship on. The newest commander needs Node 22.12 or later and is an ES module. The agent reads your Dockerfile, CI workflow and `engines` field and picks accordingly.

### Will my flags or help text change?

Flags, defaults and coercion functions are kept as they are, and the prompt forbids renaming. Help text can differ slightly between majors, for example in where long lines wrap. The pull request includes the before and after of `--help` so you can check.

## More jobs like this: Upgrade dependencies weekly

- [Upgrade Filament and Composer Dependencies](https://getrush.ai/run/upgrade-composer-dependencies/filament/)
- [Upgrade Cypress to the Current Major Version](https://getrush.ai/run/upgrade-cypress/cypress/)
- [Upgrade dbt and Its Packages](https://getrush.ai/run/upgrade-dbt-packages/dbt/)
- [Upgrade ASP.NET Core Dependencies Every Week](https://getrush.ai/run/upgrade-dependencies-weekly/aspnet-core/)
- [Upgrade Astro Dependencies Every Week](https://getrush.ai/run/upgrade-dependencies-weekly/astro/)
- [Upgrade Django Dependencies Every Week](https://getrush.ai/run/upgrade-dependencies-weekly/django/)

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