structured-args

A feature-complete, type safe and highly flexible command line argument parsing library for JavaScript.

import { parse_args, boolean, string } from "structured-args";

const args = parse_args({
    verbose: { alias: "v", type: boolean() },
    name: { alias: "n", type: string(), default: "world" }
});

console.log(`Hello, ${args.name}!`);
if (args.verbose) console.log("Verbose mode enabled.");

$ node index.js -v=false --name CLI
Hello, CLI!

Parsing

Parsing supports:

• Bundling short options with - (All options except for the last ones must be boolean)
• getopt style short options immediately followed by their value, eg -O3 or -ifile.js
• Assigning values with a = sign, eg --letter=a
• Using a standalone -- to delimit options and values
• Treating negative numbers as values rather than flags (including Infinity and -Infinity)
• Optionally accepting multiple values for an option
• Automatic type conversion and validation via option-type processors
• Collecting positional arguments (standalone values) into the output array

The output object of parse_args is an array with the numeric indices corresponding to the standalone positional arguments, and additional fields for options that were passed (or that have a default value).

const args = parse_args({
    recursive: { alias: "r", type: boolean() },
    depth: { type: int(), default: 1 }
});

console.log(args[0]);
console.log(args.recursive);

$ node index.js -r --depth 3 path/to/dir
'path/to/dir'
true

Error handling

By default, parse_args prints a descriptive error message to stderr and exits the process when it encounters invalid input.

# Missing value for non-boolean flag
$ node index.js --name
Argument error: Expected a value after option 'name' (Found nothing)

# Unrecognized option
$ node index.js --unknown
Argument error: Unrecognised option 'unknown'

# Type validation failure (from built-in processor - see example below)
$ node index.js --port=99999
Argument error: port: Must be an integer between 1 and 65535 (Received: '99999')

Advanced usage

parse_args handles complex scenarios like multi-value flags and custom type validation out of the box.

import { parse_args, int, list, boolean } from "structured-args";

const options = {
    port: { alias: "p", type: int(1, 65535), default: 8080 },
    tags: { type: string(), multiple: true },
    debug: { alias: "d", type: boolean() }
};

const args = parse_args(options);
console.log(args);

$ node node index.js -p 0xBB8 --tags web api prod --debug extra_value
['extra_value', port: 3000, tags: ['web', 'api', 'prod'], debug: true]

Configuration

The parse_args function accepts an optional configuration object:

Option	Type	Default	Description
collect_values	boolean	true	Collect standalone values into the output array.
collect_unknown_options	boolean	false	Parse options not defined in the schema.
allow_double_dash_delimeter	boolean	true	Allow passing -- to stop option parsing.
argv	string[]	process.argv.slice(2)	Array of arguments to parse.
on_error	(msg: string) => void	standard_error	Custom error handler.

Option types

The library includes several built-in processors in structured-args/option-types:

Processor	Description
string()	Returns the argument as a string.
boolean()	Returns true (can be explicitly set to false using =false).
int(min, max)	Validates and returns an integer, optionally between min and max.
float(min, max)	Validates and returns a number, optionally between min and max.
one_of(...options)	Ensures value is one of the provided strings.
not_one_of(...options)	Ensures value is not one of the provided strings.
list(separator)	Splits a string into an array by separator (default ,).

Custom option types

A flag type is simply a function that takes a string and returns a value of any type. If the input is invalid, it should throw an error message as a string.

const absolutePath = (arg: string) => {
    if (!arg.startsWith("/")) throw "Must be an absolute path";
    return arg;
};

const args = parse_args({ path: { type: absolutePath } });

If a custom processor throws an error, the library catches it and appends the received value:

$ node index.js --path=./relative/path
Argument error: path: Must be an absolute path (Received: './relative/path')

Help menu generation

This library can also be used to generate a flag table to use in help menus:

import { help_string, boolean, string } from "structured-args";

const options = {
    verbose: { alias: "v", type: boolean(), description: "Show verbose output" },
    name: { alias: "n", type: string(), arg_label: "<name>", description: "Your name" }
};

console.log("Usage: my-app [options]\n");
console.log(help_string(options));

Output:

Usage: my-app [options]

 -v, --verbose        Show verbose output
 -n, --name <name>    Your name

Help configuration

The help_string generator can be customized with a HelpConfig object:

Option	Type	Default	Description
descriptions_only	boolean	false	Only include options that have a description.
option_format	util.InspectColor	undefined	Color or style used to format flag strings.
spaces_before_option	number	1	Padding before the flags.
spaces_after_option	number	4	Padding between flags and description.