76 curated breaking changes across major versions of commander. Use this as a migration checklist before bumping dependencies.
update package-lock.json to lockfile@2 format (#1659)
`showSuggestionAfterError` is now on by default (#1657)
use command name as prefix for subcommand stand-alone executable name (with fallback to script name for backwards compatibility) (#1571)
*Breaking:* default value specified for boolean option now always used as default value (see .preset() to match some previous behaviours) (#1652)
default value for boolean option only shown in help if true/false (#1652)
update package-lock.json to lockfile@2 format (#1659)
`showSuggestionAfterError` is now on by default (#1657)
*Breaking:* default value specified for boolean option now always used as default value (see .preset() to match some previous behaviours) (#1652)
default value for boolean option only shown in help if true/false (#1652)
use command name as prefix for subcommand stand-alone executable name (with fallback to script name for backwards compatibility) (#1571)
*Breaking:* `CommanderError` code `commander.invalidOptionArgument` renamed `commander.invalidArgument` (#1508)
*Breaking:* TypeScript declaration for `.addTextHelp()` callback no longer allows result of `undefined`, now just `string` (#1516)
refactor `index.tab` into a file per class (#1522)
*Breaking:* Commander 8 requires Node.js 12 or higher (#1500)
remove help suggestion from "unknown command" error message (see `.showHelpAfteError()`) (#1534)
*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)
update example to use compatible character for MINGW64 (#2475)
internal refactor of `Help` class adding `.formatItemList()` and `.groupItems()` methods (#2328)
TypeScript: include implicit `this` in parameters for action handler callback (#2197)
*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)
*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)
*Breaking:* throw an error if add a command with name or alias which is already in use (#2059)
*Breaking:* check `passThroughOptions` constraints when using `.addCommand` and throw if parent command does not have `.enablePositionalOptions()` enabled (#1937)
*Breaking:* throw an error if add an option with a flag which is already in use (#2055)
replace non-standard JSDoc of `@api private` with documented `@private` (#1949)
*Breaking:* throw error when calling `.storeOptionsAsProperties()` after setting an option value (#1928)
*Breaking:* throw error when calling `.storeOptionsAsProperties()` after setting an option value (#1928)
*Breaking:* throw an error if add an option with a flag which is already in use (#2055)
*Breaking:* check `passThroughOptions` constraints when using `.addCommand` and throw if parent command does not have `.enablePositionalOptions()` enabled (#1937)
replace non-standard JSDoc of `@api private` with documented `@private` (#1949)
*Breaking:* throw an error if add a command with name or alias which is already in use (#2059)
*Breaking:* removed internal fallback to `require.main.filename` when script not known from arguments passed to `.parse()` (can supply details using `.name()`, and `.executableDir()` or `executableFile`) ([#1571])
*Breaking:* TypeScript declaration for default export of global `Command` object ([#1520])
(still available as named `program` export)
allow restricting option arguments to a list of choices
`.allowExcessArguments(false)` to show an error message if there are too many command-arguments on command line for the action handler ([#1409])
revert behaviour with `.storeOptionsAsProperties()`
allow setting how default value is shown in help
*Breaking:* options are stored safely by default, not as properties on the command ([#1409])
allow hiding options from help
support sorting subcommands and options in help
support specifying wrap width (columns)
allow subclassing Help class
allow configuring Help class without subclassing
`.enablePositionalOptions()` to let program and subcommand reuse same option ([#1427])
`.passThroughOptions()` to pass options through to other programs without needing `--` ([#1427])
`.configureOutput()` to modify use of stdout and stderr or customise display of errors ([#1387])
use `.addHelpText()` to add text before or after the built-in help, for just current command or also for all subcommands ([#1296])
enhance Option class ([#1331])
refactor the code generating the help into a separate public Help class ([#1365])
`.createOption()` to support subclassing of automatically created options (like `.createCommand()`) ([#1380])
this especially affects accessing options on program, use `program.opts()`
*Breaking:* action handlers are passed options and command separately ([#1409])
*Breaking:* errors now displayed using `process.stderr.write()` instead of `console.error()`
initialise the command description to empty string (previously undefined) ([#1365])
wrapping bugs in help ([#1365])
document and annotate deprecated routines ([#1349])
deprecate `.on('--help')` (removed from README) ([#1296])
deprecated callback parameter to `.help()` and `.outputHelp()` (removed from README) ([#1296])
TypeScript: add `parseArg` property to `Argument` class ([#2359])
support for unescaped negative numbers as option-arguments and command-arguments ([#2339])
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 options/commands ([#2328])
internal refactor of `Help` class adding `.formatItemList()` and `.groupItems()` methods ([#2328])
*Breaking:* Commander 14 requires Node.js v20 or higher
`.configureOutput()` now makes copy of settings instead of modifying in-place, fixing side-effects ([#2350])
remove bogus leading space in help when option has default value but not a description ([#2348])
*Breaking:* removed default export of a global Command instance from CommonJS (use the named `program` export instead) ([#2017])
leading and trailing spaces are now ignored by the .arguments() method ([#1874])
*Breaking:* Commander 11 requires Node.js v16 or higher
refine "types" exports for ESM to follow TypeScript guidelines ([#1886])
help command works when help option is disabled ([#1864])
wrap command description in help ([#1804])
*Breaking:* Commander 10 requires Node.js v14 or higher
Get this data programmatically \u2014 free, no authentication.
curl https://depscope.dev/api/breaking/npm/commander