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`.

Execute without arguments to start the [REPL][].

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

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 entry point string is then resolved as if it's been requested

by `require()` from the current working directory. If no corresponding file

is found, an error is thrown.

By default, the resolved path is also loaded as if it's been requested by `require()`,

unless one of the conditions below apply—then it's loaded as if it's been requested

by `import()`:

* 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`, `.mts` or `.wasm` 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"`.

See [module resolution and loading][] for more details.

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.

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.

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.

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).

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:

require('nodejs-addon-example');

$ node --permission --allow-fs-read=* index.js

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 the `--allow-child-process` flag when starting Node.js.

Example:

const childProcess = require('node:child_process');

childProcess.spawn('node', ['-e', 'require("fs").writeFileSync("/new-file", "example")']);

$ node --permission --allow-fs-read=* index.js

The `child_process.fork()` API inherits the execution arguments from the

parent process. This means that if Node.js is started with the Permission

Model enabled and the `--allow-child-process` flag is set, any child process

created using `child_process.fork()` will automatically receive all relevant

Permission Model flags.

This behavior also applies to `child_process.spawn()`, but in that case, the

flags are propagated via the `NODE_OPTIONS` environment variable rather than

directly through the process arguments.

This flag configures file system read permissions using

the [Permission Model][].

The valid arguments for the `--allow-fs-read` flag are:

* `*` - To allow all `FileSystemRead` operations.

* Multiple paths can be allowed using multiple `--allow-fs-read` flags.

Example `--allow-fs-read=/folder1/ --allow-fs-read=/folder1/`

Examples can be found in the [File System Permissions][] documentation.

The initializer module and custom `--require` modules has a implicit

read permission.

$ node --permission -r custom-require.js -r custom-require-2.js index.js

* The `custom-require.js`, `custom-require-2.js`, and `index.js` will be

by default in the allowed read list.

process.has('fs.read', 'index.js'); // true

process.has('fs.read', 'custom-require.js'); // true

process.has('fs.read', 'custom-require-2.js'); // true

This flag configures file system write permissions using

the [Permission Model][].

The valid arguments for the `--allow-fs-write` flag are:

* `*` - To allow all `FileSystemWrite` operations.

* Multiple paths can be allowed using multiple `--allow-fs-write` flags.

Example `--allow-fs-write=/folder1/ --allow-fs-write=/folder1/`

Paths delimited by comma (`,`) are no longer allowed.

When passing a single flag with a comma a warning will be displayed.

Examples can be found in the [File System Permissions][] documentation.

When using the [Permission Model][], the process will not be able to connect

through inspector protocol.

Attempts to do so will throw an `ERR_ACCESS_DENIED` unless the

user explicitly passes the `--allow-inspector` flag when starting Node.js.

Example:

const { Session } = require('node:inspector/promises');

const session = new Session();

session.connect();

$ node --permission index.js

When using the [Permission Model][], the process will not be able to access

network by default.

Attempts to do so will throw an `ERR_ACCESS_DENIED` unless the

user explicitly passes the `--allow-net` flag when starting Node.js.

Example:

const http = require('node:http');

const req = http.get('http://example.com', () => {});

req.on('error', (err) => {

console.log('err', err);

});

$ node --permission index.js

When using the [Permission Model][], the process will not be capable of creating

any WASI instances by default.

For security reasons, the call will throw an `ERR_ACCESS_DENIED` unless the

user explicitly passes the flag `--allow-wasi` in the main Node.js process.

Example:

const { WASI } = require('node:wasi');

new WASI({

version: 'preview1',

// Attempt to mount the whole filesystem

preopens: {

'/': '/',

},

});

$ node --permission --allow-fs-read=* index.js

When using the [Permission Model][], the process will not be able to create any

worker threads by default.

For security reasons, the call will throw an `ERR_ACCESS_DENIED` unless the

user explicitly pass the flag `--allow-worker` in the main Node.js process.

Example:

const { Worker } = require('node:worker_threads');

new Worker(__filename);

$ node --permission --allow-fs-read=* index.js

Generates a snapshot blob when the process exits and writes it to

disk, which can be loaded later with `--snapshot-blob`.

When building the snapshot, if `--snapshot-blob` is not specified,

the generated blob will be written, by default, to `snapshot.blob`

in the current working directory. Otherwise it will be written to

the path specified by `--snapshot-blob`.

$ echo "globalThis.foo = 'I am from the snapshot'" > snapshot.js

# Run snapshot.js to initialize the application and snapshot the

# state of it into snapshot.blob.

$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js

$ echo "console.log(globalThis.foo)" > index.js

# Load the generated snapshot and start the application from index.js.

$ node --snapshot-blob snapshot.blob index.js

The [`v8.startupSnapshot` API][] can be used to specify an entry point at

snapshot building time, thus avoiding the need of an additional entry

script at deserialization time:

$ echo "require('v8').startupSnapshot.setDeserializeMainFunction(() => console.log('I am from the snapshot'))" > snapshot.js

$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js

$ node --snapshot-blob snapshot.blob

For more information, check out the [`v8.startupSnapshot` API][] documentation.

Currently the support for run-time snapshot is experimental in that:

1. User-land modules are not yet supported in the snapshot, so only

one single file can be snapshotted. Users can bundle their applications

into a single script with their bundler of choice before building

a snapshot, however.

2. Only a subset of the built-in modules work in the snapshot, though the

Node.js core test suite checks that a few fairly complex applications

can be snapshotted. Support for more modules are being added. If any

crashes or buggy behaviors occur when building a snapshot, please file

a report in the [Node.js issue tracker][] and link to it in the

[tracking issue for user-land snapshots][].

Specifies the path to a JSON configuration file which configures snapshot

creation behavior.

The following options are currently supported:

* `builder` {string} Required. Provides the name to the script that is executed

before building the snapshot, as if [`--build-snapshot`][] had been passed

with `builder` as the main script name.

* `withoutCodeCache` {boolean} Optional. Including the code cache reduces the

time spent on compiling functions included in the snapshot at the expense

of a bigger snapshot size and potentially breaking portability of the

snapshot.

When using this flag, additional script files provided on the command line will

not be executed and instead be interpreted as regular command line arguments.

Syntax check the script without executing.

Print source-able bash completion script for Node.js.

node --completion-bash > node_bash_completion

source node_bash_completion

Provide custom [conditional exports][] resolution conditions.

Any number of custom string condition names are permitted.

The default Node.js conditions of `"node"`, `"default"`, `"import"`, and

`"require"` will always apply as defined.

For example, to run a module with "development" resolutions:

node -C development app.js

Starts the V8 CPU profiler on start up, and writes the CPU profile to disk

before exit.

If `--cpu-prof-dir` is not specified, the generated profile is placed

in the current working directory.

If `--cpu-prof-name` is not specified, the generated profile is

named `CPU.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.cpuprofile`.

$ node --cpu-prof index.js

$ ls *.cpuprofile

If `--cpu-prof-name` is specified, the provided value is used as a template

for the file name. The following placeholder is supported and will be

substituted at runtime:

* `${pid}` — the current process ID

$ node --cpu-prof --cpu-prof-name 'CPU.${pid}.cpuprofile' index.js

$ ls *.cpuprofile

Specify the directory where the CPU profiles generated by `--cpu-prof` will

be placed.

The default value is controlled by the

[`--diagnostic-dir`][] command-line option.

Specify the sampling interval in microseconds for the CPU profiles generated

by `--cpu-prof`. The default is 1000 microseconds.

Specify the file name of the CPU profile generated by `--cpu-prof`.

Set the directory to which all diagnostic output files are written.

Defaults to current working directory.

Affects the default output directory of:

* [`--cpu-prof-dir`][]

* [`--heap-prof-dir`][]

* [`--redirect-warnings`][]

Disable the `Object.prototype.__proto__` property. If `mode` is `delete`, the

property is removed entirely. If `mode` is `throw`, accesses to the

property throw an exception with the code `ERR_PROTO_ACCESS`.

Disable the ability of starting a debugging session by sending a

`SIGUSR1` signal to the process.

Disable specific process warnings by `code` or `type`.

Warnings emitted from [`process.emitWarning()`][emit_warning] may contain a

`code` and a `type`. This option will not-emit warnings that have a matching

`code` or `type`.

List of [deprecation warnings][].

The Node.js core warning types are: `DeprecationWarning` and

For example, the following script will not emit

[DEP0025 `require('node:sys')`][DEP0025 warning] when executed with

`node --disable-warning=DEP0025`:

import sys from 'node:sys';

const sys = require('node:sys');

For example, the following script will emit the

[DEP0025 `require('node:sys')`][DEP0025 warning], but not any Experimental

Warnings (such as

[ExperimentalWarning: `vm.measureMemory` is an experimental feature][]

in <=v21) when executed with `node --disable-warning=ExperimentalWarning`:

import sys from 'node:sys';

import vm from 'node:vm';

vm.measureMemory();

const sys = require('node:sys');

const vm = require('node:vm');

vm.measureMemory();

By default, Node.js enables trap-handler-based WebAssembly bound

checks. As a result, V8 does not need to insert inline bound checks

int the code compiled from WebAssembly which may speedup WebAssembly

execution significantly, but this optimization requires allocating

a big virtual memory cage (currently 10GB). If the Node.js process

does not have access to a large enough virtual memory address space

due to system configurations or hardware limitations, users won't

be able to run any WebAssembly that involves allocation in this

virtual memory cage and will see an out-of-memory error.

$ ulimit -v 5000000

$ node -p "new WebAssembly.Memory({ initial: 10, maximum: 100 });"

`--disable-wasm-trap-handler` disables this optimization so that

users can at least run WebAssembly (with less optimal performance)

when the virtual memory address space available to their Node.js

process is lower than what the V8 WebAssembly memory cage needs.

Make built-in language features like `eval` and `new Function` that generate

code from strings throw an exception instead. This does not affect the Node.js

`node:vm` module.

Set the default value of `order` in [`dns.lookup()`][] and

[`dnsPromises.lookup()`][]. The value could be:

* `ipv4first`: sets default `order` to `ipv4first`.

* `ipv6first`: sets default `order` to `ipv6first`.

* `verbatim`: sets default `order` to `verbatim`.

The default is `verbatim` and [`dns.setDefaultResultOrder()`][] have higher

priority than `--dns-result-order`.

Enable FIPS-compliant crypto at startup. (Requires Node.js to be built

against FIPS-compatible OpenSSL.)

Enables the family autoselection algorithm unless connection options explicitly

disables it.

Enable [Source Map][] support for stack traces.

When using a transpiler, such as TypeScript, stack traces thrown by an

application reference the transpiled code, not the original source position.

`--enable-source-maps` enables caching of Source Maps and makes a best

effort to report stack traces relative to the original source file.

Overriding `Error.prepareStackTrace` may prevent `--enable-source-maps` from

modifying the stack trace. Call and return the results of the original

`Error.prepareStackTrace` in the overriding function to modify the stack trace

with source maps.

const originalPrepareStackTrace = Error.prepareStackTrace;

Error.prepareStackTrace = (error, trace) => {

// Modify error and trace and format stack trace with

// original Error.prepareStackTrace.

return originalPrepareStackTrace(error, trace);

};

Note, enabling source maps can introduce latency to your application

when `Error.stack` is accessed. If you access `Error.stack` frequently

in your application, take into account the performance implications

of `--enable-source-maps`.

When present, Node.js will interpret the entry point as a URL, rather than a

path.

Follows [ECMAScript module][] resolution rules.

Any query parameter or hash in the URL will be accessible via [`import.meta.url`][].

node --entry-url 'file:///path/to/file.js?queryparams=work#and-hashes-too'

node --entry-url 'file.ts?query#hash'

node --entry-url 'data:text/javascript,console.log("Hello")'

Behavior is the same as [`--env-file`][], but an error is not thrown if the file

does not exist.

Loads environment variables from a file relative to the current directory,

making them available to applications on `process.env`. The [environment

variables which configure Node.js][environment_variables], such as `NODE_OPTIONS`,

are parsed and applied. If the same variable is defined in the environment and

in the file, the value from the environment takes precedence.

You can pass multiple `--env-file` arguments. Subsequent files override

pre-existing variables defined in previous files.

An error is thrown if the file does not exist.

node --env-file=.env --env-file=.development.env index.js

The format of the file should be one line per key-value pair of environment

variable name and value separated by `=`:

Any text after a `#` is treated as a comment:

Values can start and end with the following quotes: `` ` ``, `"` or `'`.

They are omitted from the values.

Multi-line values are supported:

Export keyword before a key is ignored:

If you want to load environment variables from a file that may not exist, you

can use the [`--env-file-if-exists`][] flag instead.

Evaluate the following argument as JavaScript. The modules which are

predefined in the REPL can also be used in `script`.

On Windows, using `cmd.exe` a single quote will not work correctly because it

only recognizes double `"` for quoting. In Powershell or Git bash, both `'`

and `"` are usable.

It is possible to run code containing inline types unless the

[`--no-strip-types`][] flag is provided.

Enable experimental import support for `.node` addons.