# Replace minimist With util.parseArgs in a Node.js CLI

Yes. An agent ports a CLI from minimist to Node's built-in util.parseArgs, tests every documented command line before and after, and opens a pull request.

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

## What the agent does

Node has shipped an argument parser of its own, `util.parseArgs`, since version 18, and a small CLI can drop `minimist` for it. The two are not interchangeable, though, and the differences are where the work is. minimist accepts any flag it sees and guesses types; `parseArgs` is strict and treats everything as a string or a boolean that you declared. feross/spoof, a MAC address tool, is a good subject. `bin/cmd.js` calls `minimist(process.argv.slice(2), { alias: { v: 'version' }, boolean: ['version'] })` and then reads `argv._` for the command and its operands, `argv.version`, and two flags the configuration never mentions: `argv.wifi` in `list()` and `argv.local` in `randomize()`.

Before changing anything the agent writes down what the CLI does today, taking its cases from the usage text in `help()`. The existing `test/basic.js` covers only the library functions `spoof.normalize()` and `spoof.randomize()`, so the agent adds tests that spawn `bin/cmd.js`. Two of them expose bugs that come from minimist's guessing. The usage line reads `spoof randomize [--local] <devices>...`, but since `local` is not declared as a boolean, minimist parses `randomize --local en0` as `local: "en0"` with no devices left, and the command exits 0 having done nothing. And minimist turns operands that look numeric into numbers: `spoof normalize 001122334455` prints `11:22:33:44:05:05`, while the library function given the string returns `00:11:22:33:44:55`.

The port itself is short. The agent replaces the call with `parseArgs({ allowPositionals: true, options: { version: { type: 'boolean', short: 'v' }, wifi: { type: 'boolean' }, local: { type: 'boolean' } } })` and builds the old shape from the result, `{ ...values, _: positionals }`, so the rest of the file is untouched. Positionals stay strings, which repairs the `normalize` case, and declared booleans no longer swallow the next word, which repairs `randomize --local en0`. One behaviour changes on purpose and the agent calls it out: an unknown flag such as `--bogus` used to be ignored and now throws `Unknown option '--bogus'`. The agent catches that error and prints it through the script's existing `chalk.red('Error:', ...)` path with a non-zero exit code.

Then it settles the housekeeping. `minimist` comes out of `dependencies`, and the lockfile, if the project has one, is regenerated with npm instead of edited. `package.json` has no `engines` field and `.travis.yml` tests `lts/*`, so the agent adds an `engines` entry naming the first Node line where `parseArgs` is stable and says that this is a support decision for the maintainer to confirm. It runs `npm test`, which is `standard && tape test/*.js`, so the new code also has to satisfy the project's linter.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Replace the minimist dependency in this CLI with Node's built-in util.parseArgs. First record current behaviour: read the usage or help text and every place the parsed result is read, and write tests that run the CLI as a child process for each documented command line, including flags placed before and after positional arguments, short aliases, a numeric-looking positional with leading zeros, and an unknown flag. Run them against the unchanged code and keep the results; mark any case where current behaviour contradicts the usage text. Then port: declare every flag the code reads, including ones minimist accepted without declaration, with its type and short alias, and enable positionals. Keep the shape the rest of the code expects so the diff stays small. Positionals and option values must stay strings; do not reintroduce number coercion. Decide explicitly what an unknown flag does, report the error through the CLI's existing error path with a non-zero exit code, and list every behaviour that differs from before, saying which differences fix a documented command line. Remove minimist from package.json and regenerate the lockfile with the package manager. Set or raise the engines field to the first Node version where util.parseArgs is stable and say so. Run the full test script including the linter. 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 a rewritten parsing block at the top of the CLI script, one dependency fewer, and a new test file that runs the CLI itself. The description has a table of command lines with the result before and after. Most rows are identical. The rows that differ are the reason to read it: in a CLI like spoof, `randomize --local <device>` reaches the device lookup where it used to do nothing, and a twelve-digit MAC address keeps its leading zeros.

Each difference is labelled as a fix for a documented command line or as a deliberate tightening, the unknown-flag error being the main one. If your users have scripts that pass flags the tool silently ignored, that row tells you they will now see an error, and the description suggests `strict: false` as the switch that restores leniency if you want it.

A reviewer checks the declared options against their own knowledge of the tool, since a flag the code reads through a dynamic property name would not show up in a grep, and confirms the `engines` floor. Commands that need a real network interface or root, such as actually setting an address, are exercised only up to the point where they would touch the system, and the description says where each test stops.

## Run it on every Monday morning

Removing small dependencies is steady work that never becomes urgent, which makes it a fit for a schedule. Create an automation in the Project with a `schedule` trigger, for example the cron `0 8 * * 1`, and save a prompt that names this job. Each Monday a run starts in the Project's repository and either opens a pull request or reports that minimist is no longer a direct dependency.

For many repositories, start the runs from your own script with an API key instead: one `POST /o/{org}/sessions` per repository, each with a `request_id` that is a UUID v5 of the repository name and the week, so a script that is run twice starts nothing twice. Runs beyond the key's `max_concurrent` limit wait as `queued` and start as earlier ones finish.

## Why run it on Rush?

The risk in swapping an argument parser is behaviour nobody wrote down, and the way to find it is to run the tool with many command lines before and after. In its own sandbox the agent can execute the CLI as often as it needs, including with inputs that fail, without touching a network interface on a real machine. Every invocation and its output is kept in the session's transcript, so the before and after table in the pull request can be checked against the commands that produced it.

Dependency removal is also work that scales by repetition. One team may own a dozen small command-line tools that each pull in the same parser. Each run has its own machine and its own branch, so the tools can be ported side by side, and each pull request stands alone with its own table of differences. Reviewing twelve short tables is a better use of an afternoon than performing twelve ports by hand.

## Frequently asked questions

### Is util.parseArgs a drop-in replacement for minimist?

No. It needs every option declared, never converts values to numbers, and throws on flags it does not know unless you pass `strict: false`. Those differences are mostly improvements, and each one can change what a given command line does, which is why the agent tests the CLI before and after.

### Which Node.js version do I need?

`util.parseArgs` first appeared in Node 18.3 and was backported to 16.17 as an experimental API, and it is stable from Node 20. The agent sets the `engines` field accordingly and says so in the pull request, since raising the floor is a decision for the maintainer.

### What happens to flags my code reads but never declared?

minimist accepted them silently and guessed whether they took a value. The agent finds every property read from the parsed result, declares each one with a type, and tests it. Flags it cannot find in the code but that users may still pass become errors under strict parsing, and the description lists that as a behaviour change.

### Why keep the argv._ shape instead of rewriting the rest of the script?

To keep the diff reviewable. Building `{ ...values, _: positionals }` from the new parser's result means only the parsing block changes, and every later line reads the same names as before. A wider cleanup can follow in its own pull request.

### Does the agent run commands that need root or change system state?

Its tests stop before that point. A command that would change a network interface is run with a device name that does not exist, which exercises parsing and the lookup and fails safely. Whatever the agent runs happens inside its sandbox, not on your machines.

## More jobs like this: Upgrade dependencies weekly

- [Migrate From mitchellh/mapstructure to go-viper/mapstructure v2](https://getrush.ai/run/migrate-mitchellh-mapstructure-to-go-viper/mapstructure/)
- [Replace the mock Backport With unittest.mock](https://getrush.ai/run/migrate-mock-to-unittest-mock/mock/)
- [Migrate From mysql to mysql2 in a Node.js App](https://getrush.ai/run/migrate-mysql-to-mysql2/mysql/)
- [Migrate from node-sass to Dart Sass in a Webpack Project](https://getrush.ai/run/migrate-node-sass-to-dart-sass/webpack/)
- [Migrate a Python Project From oauth2client to google-auth](https://getrush.ai/run/migrate-oauth2client-to-google-auth/oauth2client/)
- [Migrate From packr to Go's embed Package](https://getrush.ai/run/migrate-packr-to-embed/packr/)

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