🚀 Big News: Socket Acquires Coana to Bring Reachability Analysis to Every Appsec Team.Learn more

command-line-parser

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

command-line-parser

Simple lightweight function takes an array of command-line arguments and returns a parsed object

0.2.10
latest
Version published
Weekly downloads
854
5.04%
Maintainers
2
Weekly downloads
 
Created

command-line-parser

This statement:

const argsObj = require('command-line-parser')();

returns this argsObj object:

{
	v: true,
	debug: true,
	host: 'there.com',
	port: '8081',
	_args: [ 'myfile1', 'myfile2' ]
}

when invoked with:

node ./myscript.js myfile1 -v -debug -host there.com -port 8081 myfile2

This simple lightweight module exports a default function that takes an array of command-line arguments and returns a parsed object (a bit simpler than the venerable minimist or commander).

Arguments as keys and values

A key argument (starts with a dash) looks to the next argument for a value, such as -foo bar. If foo does not find a value, a default value of true will be set.

There's a few ways in which foo might not find a value:

  • the following argument also starts with a dash, as in -foo -hey
  • there are no more arguments
  • foo is set in booleanKeys of config (an optional argument):
const argsObj = require('command-line-parser')({
	booleanKeys: [ 'foo' ]
});

A key with multiple leading dashes such as --debug will be the same as -debug (with the exception of overriding the optional argument allowKeyGrouping described below).

A key with embedded dashes or spaces will be converted to camelCase from camel-case.

Arguments that don't fulfill the role of a key or a value will be added in an array to a key called _args in the parsed object.

To avoid any arguments intended for _args from becoming the unintentional value of a preceding boolean key, either specify that boolean key in booleanKeys of config, or follow that boolean key with a placeholder argument such as a single - or double dash -- on the command line.

node ./myscript.js -d -- foo1 foo2 foo3

Embedding numerical values within keys

Instead of having to separate a numerical argument from its key:

node ./myscript.js -n 8

it may be embedded in the key:

node ./myscript.js -n8

by setting allowEmbeddedValues in the config:

const argsObj = require('command-line-parser')({
	allowEmbeddedValues: true
});

to give the result

{
	n: 8
}

Single letter key grouping

To parse a leading-dash argument such as -abc as single-letter keys instead of one multi-letter key, then set allowKeyGrouping in config so that

node ./myscript.js -abc

when parsed by

const argsObj = require('command-line-parser')({
	allowKeyGrouping: true
});

gives the result

{
	a: true,
	b: true,
	c: true
}

allowKeyGrouping can be overridden on the command-line by prefixing the argument with double-dashes, so that

node ./myscript.js --abc

becomes

{
	abc: true
}

Passing configuration

An optional configuration object may be passed in that will override these default values:

const argsObj = require('command-line-parser')({
	args = process.argv.slice(2),	// skip the binary and script file args
	booleanKeys = [],
	allowKeyGrouping: false,
	allowEmbeddedValues: false
});

Installation and testing

Install with npm install command-line-parser.

Test via npm test (and see test/index.js for some examples).

Useful destructuring assignment pattern

This is a common pattern using destructuring assignment (available in ES6 or via Babel) which can be useful here, especially with default values, and perhaps renaming _args:

const {
	v,
	debug = false,
	host = 'default.com',
	port = '80',
	_args: files = []
} = argsObj ;

will assign the locally scoped constant variables v, debug, host, port, and files.

FAQs

Package last updated on 01 Mar 2023

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts