Command-line API#

Node.js comes with a variety of CLI options. These options expose built-in debugging, multiple ways to execute scripts, and other helpful runtime options.

To view this documentation as a manual page in a terminal, run man node.

Synopsis#

node [options] [V8 options] [<program-entry-point> | -e "script" | -] [--] [arguments]

node inspect [<program-entry-point> | -e "script" | <host>:<port>] …

node --v8-options

Execute without arguments to start the REPL.

For more info about node inspect, see the debugger documentation.

Program entry point#

The program entry point is a specifier-like string. If the string is not an absolute path, it's resolved as a relative path from the current working directory. That path is then resolved by CommonJS module loader. If no corresponding file is found, an error is thrown.

If a file is found, its path will be passed to the ES module loader under any of the following conditions:

  • The program was started with a command-line flag that forces the entry point to be loaded with ECMAScript module loader, such as --import.
  • The file has an .mjs or .wasm (with --experimental-wasm-modules) extension.
  • The file does not have a .cjs extension, and the nearest parent package.json file contains a top-level "type" field with a value of "module".

Otherwise, the file is loaded using the CommonJS module loader. See Modules loaders for more details.

ECMAScript modules loader entry point caveat#

When loading, the ES module loader loads the program entry point, the node command will accept as input only files with .js, .mjs, or .cjs extensions. With the following flags, additional file extensions are enabled:

Options#

History
VersionChanges
v10.12.0

Underscores instead of dashes are now allowed for Node.js options as well, in addition to V8 options.

Stability: 2 - Stable

All options, including V8 options, allow words to be separated by both dashes (-) or underscores (_). For example, --pending-deprecation is equivalent to --pending_deprecation.

If an option that takes a single value (such as --max-http-header-size) is passed more than once, then the last passed value is used. Options from the command line take precedence over options passed through the NODE_OPTIONS environment variable.

-#

Added in: v8.0.0

Alias for stdin. Analogous to the use of - in other command-line utilities, meaning that the script is read from stdin, and the rest of the options are passed to that script.

--#

Added in: v6.11.0

Indicate the end of node options. Pass the rest of the arguments to the script. If no script filename or eval/print script is supplied prior to this, then the next argument is used as a script filename.

--abort-on-uncaught-exception#

Added in: v0.10.8

Aborting instead of exiting causes a core file to be generated for post-mortem analysis using a debugger (such as lldb, gdb, and mdb).

If this flag is passed, the behavior can still be set to not abort through process.setUncaughtExceptionCaptureCallback() (and through usage of the node:domain module that uses it).

--allow-addons#

Added in: v21.6.0, v20.12.0

Stability: 1.1 - Active development

When using the Permission Model, the process will not be able to use native addons by default. Attempts to do so will throw an ERR_DLOPEN_DISABLED unless the user explicitly passes the --allow-addons flag when starting Node.js.

Example:

// Attempt to require an native addon
require('nodejs-addon-example'); 
$ node --permission --allow-fs-read=* index.js
node:internal/modules/cjs/loader:1319
  return process.dlopen(module, path.toNamespacedPath(filename));
                 ^

Error: Cannot load native addon because loading addons is disabled.
    at Module._extensions..node (node:internal/modules/cjs/loader:1319:18)
    at Module.load (node:internal/modules/cjs/loader:1091:32)
    at Module._load (node:internal/modules/cjs/loader:938:12)
    at Module.require (node:internal/modules/cjs/loader:1115:19)
    at require (node:internal/modules/helpers:130:18)
    at Object.<anonymous> (/home/index.js:1:15)
    at Module._compile (node:internal/modules/cjs/loader:1233:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1287:10)
    at Module.load (node:internal/modules/cjs/loader:1091:32)
    at Module._load (node:internal/modules/cjs/loader:938:12) {
  code: 'ERR_DLOPEN_DISABLED'
}

--allow-child-process#

Added in: v20.0.0

Stability: 1.1 - Active development

When using the Permission Model, the process will not be able to spawn any child process by default. Attempts to do so will throw an ERR_ACCESS_DENIED unless the user explicitly passes