diff --git a/doc/api/cli.md b/doc/api/cli.md index fa269469160304..f50b22f729c283 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -320,6 +320,20 @@ Currently the support for run-time snapshot is experimental in that: a report in the [Node.js issue tracker][] and link to it in the [tracking issue for user-land snapshots][]. +### `-c`, `--check` + + + +Syntax check the script without executing. + ### `--completion-bash` - -Disables the family autoselection algorithm unless connection options explicitly -enables it. - ### `--enable-source-maps` + +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. + +```bash +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 `=`: + +```text +PORT=3000 +``` + +Any text after a `#` is treated as a comment: + +```text +# This is a comment +PORT=3000 # This is also a comment +``` + +Values can start and end with the following quotes: `\`, `"` or `'`. +They are omitted from the values. + +```text +USERNAME="nodejs" # will result in `nodejs` as the value. +``` + +### `-e`, `--eval "script"` + + + +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. + ### `--experimental-import-meta-resolve` - -Disable experimental support for the [Fetch API][]. - -### `--no-experimental-global-webcrypto` - - - -Disable exposition of [Web Crypto API][] on the global scope. - -### `--no-experimental-global-customevent` - - - -Disable exposition of [CustomEvent Web API][] on the global scope. - -### `--no-experimental-repl-await` - - - -Use this flag to disable top-level await in REPL. - ### `--experimental-sea-config` + +Enforces `uncaughtException` event on Node-API asynchronous callbacks. + +To prevent from an existing add-on from crashing the process, this flag is not +enabled by default. In the future, this flag will be enabled by default to +enforce the correct behavior. + ### `--frozen-intrinsics` -Enforces `uncaughtException` event on Node-API asynchronous callbacks. +> Stability: 1 - Experimental -To prevent from an existing add-on from crashing the process, this flag is not -enabled by default. In the future, this flag will be enabled by default to -enforce the correct behavior. +Starts the V8 heap profiler on start up, and writes the heap profile to disk +before exit. + +If `--heap-prof-dir` is not specified, the generated profile is placed +in the current working directory. + +If `--heap-prof-name` is not specified, the generated profile is +named `Heap.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.heapprofile`. + +```console +$ node --heap-prof index.js +$ ls *.heapprofile +Heap.20190409.202950.15293.0.001.heapprofile +``` + +### `--heap-prof-dir` + + + +> Stability: 1 - Experimental + +Specify the directory where the heap profiles generated by `--heap-prof` will +be placed. + +The default value is controlled by the +[`--diagnostic-dir`][] command-line option. + +### `--heap-prof-interval` + + + +> Stability: 1 - Experimental + +Specify the average sampling interval in bytes for the heap profiles generated +by `--heap-prof`. The default is 512 \* 1024 bytes. + +### `--heap-prof-name` + + + +> Stability: 1 - Experimental + +Specify the file name of the heap profile generated by `--heap-prof`. ### `--heapsnapshot-near-heap-limit=max_count` @@ -816,63 +900,14 @@ $ ls Heap.20190718.133405.15554.0.001.heapsnapshot ``` -### `--heap-prof` - - - -> Stability: 1 - Experimental - -Starts the V8 heap profiler on start up, and writes the heap profile to disk -before exit. - -If `--heap-prof-dir` is not specified, the generated profile is placed -in the current working directory. - -If `--heap-prof-name` is not specified, the generated profile is -named `Heap.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.heapprofile`. - -```console -$ node --heap-prof index.js -$ ls *.heapprofile -Heap.20190409.202950.15293.0.001.heapprofile -``` - -### `--heap-prof-dir` - - - -> Stability: 1 - Experimental - -Specify the directory where the heap profiles generated by `--heap-prof` will -be placed. - -The default value is controlled by the -[`--diagnostic-dir`][] command-line option. - -### `--heap-prof-interval` - - - -> Stability: 1 - Experimental - -Specify the average sampling interval in bytes for the heap profiles generated -by `--heap-prof`. The default is 512 \* 1024 bytes. - -### `--heap-prof-name` +### `-h`, `--help` -> Stability: 1 - Experimental - -Specify the file name of the heap profile generated by `--heap-prof`. +Print node command-line options. +The output of this option is less detailed than this document. ### `--icu-data-dir=file` @@ -909,28 +944,19 @@ Valid values are `"commonjs"` and `"module"`. The default is `"commonjs"`. The REPL does not support this option. -### `--inspect-brk[=[host:]port]` - - - -Activate inspector on `host:port` and break at start of user script. -Default `host:port` is `127.0.0.1:9229`. - -### `--inspect-port=[host:]port` +### `--insecure-http-parser` -Set the `host:port` to be used when the inspector is activated. -Useful when activating the inspector by sending the `SIGUSR1` signal. - -Default host is `127.0.0.1`. - -See the [security warning][] below regarding the `host` -parameter usage. +Use an insecure HTTP parser that accepts invalid HTTP headers. This may allow +interoperability with non-conformant HTTP implementations. It may also allow +request smuggling and other HTTP attacks that rely on invalid headers being +accepted. Avoid using this option. ### `--inspect[=[host:]port]` @@ -964,81 +990,56 @@ default) is not firewall-protected.** See the [debugging security implications][] section for more information. -### `--inspect-publish-uid=stderr,http` - -Specify ways of the inspector web socket url exposure. - -By default inspector websocket url is available in stderr and under `/json/list` -endpoint on `http://host:port/json/list`. - -### `--insecure-http-parser` +### `--inspect-brk[=[host:]port]` -Use an insecure HTTP parser that accepts invalid HTTP headers. This may allow -interoperability with non-conformant HTTP implementations. It may also allow -request smuggling and other HTTP attacks that rely on invalid headers being -accepted. Avoid using this option. +Activate inspector on `host:port` and break at start of user script. +Default `host:port` is `127.0.0.1:9229`. -### `--jitless` +### `--inspect-port=[host:]port` -Disable [runtime allocation of executable memory][jitless]. This may be -required on some platforms for security reasons. It can also reduce attack -surface on other platforms, but the performance impact may be severe. - -This flag is inherited from V8 and is subject to change upstream. It may -disappear in a non-semver-major release. - -### `--env-file=config` +Set the `host:port` to be used when the inspector is activated. +Useful when activating the inspector by sending the `SIGUSR1` signal. -> Stability: 1.1 - Active development +Default host is `127.0.0.1`. - +See the [security warning][] below regarding the `host` +parameter usage. -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. +### `--inspect-publish-uid=stderr,http` -You can pass multiple `--env-file` arguments. Subsequent files override -pre-existing variables defined in previous files. +Specify ways of the inspector web socket url exposure. -```bash -node --env-file=.env --env-file=.development.env index.js -``` +By default inspector websocket url is available in stderr and under `/json/list` +endpoint on `http://host:port/json/list`. -The format of the file should be one line per key-value pair of environment -variable name and value separated by `=`: +### `-i`, `--interactive` -```text -PORT=3000 -``` + -Any text after a `#` is treated as a comment: +Opens the REPL even if stdin does not appear to be a terminal. -```text -# This is a comment -PORT=3000 # This is also a comment -``` +### `--jitless` -Values can start and end with the following quotes: `\`, `"` or `'`. -They are omitted from the values. + -```text -USERNAME="nodejs" # will result in `nodejs` as the value. -``` +Disable [runtime allocation of executable memory][jitless]. This may be +required on some platforms for security reasons. It can also reduce attack +surface on other platforms, but the performance impact may be severe. + +This flag is inherited from V8 and is subject to change upstream. It may +disappear in a non-semver-major release. ### `--max-http-header-size=size` @@ -1082,6 +1083,38 @@ added: v0.8.0 Silence deprecation warnings. +### `--no-experimental-fetch` + + + +Disable experimental support for the [Fetch API][]. + +### `--no-experimental-global-customevent` + + + +Disable exposition of [CustomEvent Web API][] on the global scope. + +### `--no-experimental-global-webcrypto` + + + +Disable exposition of [Web Crypto API][] on the global scope. + +### `--no-experimental-repl-await` + + + +Use this flag to disable top-level await in REPL. + ### `--no-extra-info-on-fatal-exception` + +Disables the family autoselection algorithm unless connection options explicitly +enables it. + ### `--no-warnings` + +Enable OpenSSL 3.0 legacy provider. For more information please see +[OSSL\_PROVIDER-legacy][OSSL_PROVIDER-legacy]. + ### `--openssl-shared-config` - -Enable OpenSSL 3.0 legacy provider. For more information please see -[OSSL\_PROVIDER-legacy][OSSL_PROVIDER-legacy]. - ### `--pending-deprecation` + +Identical to `-e` but prints the result. + ### `--prof` + +Preload the specified module at startup. + +Follows `require()`'s module resolution +rules. `module` may be either a path to a file, or a node module name. + +Only CommonJS modules are supported. +Use [`--import`][] to preload an [ECMAScript module][]. +Modules preloaded with `--require` will run before modules preloaded with `--import`. + ### `--secure-heap=n` -A test reporter to use when running tests. See the documentation on -[test reporters][] for more details. +Configures the test runner to only execute top level tests that have the `only` +option set. -### `--test-reporter-destination` +### `--test-reporter` -The destination for the corresponding test reporter. See the documentation on +A test reporter to use when running tests. See the documentation on [test reporters][] for more details. -### `--test-only` +### `--test-reporter-destination` -Configures the test runner to only execute top level tests that have the `only` -option set. +The destination for the corresponding test reporter. See the documentation on +[test reporters][] for more details. ### `--test-shard` @@ -1918,6 +1993,14 @@ The amount of parallelism refers to the number of computations that can be carried out simultaneously in a given machine. In general, it's the same as the amount of CPUs, but it may diverge in environments such as VMs or containers. +### `-v`, `--version` + + + +Print node's version. + ### `--watch` - -Syntax check the script without executing. - -### `-e`, `--eval "script"` - - - -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. - -### `-h`, `--help` - - - -Print node command-line options. -The output of this option is less detailed than this document. - -### `-i`, `--interactive` - - - -Opens the REPL even if stdin does not appear to be a terminal. - -### `-p`, `--print "script"` - - - -Identical to `-e` but prints the result. - -### `-r`, `--require module` - - - -Preload the specified module at startup. - -Follows `require()`'s module resolution -rules. `module` may be either a path to a file, or a node module name. - -Only CommonJS modules are supported. -Use [`--import`][] to preload an [ECMAScript module][]. -Modules preloaded with `--require` will run before modules preloaded with `--import`. - -### `-v`, `--version` - - - -Print node's version. - ## Environment variables ### `FORCE_COLOR=[1, 2, 3]` @@ -2091,6 +2091,11 @@ and `NODE_DISABLE_COLORS` environment variables are ignored. Any other value will result in colorized output being disabled. +### `NO_COLOR=` + +[`NO_COLOR`][] is an alias for `NODE_DISABLE_COLORS`. The value of the +environment variable is arbitrary. + ### `NODE_DEBUG=module[,…]` - -Path to the file used to store the persistent REPL history. The default path is -`~/.node_repl_history`, which is overridden by this variable. Setting the value -to an empty string (`''` or `' '`) disables persistent REPL history. - ### `NODE_REPL_EXTERNAL_MODULE=file` + +Path to the file used to store the persistent REPL history. The default path is +`~/.node_repl_history`, which is overridden by this variable. Setting the value +to an empty string (`''` or `' '`) disables persistent REPL history. + ### `NODE_SKIP_PLATFORM_CHECK=value`