How To Handle Command-line Arguments in Node.js Scripts

Updated on May 13, 2021


How To Handle Command-line Arguments in Node.js Scripts


Command-line arguments are a way to provide additional input for commands. You can use command-line arguments to add flexibility and customization to your Node.js scripts.

In this article, you will learn about argument vectors, detecting argument flags, handling multiple arguments and values, and using the commander package.


To follow through this tutorial, you’ll need:

This tutorial was verified with Node v16.10.0, npm v7.12.2, and commander v7.2.0.

Using Argument Vectors

Node.js supports a list of passed arguments, known as an argument vector. The argument vector is an array available from process.argv in your Node.js script.

The array contains everything that’s passed to the script, including the Node.js executable and the path and filename of the script.

If you were to run the following command:

  1. node example.js -a -b -c

Your argument vector would contain five items:


At the very least, a script that’s run without any arguments will still contain two items in the array, the node executable and the script file that is being run.

Typically the argument vector is paired with an argument count (argc) that tells you how many arguments have been passed in. Node.js lacks this particular variable but we can always grab the length of the argument vector array:

if (process.argv.length === 2) {
  console.error('Expected at least one argument!');

This example code will check the length of argv. A length of 2 would indicate that only the node executable and the script file are present. If there are no arguments, it will print out the message: Expected at least one argument! and exit.

Using Argument Flags

Let’s consider an example that displays a default message. However, when a specific flag is present, it will display a different message.

if (process.argv[2] && process.argv[2] === '-f') {
  console.log('Flag is present.');
} else {
  console.log('Flag is not present.');

This script checks if we have a third item in our argument vector. The index is 2 because arrays in JavaScript are zero-indexed. If a third item is present and is equal to -f it will alter the output.

Here is an example of running the script without arguments:

  1. node example.js

And the generated output:

Flag is not present.

Here is an example of running the script with arguments:

  1. node example.js -f

And the generated output:

Flag is present.

We don’t have to limit ourselves to modifying the conditional control structure, we can use the actual value that’s been passed to the script as well:

const custom = (process.argv[2] || 'Default');
console.log('Custom: ', custom);

Instead of a conditional based on the argument, this script takes the value that is passed in (defaulting to "Default" when the argument is missing) and injects it into the script output.

Using Multiple Arguments with Values

We have written a script that accepts an argument and one that accepts a raw value, what about in scenarios where we want to use a value in conjunction with an argument?

To make things a bit more complex, let’s also accept multiple arguments:

// Check to see if the -f argument is present
const flag = (  
  process.argv.indexOf('-f') > -1 ? 'Flag is present.' : 'Flag is not present.'

// Checks for --custom and if it has a value
const customIndex = process.argv.indexOf('--custom');
let customValue;

if (customIndex > -1) {
  // Retrieve the value after --custom
  customValue = process.argv[customIndex + 1];

const custom = (customValue || 'Default');

console.log('Flag:', `${flag}`);
console.log('Custom:', `${custom}`);

By using indexOf instead of relying on specific index values, we are able to look for the arguments anywhere in the argument vector, regardless of the order!

Here is an example of running the script without arguments:

node example.js

And the generated output:

Flag: Flag is not present. Custom: Default

Here is an example of running the script with arguments:

  1. node example.js -f --custom Override

And the generated output:

Flag: Flag is present. Custom: Override

Now, your command-line script can accept multiple arguments and values.

Using commander

The aforementioned examples work when the argument input is quite specific. However, users may attempt to use arguments with and without equal signs (-nJaneDoe or --name=JohnDoe), quoted strings to pass-in values with spaces (-n "Jane Doe") and even have arguments aliased to provide short and longhand versions.

That’s where the commander library can help.

commander is a popular Node.js library that is inspired by the Ruby library of the same name.

First, in your project directory, initialize your project:

  1. npm init

Then, install commander:

  1. npm install commander@7.2.0

Let’s take our previous example and port it to use commander:

const commander = require('commander');

  .version('1.0.0', '-v, --version')
  .option('-f, --flag', 'Detects if the flag is present.')
  .option('-c, --custom <value>', 'Overwriting value.', 'Default')

const options = commander.opts();

const flag = (options.flag ? 'Flag is present.' : 'Flag is not present.');

console.log('Flag:', `${flag}`);
console.log('Custom:', `${options.custom}`);

commander does all of the hard work by processing process.argv and adding the arguments and any associated values as properties in our commander object.

We can easily version our script and report the version number with -v or --version. We also get some friendly output that explains the script’s usage by passing the --help argument and if you happen to pass an argument that’s not defined or is missing a passed value, it will throw an error.


In this article, you learned about argument vectors, detecting argument flags, handling multiple arguments and values, and using the commander package.

While you can quickly create scripts with your own command-line arguments, you may want to consider utilizing commander or Inquirer.js if you would like more robustness and maintainability.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about our products

About the authors
Default avatar


Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

In Node. js, as in C and many related environments, all command-line arguments received by the shell are given to the process in an array called args (short for ‘argument values’). There you have it - an array containing any arguments you passed in. Notice the first two elements - node and the path to your script.

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Featured on Community

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel