Simpler CLIs with Util.parseArgs

Command-line applications, often called CLIs (Command Line Interfaces), are extremely common, especially when working with developers.

These applications are typically orders of magnitude lighter than graphical applications, simpler to use, and allow automation and scripting natively. However, this comes at the cost of interface polish and some user experience, since you need some knowledge, or sometimes quite a bit, of command-line environments to get started with basic functionality.

While the UI side is becoming increasingly advanced with libraries like blessed, and UX is getting more advanced with libraries like inquirer, the DX, or Developer Experience, remains the same. Developing a CLI ends up being complicated and full of little hacks we have to make, especially to understand what the user sent in the initial command, the so-called arguments.

Today, popular libraries like Yargs, commander, meow, and caporal make the task of fetching command-line arguments and passing them to the application to execute something easier. But this is something so simple that people wonder: “Why isn’t this native to Node.js?” Well, that wait is over.

util.parseArgs#

In version 18, Node.js implemented an experimental API called util.parseArgs. The goal is to make it easier and automate how we fetch command-line arguments to improve (and even eliminate) the need for external libraries to do the same thing.

It has a pretty simple API that takes only a configuration object:

1
import { parseArgs } from 'node:util'
2
const { values, positionals } = parseArgs({ args, options })

The configuration object has four options:

• args: The array of arguments we want to parse. By default, it will be process.argv with the first two arguments removed (the execPath and filename, which are the path to the Node command that was executed and the name of the file that’s running), leaving only what comes after.
• options: Another object used to define which arguments are recognized as valid by the program. This key is required and is an object with items that should follow this interface:
  • type: A string defining the type of the argument. Currently, parseArgs only supports string and boolean
  • multiple: A boolean that defines whether the argument can be passed multiple times. If true, all values for that argument are collected in an array. Otherwise, the last set option is used. Defaults to false
  • short: A single-character alias for the option. For example, if --all has the abbreviation -A, then short would be A
• strict: Whether the program should throw an error if an unrecognized argument is passed. Defaults to true
• allowPositionals: Whether the command accepts positional arguments, that is, arguments without flags like -a. These arguments will be received in a separate array that we destructure as positionals
• tokens: Returns the tokens that were passed. This is more useful when you want to extend the behavior of the original function, not as much when you just want to use the basic functionality.

The return value of parseArgs is an object with three keys:

• values: A map of all option names with their respective values
• positionals: An array of strings with the positional arguments passed, in order.
• tokens: An array of objects returned if the tokens configuration option is true

The token object can have tokens of two types, either options or positional arguments. All of them will be returned in a single object that has all the tokens. All values in this object will have at least two keys:

• kind: Either option, positional, or option-terminator
• index: The index of the element in the arguments array, so the original argument of a token can be obtained with args[token.index]

For option-type tokens (those with flags), we’ll have some extra properties:

• name: The long name of the token, for example all
• rawName: The original name of the option, without removing the dashes, the way it was passed to the command, for example --all
• value: The value of the argument. If it’s a boolean, this value will be undefined
• inlineValue: Whether the value was specified inline like --foo=bar

For positional arguments without options, we only have the value in a value key, which is equivalent to args[index].

These tokens are always returned in the order they were passed, so it’s possible to extend the functionality if you need to support one type of argument before another.

Another important thing is when we have so-called short option groups, cases like -abc. In these cases, each one will be expanded to a different token, so if we have common cases like -vvv, we’ll have three option-type tokens.

Let’s look at some examples.

Simple options#

Imagine we have the following code:

1
const options = {
2
  verbose: {
3
    type: 'boolean',
4
    short: 'v',
5
  },
6
  color: {
7
    type: 'string',
8
    short: 'c',
9
  },
10
  times: {
11
    type: 'string',
12
    short: 't',
13
  },
14
}
15

16
const { values, positionals } = parseArgs({options, args: ['-v', '-c', 'green']})

We’ll have the following object in values:

1
{
2
  __proto__: null,
3
  verbose: true,
4
  color: 'green'
5
}

Our positionals array will be empty because we’re not specifying that we want positionals. Notice that in values, the keys are always the full option names.

Positional parameters#

If we modify the code to allow positionals like this:

1
const { values, positionals } = parseArgs({
2
    options,
3
    allowPositionals: true,
4
    args: [
5
      'home.html', '--verbose', 'main.js', '--color', 'red', 'post.md'
6
    ]
7
  })

We’ll have the following output in values:

1
{
2
    __proto__:null,
3
    verbose: true,
4
    color: 'red'
5
}

But now we’ll have an array of positional options in positionals:

1
['home.html', 'main.js', 'post.md']

Notice that they appear in the order we’re sending them in the code.

Multiple options#

If we use the same option multiple times normally, as I mentioned before, only one key will be created, for example:

1
const options = {
2
  'bool': {
3
    type: 'boolean',
4
  },
5
  'str': {
6
    type: 'string',
7
  },
8
}
9
parseArgs({
10
  options, args: [
11
    '--bool', '--bool', '--str', 'yes', '--str', 'no'
12
  ]
13
})

We’ll have a values like:

1
{
2
  __proto__:null,
3
  bool: true,
4
  str: 'no'
5
}

Notice that we only have the last value of the option. Now, if we pass the multiple parameter to any option type in our options object:

1
const options = {
2
  'bool': {
3
    type: 'boolean',
4
    multiple: true,
5
  },
6
  'str': {
7
    type: 'string',
8
    multiple: true,
9
  },
10
}
11
parseArgs({
12
  options, args: [
13
    '--bool', '--bool', '--str', 'yes', '--str', 'no'
14
  ]
15
})

We’ll have the following value in values:

1
{
2
  __proto__:null,
3
  bool: [ true, true ],
4
  str: [ 'yes', 'no' ]
5
}

Short option groups#

There’s a type of value we can pass to a command line that’s known as a shorthand. The idea is that when we set multiple boolean options, we can group them all under a single -. For example, instead of main.js -v -s, we can do main.js -vs.

This also works in parseArgs without needing to do anything extra. We just need to set the short option for these properties:

1
const options = {
2
  'verbose': {
3
    type: 'boolean',
4
    short: 'v',
5
  },
6
  'silent': {
7
    type: 'boolean',
8
    short: 's',
9
  },
10
  'color': {
11
    type: 'string',
12
    short: 'c',
13
  },
14
}
15
parseArgs({options, args: ['-vs']})

It will give us this values object:

1
{
2
  __proto__:null,
3
  verbose: true,
4
  silent: true,
5
}

Option terminators#

There’s a specific type of option called a terminator. After this argument, everything else is treated as positional. In most shells, this option is --. For example, when we wanted to run an NPM command and send an argument to the command that would be executed, we’d do: npm run <command> -- param param param, and the command would receive the three parameters individually. The same applies to parseArgs:

1
const options = {
2
  'verbose': {
3
    type: 'boolean',
4
  },
5
  'count': {
6
    type: 'string',
7
  },
8
}
9

10
parseArgs({options, allowPositionals: true,
11
 args: [
12
   'how',
13
   '--verbose',
14
   'are',
15
   '--',
16
   '--count',
17
   '5',
18
   'you'
19
 ]
20
})

The values object will be:

1
{
2
  __proto__:null,
3
  verbose: true
4
}

And we’ll have the positionals:

1
[ 'how', 'are', '--count', '5', 'you' ]

Notice that when we use a terminator, all remaining values are considered positional.

Tokens#

When we talk about tokens, the functionality is a bit more complex. To explain this, we need to explain how this API actually works.

The parseArgs works in two phases:

• The first phase is parsing the arguments array into a tokens array. The goal is to have a sort of parsed arguments array like the one we already have, but with type annotations, indicating if the argument is an option, a positional argument, etc.
• In the second phase, the output of this first phase is read by the parser and we end up with the array we had before.

We can access the first part as an output if we set the configuration array with the tokens option as true. Then we’ll have a tokens key in the final output.

The type of this object will be the following interface (as explained here):

1
type Token = OptionToken | PositionalToken | OptionTerminatorToken;
2

3
interface CommonTokenProperties {
4
    /** Where does the token start in the string? */
5
  index: number;
6
}
7

8
interface OptionToken extends CommonTokenProperties {
9
  kind: 'option';
10

11
  /** Long name */
12
  name: string;
13

14
  /** The name of the option in the `args` array */
15
  rawName: string;
16

17
  /** The value of the option. Always `undefined` for boolean. */
18
  value: string | undefined;
19

20
  /** Is the value inline (ex --level=5)? */
21
  inlineValue: boolean | undefined;
22
}
23

24
interface PositionalToken extends CommonTokenProperties {
25
  kind: 'positional';
26

27
  /** The value of the positional argument, args[token.index] */
28
  value: string;
29
}
30

31
interface OptionTerminatorToken extends CommonTokenProperties {
32
  kind: 'option-terminator';
33
}

Let’s look at an example. Say we have the following options array:

1
const options = {
2
  'bool': {
3
    type: 'boolean',
4
    short: 'b',
5
  },
6
  'flag': {
7
    type: 'boolean',
8
    short: 'f',
9
  },
10
  'str': {
11
    type: 'string',
12
    short: 's',
13
  },
14
}

When we run parseArgs({ options, tokens: true, args: [ '--bool', '-b', '-bf' ] }), we get the following object:

1
{
2
    values: {
3
      __proto__:null,
4
      bool: true,
5
      flag: true,
6
    },
7
    positionals: [],
8
    tokens: [
9
      {
10
        kind: 'option',
11
        name: 'bool',
12
        rawName: '--bool',
13
        index: 0,
14
        value: undefined,
15
        inlineValue: undefined
16
      },
17
      {
18
        kind: 'option',
19
        name: 'bool',
20
        rawName: '-b',
21
        index: 1,
22
        value: undefined,
23
        inlineValue: undefined
24
      },
25
      {
26
        kind: 'option',
27
        name: 'bool',
28
        rawName: '-b',
29
        index: 2,
30
        value: undefined,
31
        inlineValue: undefined
32
      },
33
      {
34
        kind: 'option',
35
        name: 'flag',
36
        rawName: '-f',
37
        index: 2,
38
        value: undefined,
39
        inlineValue: undefined
40
      },
41
    ]
42
  }

It’s important to note that even though we have a single option called bool, we have three indices in the array because we’re passing the key three times. A more complete example can be using terminators and also inline values like this:

1
parseArgs({
2
    options, allowPositionals: true, tokens: true,
3
    args: [
4
      'command', '--', '--str', 'yes', '--str=yes'
5
    ]
6
})

Which gives us the following output:

1
{
2
    values: {
3
      __proto__:null,
4
    },
5
    positionals: [ 'command', '--str', 'yes', '--str=yes' ],
6
    tokens: [
7
      { kind: 'positional', index: 0, value: 'command' },
8
      { kind: 'option-terminator', index: 1 },
9
      { kind: 'positional', index: 2, value: '--str' },
10
      { kind: 'positional', index: 3, value: 'yes' },
11
      { kind: 'positional', index: 4, value: '--str=yes' }
12
    ]
13
  }

Notice that when we use a terminator, all remaining values are considered positional.

An example would be using this functionality to implement a CLI that uses subcommands, like git with git commit or Azure with az aks create. I’ll go through this implementation explaining how it would work.

First, let’s define a function to fetch the first command, which is a positional, and then we’ll fetch the first positional element we find:

1
function parseSubcommand(config) {
2
  // Allowing positionals since the subcommand is positional
3
  const {tokens} = parseArgs({
4
    ...config, tokens: true, allowPositionals: true
5
  });
6
  // Find the first occurrence of the positional
7
  let firstPosToken = tokens.find(({kind}) => kind==='positional');
8
  if (!firstPosToken) {
9
    throw new Error('Command name is missing: ' + config.args);
10
  }

Then we’ll get the command’s options and call parseArgs again:

1
  const cmdArgs = config.args.slice(0, firstPosToken.index);
2
  // Replace the occurrence in `config.args`
3
  const commandResult = parseArgs({
4
    ...config, args: cmdArgs, tokens: false, allowPositionals: false
5
  })

Now we’ll get the subcommand of this command:

1
  const subcommandName = firstPosToken.value
2

3
  const subcmdArgs = config.args.slice(firstPosToken.index+1)
4
  // Replace `config.args`
5
  const subcommandResult = parseArgs({
6
    ...config, args: subcmdArgs, tokens: false
7
  })
8

9
  return {
10
    commandResult,
11
    subcommandName,
12
    subcommandResult,
13
  }
14
}

The entire function would look like this:

1
function parseSubcommand(config) {
2
  const {tokens} = parseArgs({
3
    ...config, tokens: true, allowPositionals: true
4
  })
5
  let firstPosToken = tokens.find(({kind}) => kind==='positional')
6
  if (!firstPosToken) {
7
    throw new Error('Command name is missing: ' + config.args)
8
  }
9

10
  //----- Command options
11
  const cmdArgs = config.args.slice(0, firstPosToken.index)
12
  const commandResult = parseArgs({
13
    ...config, args: cmdArgs, tokens: false, allowPositionals: false
14
  })
15

16
  //----- Subcommand
17
  const subcommandName = firstPosToken.value;
18

19
  const subcmdArgs = config.args.slice(firstPosToken.index+1)
20
  const subcommandResult = parseArgs({
21
    ...config, args: subcmdArgs, tokens: false
22
  })
23

24
  return {
25
    commandResult,
26
    subcommandName,
27
    subcommandResult,
28
  }
29
}

Conclusion#

The parseArgs is an excellent option for making CLI creation easier and showing how we can further improve application development with Node.js. Don’t forget to read the official documentation and the article I showed in this post!