# Commander.js changelog

> Command-line interface builder for Node — options, subcommands and help output.

- Vendor: Commander.js
- Category: Frameworks & Libraries
- Official site: https://github.com/tj/commander.js
- Tracked by: What's New (https://whatsnew.fyi/product/commander-js)
- Harvested from: GitHub (tj/commander.js)
- Entries below: 10 (newest first)

What's New is an index, not a publisher: every entry below links to the vendor's own release notes, which are the authoritative source. Entries are labelled where they are hand-curated sample data, pre-releases, or drawn from a secondary source such as a developer blog.

## Releases

### v15.0.0

- Date: 2026-05-29
- Version: v15.0.0
- Original notes: https://github.com/tj/commander.js/releases/tag/v15.0.0
- Permalink: https://whatsnew.fyi/product/commander-js/releases/v15.0.0

Commander 15 is ESM only. This is expected to be seamless for ESM consumers, but some CommonJS consumers may hit issues with tooling requiring configuration for ESM-only dependencies. See Migration Tips below.

The release of Commander 15 moves Commander 14 into maintenance. Commander 14 will get security updates for
12 months (to May 2027). For more info see [Release Policy](https://github.com/tj/commander.js/blob/v15.0.0/docs/release-policy.md).

###### Added

- show excess command-arguments in error message (#2384)

###### Fixed

- *Breaking:* only lone `--no-*` option sets default option value to `true`, default not implicitly set when define both positive and negative option in either order (#2405)
- update example to use compatible character for MINGW64 (#2475)

###### Changed

- *Breaking:* migrated Commander implementation from CommonJS to ESM (#2464)
- *Breaking:* Commander 15 requires Node.js v22.12.0 or higher (for `require(esm)`).
- dev: switch tests from Jest to `node:test` test runner (#2463)

###### Deleted

- *Breaking:* removed deprecated export of `commander/esm.mjs` (#2464)

###### Migration Tips

Commander 15 is ESM only, but this does not mean you need to migrate to ESM to use it. Importing ESM from CommonJS is
supported by Node.js, and Bun, and Deno. Hopefully it Just Works for you! However, you may be using a different runtime or
some other part of your setup that may not yet natively support importing ESM from CommonJS, such as your testing framework
or bundler.

If you have problems using Commander 15 in your environment, one option is stay on Commander 14 for now. Commander 14 will
get security updates until May 2027 and things will hopefully improve for your setup in the meantime.

### v15.0.0-0

- Date: 2026-02-21
- Version: v15.0.0-0
- Original notes: https://github.com/tj/commander.js/releases/tag/v15.0.0-0
- Permalink: https://whatsnew.fyi/product/commander-js/releases/v15.0.0-0
- Labels: Pre-release

Commander 15 is ESM only. This is expected to be seamless for ESM consumers, but some CommonJS consumers may hit issues with tooling requiring configuration for ESM-only dependencies. See Migration Tips below.

The release of Commander 15 in May 2026 will move Commander 14 into maintenance. Commander 14 will get security updates for 
12 months (to May 2027). For more info see [Release Policy](https://github.com/tj/commander.js/blob/master/docs/release-policy.md).

###### Added

- show excess command-arguments in error message (#2384)

###### Fixed

- *Breaking:* only lone `--no-*` option sets default option value to `true`, default not implicitly set when define both positive and negative option in either order (#2405)
- update example to use compatible character for MINGW64 (#2475)

###### Changed

- *Breaking:* migrated Commander implementation from CommonJS to ESM (#2464)
- *Breaking:* Commander 15 requires Node.js v22.12.0 or higher (for `require(esm)`).
- dev: switch tests from Jest to `node:test` test runner (#2463)

###### Deleted

- *Breaking:* removed deprecated export of `commander/esm.mjs` (#2464)

###### Migration Tips

Commander 15 is ESM only, but this does not mean you need to migrate to ESM to use it. Importing ESM from CommonJS is
supported by Node.js, and Bun, and Deno. Hopefully it Just Works for you! However, you may be using a different runtime or
some other part of your setup that may not yet natively support importing ESM from CommonJS, such as your testing framework
or bundler.

If you have problems using Commander 15 in your environment, one option is stay on Commander 14 for now. Commander 14 will
get security updates until May 2027 and things will hopefully improve for your setup in the meantime.

To allow `require(esm)` from CommonJS you may be able to make small changes to your current setup. Some
examples for Jest are included in [examples/using-esm-from-commonjs](https://github.com/tj/commander.js/tree/release/15.x/examples/using-esm-from-commonjs).
(Commander was using Jest, so we have a special interest.)

### v14.0.3

- Date: 2026-01-31
- Version: v14.0.3
- Original notes: https://github.com/tj/commander.js/releases/tag/v14.0.3
- Permalink: https://whatsnew.fyi/product/commander-js/releases/v14.0.3

###### Added

- Release Policy document (#2462)

###### Changes

- old major versions now supported for 12 months instead of just previous major version, to give predictable end-of-life
 date (#2462)
- clarify typing for deprecated callback parameter to `.outputHelp()` (#2427)
- simple readability improvements to README (#2465)

### v14.0.2

- Date: 2025-10-25
- Version: v14.0.2
- Original notes: https://github.com/tj/commander.js/releases/tag/v14.0.2
- Permalink: https://whatsnew.fyi/product/commander-js/releases/v14.0.2

###### Changed

- improve negative number auto-detection test (#2428)
- update (dev) dependencies

### v14.0.1

- Date: 2025-09-12
- Version: v14.0.1
- Original notes: https://github.com/tj/commander.js/releases/tag/v14.0.1
- Permalink: https://whatsnew.fyi/product/commander-js/releases/v14.0.1

###### Fixed

- broken markdown link in README (#2369)

###### Changed

- improve code readability by using optional chaining (#2394)
- use more idiomatic code with object spread instead of `Object.assign()` (#2395)
- improve code readability using `string.endsWith()` instead of `string.slice()` (#2396)
- refactor `.parseOptions()` to process args array in-place (#2409)
- change private variadic support routines from `._concatValue()` to `._collectValue()` (change code from `array.concat()` to `array.push()`) (#2410)
- update (dev) dependencies

### v14.0.0

- Date: 2025-05-18
- Version: v14.0.0
- Original notes: https://github.com/tj/commander.js/releases/tag/v14.0.0
- Permalink: https://whatsnew.fyi/product/commander-js/releases/v14.0.0

###### Added

- support for groups of options and commands in the help using low-level `.helpGroup()` on `Option` and `Command`, and higher
-level `.optionsGroup()` and `.commandsGroup()` which can be used in chaining way to specify group title for following option
s/commands (#2328)
- support for unescaped negative numbers as option-arguments and command-arguments (#2339)
- TypeScript: add `parseArg` property to `Argument` class (#2359)

###### Fixed

- remove bogus leading space in help when option has default value but not a description (#2348)
- `.configureOutput()` now makes copy of settings instead of modifying in-place, fixing side-effects (#2350)

###### Changed

- *Breaking:* Commander 14 requires Node.js v20 or higher
- internal refactor of `Help` class adding `.formatItemList()` and `.groupItems()` methods (#2328)

### v13.1.0

- Date: 2025-01-20
- Version: v13.1.0
- Original notes: https://github.com/tj/commander.js/releases/tag/v13.1.0
- Permalink: https://whatsnew.fyi/product/commander-js/releases/v13.1.0

###### Added

- support a pair of long option flags to allow a memorable shortened flag, like `.option('--ws, --workspace')` (#2312)

### v13.0.0

- Date: 2024-12-30
- Version: v13.0.0
- Original notes: https://github.com/tj/commander.js/releases/tag/v13.0.0
- Permalink: https://whatsnew.fyi/product/commander-js/releases/v13.0.0

###### Added

- support multiple calls to `.parse()` with default settings (#2299)
- add `.saveStateBeforeParse()` and `.restoreStateBeforeParse()` for use by subclasses (#2299)
- style routines like `styleTitle()` to add color to help using `.configureHelp()` or Help subclass (#2251)
- color related support in `.configureOutput()` for `getOutHasColors()`, `getErrHasColors()`, and `stripColor()` (#2251)
- Help property for `minWidthToWrap` (#2251)
- Help methods for `displayWidth()`, `boxWrap()`, `preformatted()` et al (#2251)

###### Changed

- *Breaking*: excess command-arguments cause an error by default, see migration tips (#2223)
- *Breaking*: throw during Option construction for unsupported option flags, like multiple characters after single `-` (#2270)
- *Breaking*: throw on multiple calls to `.parse()` if `storeOptionsAsProperties: true` (#2299)
- TypeScript: include implicit `this` in parameters for action handler callback (#2197)

###### Deleted

- *Breaking*: `Help.wrap()` refactored into `formatItem()` and `boxWrap()` (#2251)

###### Migration Tips

**Excess command-arguments**

It is now an error for the user to specify more command-arguments than are expected. (`allowExcessArguments` is now false by default.)

Old code:

```js
program.option('-p, --port <number>', 'port number');
program.action((options) => {
  console.log(program.args);
});
```

Now shows an error:

```console
$ node example.js a b c
error: too many arguments. Expected 0 arguments but got 3.
```

You can declare the expected arguments. The help will then be more accurate too. Note that declaring
new arguments will change what is passed to the action handler.

```js
program.option('-p, --port <number>', 'port number');
program.argument('[args...]', 'remote command and arguments'); // expecting zero or more arguments
program.action((args, options) => {
  console.log(args);
});
```

Or you could suppress the error, useful for minimising changes in legacy code.

```js
program.option('-p, --port', 'port number');
program.allowExcessArguments();
program.action((options) => {
  console.log(program.args);
});
```

### v13.0.0-0

- Date: 2024-12-06
- Version: v13.0.0-0
- Original notes: https://github.com/tj/commander.js/releases/tag/v13.0.0-0
- Permalink: https://whatsnew.fyi/product/commander-js/releases/v13.0.0-0
- Labels: Pre-release

###### Added

- style routines like `styleTitle()` to add color to help using `.configureHelp()` or Help subclass (#2251)
- color related support in `.configureOutput()` for `getOutHasColors()`, `getErrHasColors()`, and `stripColor()` (#2251)
- Help property for `minWidthToWrap` (#2251)
- Help methods for `displayWidth()`, `boxWrap()`, `preformatted()` et al (#2251)

###### Changed

- *Breaking*: excess command-arguments cause an error by default, see migration tips (#2223)
- *Breaking*: throw during Option construction for unsupported option flags, like multiple characters after single `-` (#2270)
- TypeScript: include implicit `this` in parameters for action handler callback (#2197)

###### Deleted

- *Breaking*: `Help.wrap()` refactored into `formatItem()` and `boxWrap()` (#2251)


###### Migration Tips

**Excess command-arguments**

It is now an error for the user to specify more command-arguments than are expected. (`allowExcessArguments` is now false by default.)

Old code:

```js
program.option('-p, --port <number>', 'port number');
program.action((options) => {
  console.log(program.args);
});
```

Now shows an error:

```console
$ node example.js a b c
error: too many arguments. Expected 0 arguments but got 3.
```

You can declare the expected arguments. The help will then be more accurate too. Note that declaring
new arguments will change what is passed to the action handler.

```js
program.option('-p, --port <number>', 'port number');
program.argument('[args...]', 'remote command and arguments'); // expecting zero or more arguments
program.action((args, options) => {
  console.log(args);
});
```

Or you could suppress the error, useful for minimising changes in legacy code.

```js
program.option('-p, --port', 'port number');
program.allowExcessArguments();
program.action((options) => {
  console.log(program.args);
});
```

### v12.1.0

- Date: 2024-05-18
- Version: v12.1.0
- Original notes: https://github.com/tj/commander.js/releases/tag/v12.1.0
- Permalink: https://whatsnew.fyi/product/commander-js/releases/v12.1.0

###### Added

- auto-detect special node flags `node --eval` and `node --print` when call `.parse()` with no arguments (#2164)

###### Changed

- prefix require of Node.js core modules with `node:` (#2170)
- format source files with Prettier (#2180)
- switch from StandardJS to directly calling ESLint for linting (#2153)
- extend security support for previous major version of Commander (#2150)

###### Removed

- removed unimplemented Option.fullDescription from TypeScript definition (#2191)