# Arguments, Exit Codes and Clear Errors

A command-line tool reads the words typed after it with process.argv and util.parseArgs, prints a --help line, sends errors to console.error with a message a person can act on, and sets process.exitCode so the computer that ran it knows whether it worked.

Apprentice · Node.js · JavaScript · Updated November 19, 2026

By Gregor Dzierzon

## After this lesson you can

- Read a command's options with util.parseArgs, with short flags, defaults and a --help line
- Report a failure with console.error, a message a person can act on, and process.exitCode set to 1

## Key takeaways

- process.argv holds every word of the command, starting with the paths of node and your script, so the words the person typed start at process.argv[2].
- util.parseArgs reads options such as --runner Leo, short flags such as -r, and defaults, and stops with an error for an option it doesn't know.
- console.error writes to the error output, a separate channel from console.log, so errors still reach the screen when the normal output goes to a file.
- An exit code of 0 means the program worked, and anything else means it failed. Set process.exitCode = 1 when your tool fails.
- A good error message says what went wrong and what to do next, such as which option is missing and an example of the command.

Every command you've typed so far takes words after it: `git clone` and an address, `npm install` and a package name, `node` and a file. Tools you'll write at work take them too, such as a script that tidies one month's report, or a command a build server runs with its settings. A tool that reads its words is one tool for every runner and every week, instead of a copy for each.

Dana's report shows one runner's week, and to see someone else's, she edits the code. She'd rather type the runner's name.

## The words after the command: process.argv

`process.argv` (read "arg-V", the argument values) is an array holding every word of the command that started your program:

```javascript
console.log(process.argv);
```

Run it with `node args.js --runner Leo --week 2026-11-09`:

```text
[
  'C:\\Program Files\\nodejs\\node.exe',
  'C:\\Users\\Sam\\nodejs-course\\running-club\\args.js',
  '--runner',
  'Leo',
  '--week',
  '2026-11-09'
]
```

The first two are always the paths of `node` itself and of your script; the words the person typed start at `process.argv[2]`. You could walk through that array by hand, but options can come in any order, have short forms or be left out, and that code grows fast.

## Options, short flags and defaults: util.parseArgs

`parseArgs` from the built-in `node:util` module reads them for you. You describe each option: its `type` (`"string"` for an option that takes a value, `"boolean"` for a switch that's on or off), an optional one-letter `short` form, and an optional `default`:

```javascript
import { parseArgs } from "node:util";

const { values } = parseArgs({
  options: {
    runner: { type: "string", short: "r" },
    week: { type: "string", short: "w", default: "2026-11-02" },
  },
});

console.log(`Runner: ${values.runner}`);
console.log(`Week: ${values.week}`);
```

Run it with `node options.js -r Leo`:

```text
Runner: Leo
Week: 2026-11-02
```

`-r Leo` is the short form of `--runner Leo`. The week wasn't given, so it's the default. Leave out `--runner` too, and `values.runner` is `undefined`. Every value is text, even `--week 7`; turn numbers into numbers yourself.

Mistype an option, as in `node options.js --runer Leo`, and `parseArgs` stops the program rather than guess. The line that matters in what it prints:

```text
TypeError [ERR_PARSE_ARGS_UNKNOWN_OPTION]: Unknown option '--runer'
```

A tool should also say how it's used. By habit, `--help` (or `-h`) prints a **usage line**: the command with its options, square brackets around the ones you can leave out.

## When it fails: console.error and the exit code

Here's Dana's report with a help line and a check for the runner:

```javascript
import { parseArgs } from "node:util";

const usage = "Usage: node report.js --runner <name> [--week <yyyy-mm-dd>]";

const { values } = parseArgs({
  options: {
    runner: { type: "string", short: "r" },
    week: { type: "string", short: "w", default: "2026-11-02" },
    help: { type: "boolean", short: "h" },
  },
});

if (values.help) {
  console.log(usage);
} else if (values.runner === undefined) {
  console.error("Which runner? Give a name, such as: node report.js --runner Maya");
  console.error(usage);
  process.exitCode = 1;
} else {
  console.log(`${values.runner}'s week of ${values.week}`);
}
```

Run it with no runner, then ask for the **exit code**: the number every program hands back when it ends. In PowerShell, `$LASTEXITCODE` shows the last one; in zsh, `echo $?` does.

```bash
node report.js
$LASTEXITCODE
```

```text
Which runner? Give a name, such as: node report.js --runner Maya
Usage: node report.js --runner <name> [--week <yyyy-mm-dd>]
1
```

Three things make that failure useful:

- **The message says what to do.** Not "Error: invalid input", but which option is missing and an example of the command that works.
- **`console.error` writes to the error output**, a channel of its own, separate from the normal output `console.log` writes to. Send the report to a file with `node report.js > week.txt`, and the error still appears on the screen instead of hiding in the file.
- **`process.exitCode = 1` tells the computer that ran your program that it failed.** An exit code of **0** means it worked; anything else means it didn't. You don't read it, but npm scripts, other scripts and the build servers you'll meet later do: they stop at a step that fails. Run `node report.js --runner Maya`, and the exit code is 0.

Setting `process.exitCode` lets the program finish what it's doing, such as writing a file, and then end with that code. (`process.exit(1)` would end it on that line, before a pending write finishes.)

## Check yourself

2 questions to try on the lesson page.

## So what

Options for every runner and week, a `--help` line, errors on the error output with an example that works, and an honest exit code: that's what makes a script a tool someone else can use, and a step another program can trust.

## Key terms

- [process.argv](https://www.ask-codey.com/glossary/process-argv)
- [util.parseArgs](https://www.ask-codey.com/glossary/util-parseargs)
- [Flags and Options](https://www.ask-codey.com/glossary/flags-and-options)
- [Exit Code](https://www.ask-codey.com/glossary/exit-code-operating-system)

## Related

- [Settings from Environment Variables](https://www.ask-codey.com/lessons/node-environment-variables)
- [Reading and Writing Files](https://www.ask-codey.com/lessons/node-files-read-and-write)

Source: https://www.ask-codey.com/lessons/node-command-line-arguments
