Categories
Node.js Node.js Quick Tips Quick Tips

Command-line argument parsing with Node.js core

3 min read

If you’ve ever written a command-line tool with Node.js, there’s a good chance you’ve used a library like minimist, Commander.js or Yargs to handle argument parsing for you.

For example, when we run a script like this on the command-line:

node script.mjs --name "Budgie" --verbose

We could use minimist to help us parse those arguments:

import minimist from "minimist";

const args = minimist(process.argv.slice(2), {
  string: ["name"],
  boolean: ["verbose"],
  alias: {
    name: "n",
    verbose: "v",
  },
});

console.log(args);
// > { _: [], verbose: true, v: true, name: 'Budgie', n: 'Budgie' }

The existing libraries for command-line argument parsing are all excellent choices, but there’s now a high-level API that can help us with this available in Node.js core: parseArgs

Example of argument parsing with parseArgs

parseArgs is available as a function in the Node.js util module. Here’s what our minimist example above looks like when rewritten with parseArgs:

import { parseArgs } from "node:util";

const args = parseArgs({
  options: {
    name: {
      type: "string",
      short: "n",
    },
    verbose: {
      type: "boolean",
      short: "v",
    },
  },
});

console.log(args);
// > {
// >   values: { name: 'Budgie', verbose: true },
// >   positionals: []
// > }

Example of setting default values with parseArgs

Default values landed in the v0.11.0 release of @pkgjs/parseargs and in Node.js v18.11.0, allowing us to set default values for arguments like this:

import { parseArgs } from "node:util";

const args = parseArgs({
  options: {
	message: {
	  type: "string",
	  default: "Oh hai there!",
	},
  }
});

console.log(args);
// > {
// >   values: [Object: null prototype] { message: 'Oh hai there!' },
// >   positionals: []
// > }

parseArgs also supports:

  • Passing an option multiple times
  • Positional arguments
  • Strict mode (throws an error for unknown arguments, on by default)
  • Tokens for extending the built-in behaviour

I recommend digging into the Node.js documentation for parseArgs to learn more about these features.

parseArgs isn’t intended to replace more fully featured libraries like Commander.js or Yargs, but as the project README describes, it’s a good option for "developers of simple CLI tools, ad-hoc scripts, deployed Node.js applications, and learning materials."

parseArgs development

parseArgs was created by members of the Node.js package maintenance team: John Gee (maintainer of Commander.js) and Benjamin Coe (maintainer of yargs), as well as a number of other contributors.

It’s worth mentioning that the stability of parseArgs is currently marked as Experimental in Node.js, but the API is unlikely to change at this stage. The parseArgs contributors are keen to mark it as stable if it’s meeting users needs.

The parseArgs library is developed under the pkgjs/parseargs repository on GitHub and upstreamed into Node.js. From what I’ve seen, this development process has been working well. I’m interested to see if this is an approach that other teams will adopt to contribute features to Node.js core.

Support in Node.js

If you’re using an older version of Node.js, you can still use parseArgs as it’s published as a package on npm: @pkgjs/parseargs.

Related links

If you want to dig in a little deeper I recommend checking out: