Skip to content
Switch branches/tags
Go to file


Failed to load latest commit information.
Latest commit message
Commit time

view on npm npm module downloads Gihub repo dependents Gihub package dependents Build Status Coverage Status js-standard-style

Upgraders, please read the release notes


A mature, feature-complete library to parse command-line options.


You can set options using the main notation standards (learn more). These commands are all equivalent, setting the same values:

$ example --verbose --timeout=1000 --src one.js --src two.js
$ example --verbose --timeout 1000 --src one.js two.js
$ example -vt 1000 --src one.js two.js
$ example -vt 1000 one.js two.js

To access the values, first create a list of option definitions describing the options your application accepts. The type property is a setter function (the value supplied is passed through this), giving you full control over the value received.

const optionDefinitions = [
  { name: 'verbose', alias: 'v', type: Boolean },
  { name: 'src', type: String, multiple: true, defaultOption: true },
  { name: 'timeout', alias: 't', type: Number }

Next, parse the options using commandLineArgs():

const commandLineArgs = require('command-line-args')
const options = commandLineArgs(optionDefinitions)

options now looks like this:

  src: [
  verbose: true,
  timeout: 1000

Advanced usage

Beside the above typical usage, you can configure command-line-args to accept more advanced syntax forms.

  • Command-based syntax (git style) in the form:

    $ executable <command> [options]

    For example.

    $ git commit --squash -m "This is my commit message"
  • Command and sub-command syntax (docker style) in the form:

    $ executable <command> [options] <sub-command> [options]

    For example.

    $ docker run --detached --image centos bash -c yum install -y httpd

Usage guide generation

A usage guide (typically printed when --help is set) can be generated using command-line-usage. See the examples below and read the documentation for instructions how to create them.

A typical usage guide example.


The polymer-cli usage guide is a good real-life example.


Further Reading

There is plenty more to learn, please see the wiki for examples and documentation.


$ npm install command-line-args --save

© 2014-20 Lloyd Brookes <>.

Tested by test-runner. Documented by jsdoc-to-markdown.