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 *

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.

nodejs
cli
parseargs
utilities

Try it yourself

Sketch your approach before you read the solution. That is what the interview tests.

Stuck? Get a hint.

A short nudge toward the approach. It will not give the answer away.

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, 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 s

The solution is hidden so you can try first

7 min read · 8 sections

Read the code

JavaScriptReal 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"

Discussion

Other approaches, follow-ups and how it went in real interviews.

Sign in to join the discussion.

No comments yet. Share how you would answer it.

The solution is hidden so you can try first

Keep your momentum going.