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
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:
console.log(process.argv);
Run it with node args.js --runner Leo --week 2026-11-09:
[
'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:
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:
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:
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:
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.
node report.js
$LASTEXITCODE
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.errorwrites to the error output, a channel of its own, separate from the normal outputconsole.logwrites to. Send the report to a file withnode report.js > week.txt, and the error still appears on the screen instead of hiding in the file.process.exitCode = 1tells 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. Runnode 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.