process: environment, arguments and exit code

A program is not only its code: it starts inside a process that has an environment, a list of arguments, a working directory and an exit status. process is the object that holds all four, and every one of them arrives from outside, which is why a tool can be configured without a rebuild.

The lesson reads a variable that the shell sets, prints the arguments a script was given, resolves a relative name against the working directory without printing that directory, and ends with the exit code a failing run leaves behind. The four programs use only Node.js and its node:path module.

process.env

process.env is an object of the environment variables that the parent process passed. Every value is a string, including the ones that look like numbers, and a name that nobody set is undefined rather than an empty string. The traditional way to run a program with one variable is to write it before the command.

The program reads a greeting that the command sets and a name that nothing sets, and prints the type of the second. It also reads the greeting again through destructuring, which is the shorter form.

The file env.mjs:

console.log('the greeting:', process.env.GREETING); const { GREETING, MISSING_NAME } = process.env; console.log('a name that is not set is:', typeof MISSING_NAME); console.log('the greeting has', GREETING.length, 'characters'); console.log('the missing name is undefined:', MISSING_NAME === undefined);

GREETING=hello node env.mjs

the greeting: hello
a name that is not set is: undefined
the greeting has 5 characters
the missing name is undefined: true

The missing name is undefined and not a string, so a default has to come from the program: process.env.GREETING ?? 'hello' is the usual line. A variable is also how a program learns a secret without the secret sitting in an argument list that the whole machine can read.

process.argv

process.argv is an array of strings: the runtime, the script and then whatever the command line held. The first two entries belong to the runtime, so the arguments of the program start at index two, and slice(2) is the line that every tool begins with.

The program prints the two entries it did not write, then the arguments it was given. The command passes a command word, a flag and a file name, and the program prints them in order.

The file argv.mjs:

import { basename } from 'node:path'; console.log('the runtime:', basename(process.argv[0])); console.log('the script:', basename(process.argv[1])); const args = process.argv.slice(2); console.log('the number of arguments:', args.length); console.log('the arguments:', args.join(' ')); console.log('the first one is the command:', args[0]);

node argv.mjs build --verbose out.txt

the runtime: node
the script: argv.mjs
the number of arguments: 3
the arguments: build --verbose out.txt
the first one is the command: build

The two paths are printed as base names, because argv[0] and argv[1] hold full paths that differ on every machine. The three arguments arrived as strings and in the order of the command, and it is the program that decides which of them is a command, a flag or a value.

process.cwd

process.cwd() answers with the working directory, the folder from which the program was started, and it is always an absolute path. A relative path in a program is resolved against it, which is why the same command behaves differently in two folders. resolve from node:path makes the resolution explicit.

The program prints that the directory is absolute, then resolves a relative name against it and prints the two last parts of the result. The full directory is never printed, because it would differ on every machine and every checkout.

The file cwd.mjs:

import { basename, dirname, isAbsolute, resolve } from 'node:path'; const cwd = process.cwd(); console.log('the working directory is absolute:', isAbsolute(cwd)); const file = resolve('data', 'notes.txt'); console.log('a relative name becomes:', basename(file)); console.log('inside the folder:', basename(dirname(file))); console.log('the result is absolute:', isAbsolute(file));

node cwd.mjs

the working directory is absolute: true
a relative name becomes: notes.txt
inside the folder: data
the result is absolute: true

The file name and the folder came from the relative name of the source, and the absolute path stayed inside the program. A tool that writes an output file should either take the path as an argument or say in its usage text which folder it resolves against, and the next lesson builds one that does.

process.exitCode

The exit status is the number the shell reads as $?, and a program sets it through process.exitCode. At the start the property is undefined, which ends the run with zero; setting it later changes the status without stopping the program. process.exit(2) does stop it at once, and that is exactly why it is the wrong tool: output that is still being written can be lost.

The program reads the status before anything happened, catches a failure, sets the status and prints it again. The command prints what the shell saw.

The file exitcode.mjs:

console.log('the exit code at the start is', process.exitCode); try { throw new Error('the disk is full'); } catch (error) { console.log('the failure:', error.message); process.exitCode = 2; } console.log('the program ends with code', process.exitCode);

node exitcode.mjs
echo "exit code: $?"

the exit code at the start is undefined
the failure: the disk is full
the program ends with code 2
exit code: 2

The shell saw two, and every line of the program was printed, which would not be guaranteed after process.exit. The rule that follows is short: catch the failure near the top of the program, set process.exitCode and let the event loop empty itself.

Exercises

  1. Print every environment variable whose name starts with a chosen prefix, sorted by name. Which method turns the object into pairs?
  2. Run argv.mjs with no arguments. What does the program print for the first argument, and why?
  3. Resolve a relative name against the working directory and print only the base name. Why is the whole path a bad thing to print?
  4. Set process.exitCode to zero after a failure and check what the shell reports. What does the caller learn?
  5. Replace the last assignment with process.exit(2) and run the program through a pipe. Which lines survive?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. Where do the arguments of a script start in process.argv?

    Answer

    At index 2

    The first two entries are the runtime and the script, so slice(2) is the list of arguments.

  2. What does this program print? console.log(typeof process.env.NOT_SET_BY_THE_COURSE);

    Answer

    undefined

    A variable that nobody set is missing from the object, so reading it gives undefined.

  3. What does process.env hold?

    Answer

    The environment variables, every value a string

    The environment comes from the parent process, and a shell can only pass text.

  4. What does this program print? console.log(typeof process.exitCode);

    Answer

    undefined

    Nothing has set a status yet, so the property has no value.

  5. What is process.cwd()?

    Answer

    The working directory as an absolute path

    It is the folder the program was started from, which is not always the one the script is in.

  6. What does this program print? const args = ["node", "tool.mjs", "build", "-v"]; console.log(args.slice(2).join(" "));

    Answer

    build -v

    slice(2) drops the runtime and the script name.

  7. What does process.exitCode do?

    Answer

    It sets the status the process ends with

    The program keeps running and the status is used when the event loop is empty.

  8. What does this program print? process.exitCode = 2; console.log(process.exitCode);

    Answer

    2

    The property keeps the value that was set, and the process still has work to do.

  9. Can an environment variable hold a number?

    Answer

    No, every value is a string and the program converts it

    The environment is text, so Number(process.env.PORT) is a line every server has.

  10. What ends a program that never calls process.exit?

    Answer

    The event loop becoming empty

    Node.js waits for the pending work, and then the status in process.exitCode is used.

The code on this page was run with Node.js 24.22.1 and linted with ESLint 10.14.0 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev