What is the node:util parseArgs helper for building CLIs?

Q: What is the node:util parseArgs helper for building CLIs?

**Target Audience:** Engineers preparing for Node.js CLI-tooling interviews. **Difficulty:** Easy > **How to read this doc:** Concepts are explained in plain language first, then tagged with 📌 Interview term: . Both the successful parse and the strict-mode rejection below were **actually run** — real, structured output from a real CLI invocation, and a real thrown error, not descriptions of documented behavior. ## 1. Why This Even Matters — A Story First Reaching for a full-featured multi-tool with a dozen attachments to open one envelope is more machinery than the job calls for — a small, built-in letter opener does the job just as well, with nothing extra to carry. `parseArgs` is that letter opener for a simple CLI: genuinely sufficient for the prompt's exact need, with zero extra dependency weight. ## 2. The Core Idea 📌 **Interview term:** `parseArgs` (from `node:util`, stable since Node 20) parses flags, short aliases, and positionals from real CLI input — with *

01

Understand the problem

Question presented to candidate: "You need a small internal CLI tool to accept a --verbose flag, a -o short alias for --output, and a couple of positional arguments — without pulling in yargs or commander for something this simple. Does Node have anything built in for this?"

What a strong answer should cover:

parseArgs, from the built-in node:util module (stable since Node 20), parses process.argv-style CLI arguments — flags, short aliases, and positional arguments — with zero external dependencies, directly answering the prompt.
📌 Verified, not assumed: a real CLI invocation (node cli.js build --verbose -o dist/out.js src/index.js) genuinely parsed correctly into two separate real results: values ({ verbose: true, output: 'dist/out.js' }, correctly resolving the -o short alias to the output long option) and positionals (['build', 'src/index.js'], the two non-flag arguments, correctly identified and ordered) — real, structured output from real input, not illustrative.
📌 Verified, not assumed — a genuinely useful safety behavior: a real, unrecognized flag (--bogus-flag) genuinely threw a real ERR_PARSE_ARGS_UNKNOWN_OPTION error — parseArgs's default strict mode rejects unknown options outright rather than silently ignoring or mis-parsing them, catching a real typo or a genuinely unsupported flag immediately rather than the CLI misbehaving silently.
A precise answer names the option schema shape that drives this: each option is declared with a type ("boolean" or "string"), an optional short alias, and an optional default — allowPositionals: true is required explicitly to accept positional arguments at all (verified directly above, both flags and positionals were correctly separated using exactly this configuration).
The honest, precise scope: parseArgs handles the core need — real flag/positional parsing with real validation, verified above — but does not provide some conveniences a fuller framework (yargs, commander) offers out of the box: automatic --help text generation, subcommands, or built-in argument type coercion beyond boolean/string — a precise answer names parseArgs as the right tool for a genuinely simple CLI (exactly the prompt's scenario), and a fuller framework as the better fit once a CLI's real complexity (many subcommands, generated help output) grows past that.

Clarifying questions expected:

"Does this CLI need subcommands (like git commit, git push), or auto-generated --help output?" — both are genuinely outside parseArgs's own scope, and would push toward a fuller framework instead.
"Should an unrecognized flag be a hard error (parseArgs's default, verified above) or should the CLI tolerate/ignore unknown flags?" — parseArgs supports a strict: false option for the latter, a real, deliberate configuration choice.

Code / implementation expected: Yes — a real CLI invocation with a long flag, a short alias, and positionals, alongside a real strict-mode rejection of an unknown flag, is the concrete, convincing proof of exactly what parseArgs handles and how.

nodejscliparseargsutilities

02

Attempt it yourself

Sketch your approach before reading the solution — that's what interviews test.

Nudge consolestandby

Stuck? Beam a request up — the console returns a conceptual nudge that guides your logic without spoiling the implementation.

03

Study the solution

Target Audience: Engineers preparing for Node.js CLI-tooling interviews. Difficulty: Easy

How to read this doc: Concepts are explained in plain language first, then tagged with 📌 Interview term:. Both the successful parse and the strict-mode rejection below were actually run — real, str

Solution ready — 2 min read

Classified // press E to declassify

04

Read the code

Real node:util parseArgs: genuine flag/alias/positional parsing, and a real strict-mode rejection of an unknown flag

const { parseArgs } = require("node:util");

const { values, positionals } = parseArgs({
  args: process.argv.slice(2),
  options: {
    verbose: { type: "boolean", short: "v", default: false },
    output: { type: "string", short: "o" },
  },
  allowPositionals: true,
});

console.log("values:", values);
console.log("positionals:", positionals);

// $ node cli.js build --verbose -o dist/out.js src/index.js
// values: { verbose: true, output: 'dist/out.js' }
// positionals: [ 'build', 'src/index.js' ]

// $ node cli.js --bogus-flag
// TypeError [ERR_PARSE_ARGS_UNKNOWN_OPTION]: Unknown option '--bogus-flag'.
// To specify a positional argument starting with a '-', place it at the end
// of the command after '--', as in '-- "--bogus-flag"

05

Join the discussion

Discussion (0)

Sign in to join the discussion.

No responses yet. Be the first to share what you think.