v6.0.0

This is a non-functional release intended to refresh the codebase and dependency tree. There are no changes to the library's API or behaviour.

Breaking changes since 5.2.1

• Dropped support for Node versions less than v12.20

Misc other improvements

• The package is now a native ES6 module while still maintaining support for CommonJS
• All dependencies updated to their latest version

Upgrade Notes

• If you're using Node v12.20 or above it's safe to upgrade with zero changes to your code.
• Users of older versions of Node should stick with command-line-args v5.2.1.

v5.2.0

New features since v5.1.3

• Added options.caseInsensitive, see #116 and the docs.

v5.1.0

New features since v5.0.2

Library rewritten using ECMAScript Modules to facilitate use with rollup and --experimental-modules. Fixes #99. This is a non-functional change - the library API and functionality has not changed.

• How to use with native ECMAScript modules
• How to use with rollup

v5.0.0

Breaking changes from v4.0.7

• Unknown values now throw an exception (UNKNOWN_VALUE) by default in the same way unknown options do. Command-line-args is now strict by default - all options and values must be accounted for in the option definitions.
  • An example of an unknown value is the arg 5 in the command --verbose 5 where verbose is defined as a Boolean.
  • "Strict by default" behaviour can be disabled using either partial or stopAtFIrstUnknown parse options.
• Setting a singular, non-multiple option more than once (e.g. --help --help) now throws an ALREADY_SET exception.
• The multiple error names (NAME_MISSING, INVALID_TYPE etc) thrown by commandLineArgs in the case of an invalid definition have been consolidated to just one error name: INVALID_DEFINITIONS. Given broken option definitions are a programmer error they'd never be handled anyway, making the various names pointless.

New documentation

Wiki introduced.

New parse features

• stopAtFirstUnknown
• camelCase
• the UNKNOWN_OPTION exception now has a optionName property containing the arg that specified an unknown option, e.g. --one
• the ALREADY_SET exception has a optionName property containing the option name that has already been set, e.g. one
• the UNKNOWN_VALUE exception has a value property containing the unknown value, e.g. 5

New option definition features

• lazyMultiple

Bug fixes

• #67 unknown "--option=value notation" value consumed as defaultOption
• #68 unknown --option=value arg split when defaultOption set

Upgrade notes

No API changes were introduced in v5.0.0 - it is backward-compatible. If you're comfortable with the new version throwing exceptions on unknown values, you are safe to upgrade without code change.

v4.0.0

Breaking changes since v3.0.5

• Removed support for node versions less than v4.0.0

• The method signature changed. If you're passing a custom argv you now do it this way:

  const argv = [ '--log-level', 'info' ]
  commandLineArgs(optionDefinitions, { argv })

  Previously, it was done this way:

  const argv = [ '--log-level', 'info' ]
  commandLineArgs(optionDefinitions, argv)

• String is the new default type function.

If all the following are true then no changes are required to your code

• Your app does not need to run on old nodejs versions
• You don't pass a custom argv
• All your option definitions have a type specified

New feature

• Partial parsing - support for unknown options. See the docs and issue 25 for background.

Other changes

• Fixed #24, #39
• Overhauled the examples
• Refactored internals
• More tests added

v3.0.0

Breaking changes since v2

The command-line-usage library evolved recently, it is now more flexible with a new API. As its API changed i found myself needing to update the .getUsage() method of this library, causing a breaking change. Rather than update this library each time command-line-usage changes, i separated them completely. Therefore, the .getUsage() method has been removed and the .parse() method is now exported directly.

So, the API has changed from

const commandLineArgs = require('command-line-args')
const cli = commandLineArgs([ { name: 'version' } ])
const options = cli.parse()

to the more concise

const commandLineArgs = require('command-line-args')
const options = commandLineArgs([ { name: 'version' } ])

The data you previously passed to .getUsage() you should pass to command-line-usage v2, like so:

const commandLineUsage = require('command-line-usage')
const usage = commandLineUsage(templateData)

For details about command-line-usage, including the new v3, see the project page.

v2.1.0

new features

• upgraded .getUsage to use command-line-usage v2.0.0, which features column-layout, the header field and other template improvements
• commandLineArgs(definitions) will now throw if you added defaultOption to more than one definition

v2.0.0

Breaking change since v1.0.0

• Numeric aliases are no longer valid as -1 could be interpreted as both minus 1 and option 1.

Other changes

• unicode option names (e.g. --один) are now valid
• improved error handling
  • all exceptions thrown now have names to aid distinction
  • more validation rules added to catch issues with the supplied option definitions
• updated docs
• the codebase is now ES6 (with babel-compiled ES5 fallback) and will run natively where possible