Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท util, assert and the Test Runner

Node.js util.parseArgs() function

Reference for util.parseArgs() in Node.js: declare string and boolean options, short flags, positionals, defaults, strict mode, negation and raw tokens.

util.parseArgs() turns a list of command-line words into an object of option values and a list of positional arguments. You describe the options you accept, and Node does the splitting of --name=value, --name value, -v and -- for you, with no npm package.

By default it reads process.argv.slice(2), but you can pass your own args array, which also makes the parser easy to test. In strict mode (the default) it throws on unknown options, missing values and unexpected positionals, so typos are reported instead of silently ignored.

NODE
import { parseArgs } from "node:util";

const { values, positionals } = parseArgs({
  args: ["-v", "--out=a.txt", "input.txt"],
  options: { verbose: { type: "boolean", short: "v" }, out: { type: "string" } },
  allowPositionals: true,
});

Try it

Node.js Options, short flags and positionals

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Strict mode errors and tokens

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
util.parseArgs([config])
Name Description
args Array of strings to parse. Default: process.argv.slice(2).
options Object describing each option by its long name: type ("boolean" or "string", required), short (one character), multiple (collect repeats into an array) and default.
strict Default true. Throw on unknown options, wrong value kinds and unexpected positionals.
allowPositionals Accept positional arguments. Default false in strict mode, true otherwise.
allowNegative Let --no-name set a boolean option to false. Default false.
tokens Also return the list of parsed tokens. Default false.

Returns: an object with values (an object with a null prototype), positionals (array of strings) and, with tokens: true, a tokens array. Each token has a kind of "option", "positional" or "option-terminator" plus its index; option tokens also carry name, rawName, value and inlineValue.

Errors: with strict: true it throws ERR_PARSE_ARGS_UNKNOWN_OPTION, ERR_PARSE_ARGS_INVALID_OPTION_VALUE (for example a string option without a value) or ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL.

Usage notes

  • Options you did not pass are simply absent from values, unless they have a default. Check with values.name ?? fallback.
  • values has no prototype, so values.hasOwnProperty does not exist. Use "name" in values or Object.hasOwn(values, "name").
  • Short flags can be grouped: -vx sets two booleans, and -n5 or -n 5 gives a string option a value.
  • A bare -- ends option parsing; everything after it is positional.
  • In strict mode a string option does not take a following word that starts with a dash: --name --verbose throws an "ambiguous" error. Write --name=-x when the value really starts with a dash.
  • There is no automatic --help text, no number conversion and no required-option check. Convert and validate the values yourself.
  • allowNegative is a newer addition; on very old Node versions --no-color is treated as an unknown option.