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.
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
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.
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
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 adefault. Check withvalues.name ?? fallback. valueshas no prototype, sovalues.hasOwnPropertydoes not exist. Use"name" in valuesorObject.hasOwn(values, "name").- Short flags can be grouped:
-vxsets two booleans, and-n5or-n 5gives 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 --verbosethrows an "ambiguous" error. Write--name=-xwhen the value really starts with a dash. - There is no automatic
--helptext, no number conversion and no required-option check. Convert and validate the values yourself. allowNegativeis a newer addition; on very old Node versions--no-coloris treated as an unknown option.