parseArgs

The util/parseArgs module parses command-line style argument arrays. It is exposed both as require('util/parseArgs') and as require('util').parseArgs.

parseArgs()

Parses an argument array using one or more configuration objects.

Syntax

parseArgs(args, ...configs)

Parameters

• args String[]: Argument array to parse.
• ...configs Object: One or more parser configurations.

When multiple configs are passed and some of them include command, the parser tries to match args[0] to the command name and uses the matching configuration.

Configuration fields

Option definitions

Each entry in config.options is keyed by the JavaScript property name. The parser automatically converts camelCase names to kebab-case flags.

For example, maxRetryCount maps to --max-retry-count.

Supported forms include:

• Long options such as --output file.txt
• Inline long values such as --output=file.txt
• Short options such as -o file.txt
• Inline short values such as -o=file.txt
• Short boolean groups such as -abc
• Option terminator --

Positional definitions

positionals can contain simple strings or detailed objects.

Simple form:

positionals: ['inputFile', 'outputFile']

Detailed form:

positionals: [
    { name: 'input-file' },
    { name: 'output-file', optional: true, default: 'stdout' },
    { name: 'files', variadic: true }
]

Rules:

• Variadic positionals must be the last positional.
• Missing required positionals raise TypeError.
• Named positional keys are converted from kebab-case to camelCase in result.namedPositionals.

Return value

parseArgs() returns an object with these fields.

Usage example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

const { parseArgs } = require('util');

const result = parseArgs(['-v', '--output', 'file.txt', 'input.sql'], {
    options: {
        verbose: { type: 'boolean', short: 'v' },
        output: { type: 'string' }
    },
    allowPositionals: true,
    positionals: ['input-file']
});

console.println(JSON.stringify(result.values));
console.println(JSON.stringify(result.namedPositionals));

Number parsing

Use integer for whole-number arguments and float for decimal numbers.

• integer rejects values that contain a decimal point.
• Both integer and float return JavaScript numbers.

1
2
3
4
5
6
7
8

const { parseArgs } = require('util');

const result = parseArgs(['--port', '8080', '--ratio', '0.75'], {
    options: {
        port: { type: 'integer' },
        ratio: { type: 'float' }
    }
});

Negative booleans

With allowNegative: true, boolean long options accept --no-....

1
2
3
4
5
6
7
8
9

const { parseArgs } = require('util');

const result = parseArgs(['--no-color', '--verbose'], {
    options: {
        color: { type: 'boolean' },
        verbose: { type: 'boolean' }
    },
    allowNegative: true
});

Sub-command parsing

When multiple configs are supplied, the first argument can select a command-specific config.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

const parseArgs = require('util/parseArgs');

const commitConfig = {
    command: 'commit',
    options: {
        message: { type: 'string', short: 'm' },
        all: { type: 'boolean', short: 'a' }
    }
};

const pushConfig = {
    command: 'push',
    options: {
        force: { type: 'boolean', short: 'f' }
    },
    allowPositionals: true,
    positionals: ['remote', { name: 'branch', optional: true }]
};

const result = parseArgs(['push', '-f', 'origin', 'main'], commitConfig, pushConfig);
console.println(result.command);
console.println(JSON.stringify(result.namedPositionals));

parseArgs.formatHelp()

Generates human-readable help text from the same config structure used by parseArgs().

Syntax

parseArgs.formatHelp(...configs)

It supports both:

• single-command help output
• multi-command help output with command summaries and per-command sections

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

const parseArgs = require('util/parseArgs');

const help = parseArgs.formatHelp({
    usage: 'Usage: myapp [options] <file>',
    options: {
        userName: { type: 'string', short: 'u', description: 'User name', default: 'guest' },
        enableDebug: { type: 'boolean', short: 'd', description: 'Enable debug mode', default: false }
    },
    positionals: [
        { name: 'file', description: 'Input file to process' }
    ]
});

console.println(help);

parseArgs.toKebabCase()

Converts a JavaScript camelCase option name to its CLI kebab-case form.

Syntax

parseArgs.toKebabCase(name)

Usage example

1
2
3

const parseArgs = require('util/parseArgs');

console.println(parseArgs.toKebabCase('maxRetryCount'));

Behavior notes

• The first argument must be an array, otherwise TypeError is thrown.
• In strict mode, unknown options and unexpected positionals raise TypeError.
• multiple: true collects repeated values into arrays.
• Defaults are applied before parsing explicit option values.
• The parser accepts both require('util').parseArgs and require('util/parseArgs') usage.