Skip to content

Upgrading commander 4 to 5

Breaking4.1.1 → 5.1.0Breaking13Deprecated1New21Changed23Fixed9Other5

Full comparisonBack to commander
BreakingUpgrade verdict

11 breaking changes.

In plain terms
  • The old `args` field is now `operands` and stops at the first unknown option.
  • The `.args` list now keeps unrecognised options instead of stripping them out.
  • The result of `.parseOptions()` now uses `operands` instead of `args`, and `unknown` includes everything after the first unknown option.
  • The Command TypeScript type no longer extends EventEmitter, so you no longer implicitly need `@types/node`.
Must act Top 4 of 12 that need code or config changes

What you must change

Breaking11
args in the .parseOptions() result is renamed operands and excludes anything after the first unknown option.
.parseOptions()parseOptions()operandsunknownargs
5.0.0GitHub ReleaseSummarizedView source
.args now contains command arguments with only recognised options removed.
.args
5.0.0GitHub ReleaseSummarizedView source
.parseOptions() renames args to operands and changes what unknown contains.
.parseOptions()
5.0.0GitHub ReleaseSummarizedView source
Removes EventEmitter from the TypeScript definition for Command, eliminating the implicit peer dependency on @types/node.
CommandEventEmitter
5.0.0GitHub ReleaseSummarizedView source
Removes the private function normalize, whose functionality is integrated into parseOptions.
normalizeparseOptions
5.0.0GitHub ReleaseSummarizedView source
Displays an error if a required argument for a command is missing.
5.0.0GitHub ReleaseSummarizedView source
.allowUnknownOption() now includes unknown options in action handler arguments and in .args.
.allowUnknownOption().args
5.0.0GitHub ReleaseSummarizedView source
Unknown options are included in arguments passed to the command action handler.
5.0.0GitHub ReleaseSummarizedView source
Unknown options are included in .args.
.args
5.0.0GitHub ReleaseSummarizedView source
.on('command:*', callback) and other command events receive changed results from .parseOptions, i.e. operands and unknown.
.on('command:*', callback).parseOptions
5.0.0GitHub ReleaseSummarizedView source
parseExpectedArgs is now private.
parseExpectedArgs
5.0.0GitHub ReleaseSummarizedView source

Deprecations to plan for

Deprecated1
Renames .command() configuration noHelp to hidden, keeping old support.
command()noHelphidden
5.1.0GitHub ReleaseSummarizedView source

API changes

Generated by DepDelta from published .d.ts files. Not mixed with prose notes.

  • removed: method commander.Command.parseExpectedArgs(args: string[]): Command
  • removed: property commander.CommandOptions.executableFile?: string
  • removed: property commander.ParseOptionsResult.args: string[]
  • changed: interface commander.Command extends NodeJS.EventEmitter → interface commander.Command
  • changed: method commander.Command.action(fn: (...args: any[]) => void | Promise<void>): Command → method commander.Command.action(fn: (...args: any[]) => void | Promise<void>): this
  • changed: method commander.Command.alias(alias: string): Command → method commander.Command.alias(alias: string): this
  • changed: method commander.Command.allowUnknownOption(arg?: boolean): Command → method commander.Command.allowUnknownOption(arg?: boolean): this
  • changed: method commander.Command.arguments(desc: string): Command → method commander.Command.arguments(desc: string): this
  • changed: method commander.Command.command(nameAndArgs: string, description: string, opts?: commander.CommandOptions): Command → method commander.Command.command(nameAndArgs: string, description: string, opts?: commander.ExecutableCommandOptions): this
  • changed: method commander.Command.command(nameAndArgs: string, opts?: CommandOptions): Command → method commander.Command.command(nameAndArgs: string, opts?: CommandOptions): ReturnType<this['createCommand']>
  • changed: method commander.Command.description(str: string, argsDescription?: { [argName: string]: string }): Command → method commander.Command.description(str: string, argsDescription?: { [argName: string]: string }): this
  • changed: method commander.Command.exitOverride(callback?: (err: CommanderError) => never|void): Command → method commander.Command.exitOverride(callback?: (err: CommanderError) => never|void): this
  • changed: method commander.Command.helpOption(flags?: string, description?: string): Command → method commander.Command.helpOption(flags?: string, description?: string): this
  • changed: method commander.Command.name(str: string): Command → method commander.Command.name(str: string): this
  • changed: method commander.Command.option(flags: string, description?: string, defaultValue?: any): Command → method commander.Command.option(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean): this
  • changed: method commander.Command.option(flags: string, description?: string, fn?: ((arg1: any, arg2: any) => void) | RegExp, defaultValue?: any): Command → method commander.Command.option(flags: string, description?: string, defaultValue?: string | boolean): this
  • changed: method commander.Command.parse(argv: string[]): Command → method commander.Command.parse(argv?: string[], options?: ParseOptions): this
  • changed: method commander.Command.parseAsync(argv: string[]): Promise<any> → method commander.Command.parseAsync(argv?: string[], options?: ParseOptions): Promise<this>
  • changed: method commander.Command.passCommandToAction(value?: boolean): Command → method commander.Command.passCommandToAction(value?: boolean): this
  • changed: method commander.Command.requiredOption(flags: string, description?: string, defaultValue?: any): Command → method commander.Command.requiredOption(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean): this
  • changed: method commander.Command.requiredOption(flags: string, description?: string, fn?: ((arg1: any, arg2: any) => void) | RegExp, defaultValue?: any): Command → method commander.Command.requiredOption(flags: string, description?: string, defaultValue?: string | boolean): this
  • changed: method commander.Command.storeOptionsAsProperties(value?: boolean): Command → method commander.Command.storeOptionsAsProperties(value?: boolean): this
  • changed: method commander.Command.usage(str: string): Command → method commander.Command.usage(str: string): this
  • changed: method commander.Command.version(str: string, flags?: string, description?: string): Command → method commander.Command.version(str: string, flags?: string, description?: string): this
  • changed: property commander.CommanderStatic.CommanderError:CommanderErrorConstructor → property commander.CommanderStatic.CommanderError: CommanderErrorConstructor
  • changed: type commander.CommandConstructor = { new (name?: string): Command } → type commander.CommandConstructor = new (name?: string) => Command
  • changed: type commander.CommanderErrorConstructor = { new (exitCode: number, code: string, message: string): CommanderError } → type commander.CommanderErrorConstructor = new (exitCode: number, code: string, message: string) => CommanderError
  • changed: type commander.OptionConstructor = { new (flags: string, description?: string): Option } → type commander.OptionConstructor = new (flags: string, description?: string) => Option
  • added: interface commander.ExecutableCommandOptions extends CommandOptions
  • added: interface commander.ParseOptions
  • added: method commander.Command.addCommand(cmd: Command, opts?: CommandOptions): this
  • added: method commander.Command.aliases(): string[]
  • added: method commander.Command.aliases(aliases: string[]): this
  • added: method commander.Command.createCommand(name?: string): Command
  • added: method commander.Command.helpInformation(): string
  • added: method commander.Command.on(event: string | symbol, listener: (...args: any[]) => void): this
  • added: method commander.Command.option<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this
  • added: method commander.Command.requiredOption<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this
  • added: property commander.Command.commands: Command[]
  • added: property commander.CommandOptions.hidden?: boolean
  • added: property commander.CommanderStatic.program: Command
  • added: property commander.ExecutableCommandOptions.executableFile?: string
  • added: property commander.ParseOptions.from: 'node' | 'electron' | 'user'
  • added: property commander.ParseOptionsResult.operands: string[]