Simpler CLIs with util.parseArgs

Command line applications, the famous CLIs (Command Line Interfaces), are extremely common, especially when we’re dealing with devs.

These applications tend to be orders of magnitude lighter than an app with a graphical interface, they’re simpler to use, and they allow automation and scripting natively, all of that at the cost of the interface and a bit of the user experience, since you need some – sometimes a lot – of knowledge of command line environments to start using the basic features.

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

Today, some famous libraries like Yargs, commander, meow and caporal make it easier to grab command line arguments and send them to the application to do something, but this is something so simple that people ask themselves: “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 exactly to make it easier and automate how we fetch command line arguments, to improve on (and even eliminate) the need for external libraries to do the same thing.

It has a pretty simple API, which only takes a config object:

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

The config object has four options:

• args: The array of arguments we want to parse. By default, it’ll be process.argv with the first two arguments removed, which are execPath and filename (the path of the Node command that was run and the name of the file that’s running), leaving only what came after.
• options: Another object used to define which arguments will be identified as valid by the program. This key is required, and it’s an object whose items must follow this interface:
  • type: A string defining the type of the argument. Right now 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 get collected into an array, otherwise the last value set wins. The default is false
  • short: The option’s alias as a single character, for example the short form of --all being -A, so short would be A
• strict: Whether the program should throw an error if an argument not recognized by options is passed. Defaults to true
• allowPositionals: Whether the command accepts positional arguments, meaning arguments without flags like -a. These arguments come back in their own array, which we destructure as positionals
• tokens: Returns the tokens that were passed. This is more useful when you want to extend the original function’s behavior, less so if you just want to use the base function.

The return of parseArgs is an object with three keys:

• values: A map of every option name to its respective value
• positionals: An array of strings with the positional arguments passed, in order.
• tokens: An array of objects returned if the config’s tokens option is true

The tokens object can hold two kinds of tokens, either options or positional arguments. All of them get returned in a single object holding all the tokens. Every value in that 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 that a token’s original argument can be obtained with args[token.index]

For option-type tokens (the ones with flags), we get a few extra properties:

• name: The long name of the token, for example all
• rawName: The original name of the option, without stripping the dashes, exactly as it was passed to the command, for example --all
• value: The argument’s value. 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 get the value in a value key, which is the equivalent of args[index]

These tokens always come back in the order they were passed, so it’s possible to extend the functionality if you need to support some argument type ahead of another argument.

Another important thing is when we have the so-called short option groups, which are cases like -abc. In these cases, each one of them gets expanded into a different token, so if we have a common case like -vvv we’ll get three tokens of type option.

Let’s go through some examples.

Simple options#

Say 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 get 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 the keys in values are always the full option names.

Positional parameters#

If we tweak 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 get 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 they show up in the order we’re sending them in the code.

Multiple options#

If we use the same option several times normally, like I mentioned before, only one key gets 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 get a values like:

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

Notice we only get the last value of the option. Now, if we pass the multiple parameter for 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 get the following value in values:

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

Combined shorthands#

There’s a type of value we can pass on a command line 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 any extra effort, 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']})

This gives us this values object:

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

Option terminators#

There’s a specific kind of option called a terminator, meaning that after this argument, everything else gets treated as positional. In most shells this option is --. For example, back when we wanted to run an old NPM command and send an argument to the command that would run, 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 get positionals:

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

Tokens#

When we’re talking about tokens, the feature is a bit more complex, so let’s explain how this API actually works.

parseArgs works in two phases:

• The first phase parses the arguments array into an array of tokens. The goal is to get a kind of parsed arguments array similar to what we already have, but annotated with types, whether the argument is an option, whether it’s a positional argument, and so on
• In the second phase, the output of the first phase gets read by the parser and we end up with the array we had before

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

This object’s type is 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 option's name in the `args` array */
15
  rawName: string;
16

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

20
  /** Is the value inline (e.g. --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 go through 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’ll 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 notice that even though we have a single option called bool, we get three indexes in the array because we’re passing that key three times. A more complete example would be using terminators along with inline values, like here:

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 once we use a terminator, everything else is treated as positional.

One use case for this feature would be implementing a CLI that uses subcommands, like git with git commit or Azure with az aks create. Let’s walk through this implementation explaining how it would work.

First, let’s define a function to look up the first command, which is a positional, and then we’ll grab 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
  // Finds 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 let’s grab the command’s options and call parseArgs again:

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

Now let’s grab this command’s subcommand:

1
  const subcommandName = firstPosToken.value
2

3
  const subcmdArgs = config.args.slice(firstPosToken.index+1)
4
  // replacing `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 whole 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#

parseArgs is an excellent option to make building CLIs easier and to show how we can keep improving app development with Node.js. Don’t forget to read the official docs and the article I linked in this post!