Node.js Reference ยท CLI Flags
Running Node.js files: node file
Reference for the node command: run a file, a package or standard input, how arguments and exit codes work, and how Node decides between ES modules and CommonJS.
The node command starts the runtime. Given a file name it loads that file as the program's entry point, runs it, and then keeps going as long as there is work left (open servers, pending timers). When nothing is left, the process exits with code 0. If you give it no file and stdin is a terminal, you get the interactive REPL.
The argument after the flags is the script; anything after the script goes to your program in process.argv. Flags placed before the script belong to Node itself.
node app.js
node --watch app.js first second
Try it
The live examples start a child Node process with the same executable, so they show what the command does.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
node [options] [V8 options] [script.js | -e "script" | -] [arguments] node inspect [script.js | host:port] [arguments]
| Part | Description |
|---|---|
options |
Node flags such as --watch or --env-file=.env. They must come before the script name. |
script |
Path to the entry file. The extension may be left off for CommonJS (node app), which resolves app.js, app.json, app/index.js, and so on. |
- |
Read the program from standard input. |
arguments |
Passed through to the program. process.argv[0] is the node executable, [1] the script path, the rest your arguments. |
-- |
Ends Node's option parsing; useful when a script name starts with a dash. |
Exit codes: 0 for success, 1 for an uncaught exception or other fatal error, 9 for an invalid option, and any value you set through process.exitCode or process.exit(). Signals show up as 128 + signal number in a shell.
Usage notes
- CommonJS or ES module?
.mjsis always an ES module,.cjsalways CommonJS. For.js, the nearestpackage.jsondecides:"type": "module"or"commonjs". If there is notype, Node 22 and later inspect the file and run it as ESM when it containsimport/exportsyntax; to be sure, settypeexplicitly. - Run a package directory.
node .ornode folderloads the folder'spackage.jsonmainfield (orindex.js). - Arguments belong to the script.
node app.js --watchpasses--watchto your program;node --watch app.jsgives the flag to Node. Parse program arguments withutil.parseArgs(). - Process lifetime. Node exits when the event loop is empty. A listening server or an active timer keeps it alive; call
process.exit()or close handles to stop sooner, and preferprocess.exitCodeso pending output can flush. - Shebang lines (
#!/usr/bin/env node) are ignored by the parser, so the same file works as an executable and undernode file. - Environment.
NODE_OPTIONScan add flags for every run; seeNODE_OPTIONS. - Piping.
echo 'console.log(1)' | nodealso works when stdin is not a terminal.
Related
-e and -p,--check,--watch,process.argv,process.exit()- Lessons: Running code, CLI tools