1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: alphabetize cli.md sections

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/49668
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Harshitha K P <harshitha014@gmail.com>
This commit is contained in:
Geoffrey Booth 2023-09-17 15:00:10 -07:00 committed by GitHub
parent a71e3a65bb
commit cdcb01a144
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 311 additions and 311 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

622
doc/api/cli.md
View File

@ -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`
<!-- YAML
added:
- v5.0.0
- v4.2.0
changes:
- version: v10.0.0
pr-url: https://github.com/nodejs/node/pull/19600
description: The `--require` option is now supported when checking a file.
-->
Syntax check the script without executing.
### `--completion-bash`
<!-- YAML
@ -478,21 +492,6 @@ added: v6.0.0
Enable FIPS-compliant crypto at startup. (Requires Node.js to be built
against FIPS-compatible OpenSSL.)
### `--no-network-family-autoselection`
<!-- YAML
added: v19.4.0
changes:
- version: v20.0.0
pr-url: https://github.com/nodejs/node/pull/46790
description: The flag was renamed from `--no-enable-network-family-autoselection`
to `--no-network-family-autoselection`. The old name can still work as
an alias.
-->
Disables the family autoselection algorithm unless connection options explicitly
enables it.
### `--enable-source-maps`
<!-- YAML
@ -520,6 +519,65 @@ when `Error.stack` is accessed. If you access `Error.stack` frequently
in your application, take into account the performance implications
of `--enable-source-maps`.
### `--env-file=config`
> Stability: 1.1 - Active development
<!-- YAML
added: v20.6.0
-->
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"`
<!-- YAML
added: v0.5.2
changes:
- version: v5.11.0
pr-url: https://github.com/nodejs/node/pull/5348
description: Built-in libraries are now available as predefined variables.
-->
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`
<!-- YAML
@ -593,38 +651,6 @@ added: v11.8.0
Use the specified file as a security policy.
### `--no-experimental-fetch`
<!-- YAML
added: v18.0.0
-->
Disable experimental support for the [Fetch API][].
### `--no-experimental-global-webcrypto`
<!-- YAML
added: v19.0.0
-->
Disable exposition of [Web Crypto API][] on the global scope.
### `--no-experimental-global-customevent`
<!-- YAML
added: v19.0.0
-->
Disable exposition of [CustomEvent Web API][] on the global scope.
### `--no-experimental-repl-await`
<!-- YAML
added: v16.6.0
-->
Use this flag to disable top-level await in REPL.
### `--experimental-sea-config`
<!-- YAML
@ -720,6 +746,20 @@ added: v6.0.0
Force FIPS-compliant crypto on startup. (Cannot be disabled from script code.)
(Same requirements as `--enable-fips`.)
### `--force-node-api-uncaught-exceptions-policy`
<!-- YAML
added:
- v18.3.0
- v16.17.0
-->
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`
<!-- YAML
@ -737,19 +777,63 @@ under this flag.
To allow polyfills to be added,
[`--require`][] and [`--import`][] both run before freezing intrinsics.
### `--force-node-api-uncaught-exceptions-policy`
### `--heap-prof`
<!-- YAML
added:
- v18.3.0
- v16.17.0
added: v12.4.0
-->
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`
<!-- YAML
added: v12.4.0
-->
> 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`
<!-- YAML
added: v12.4.0
-->
> 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`
<!-- YAML
added: v12.4.0
-->
> Stability: 1 - Experimental
Specify the file name of the heap profile generated by `--heap-prof`.
### `--heapsnapshot-near-heap-limit=max_count`
@ -820,63 +904,14 @@ $ ls
Heap.20190718.133405.15554.0.001.heapsnapshot
```
### `--heap-prof`
### `-h`, `--help`
<!-- YAML
added: v12.4.0
added: v0.1.3
-->
> 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`
<!-- YAML
added: v12.4.0
-->
> 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`
<!-- YAML
added: v12.4.0
-->
> 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`
<!-- YAML
added: v12.4.0
-->
> 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`
@ -913,28 +948,32 @@ Valid values are `"commonjs"` and `"module"`. The default is `"commonjs"`.
The REPL does not support this option.
### `--inspect-brk[=[host:]port]`
### `--insecure-http-parser`
<!-- YAML
added: v7.6.0
added:
- v13.4.0
- v12.15.0
- v10.19.0
-->
Activate inspector on `host:port` and break at start of user script.
Default `host:port` is `127.0.0.1:9229`.
Enable leniency flags on the HTTP parser. This may allow
interoperability with non-conformant HTTP implementations.
### `--inspect-port=[host:]port`
When enabled, the parser will accept the following:
<!-- YAML
added: v7.6.0
-->
* Invalid HTTP headers values.
* Invalid HTTP versions.
* Allow message containing both `Transfer-Encoding`
and `Content-Length` headers.
* Allow extra data after message when `Connection: close` is present.
* Allow extra trasfer encodings after `chunked` has been provided.
* Allow `\n` to be used as token separator instead of `\r\n`.
* Allow `\r\n` not to be provided after a chunk.
* Allow spaces to be present after a chunk size and before `\r\n`.
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.
All the above will expose your application to request smuggling
or poisoning attack. Avoid using this option.
### `--inspect[=[host:]port]`
@ -968,6 +1007,29 @@ default) is not firewall-protected.**
See the [debugging security implications][] section for more information.
### `--inspect-brk[=[host:]port]`
<!-- YAML
added: v7.6.0
-->
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`
<!-- YAML
added: v7.6.0
-->
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.
### `--inspect-publish-uid=stderr,http`
Specify ways of the inspector web socket url exposure.
@ -975,32 +1037,13 @@ 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`
### `-i`, `--interactive`
<!-- YAML
added:
- v13.4.0
- v12.15.0
- v10.19.0
added: v0.7.7
-->
Enable leniency flags on the HTTP parser. This may allow
interoperability with non-conformant HTTP implementations.
When enabled, the parser will accept the following:
* Invalid HTTP headers values.
* Invalid HTTP versions.
* Allow message containing both `Transfer-Encoding`
and `Content-Length` headers.
* Allow extra data after message when `Connection: close` is present.
* Allow extra trasfer encodings after `chunked` has been provided.
* Allow `\n` to be used as token separator instead of `\r\n`.
* Allow `\r\n` not to be provided after a chunk.
* Allow spaces to be present after a chunk size and before `\r\n`.
All the above will expose your application to request smuggling
or poisoning attack. Avoid using this option.
Opens the REPL even if stdin does not appear to be a terminal.
### `--jitless`
@ -1015,48 +1058,6 @@ 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`
> Stability: 1.1 - Active development
<!-- YAML
added: v20.6.0
-->
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.
```
### `--max-http-header-size=size`
<!-- YAML
@ -1099,6 +1100,38 @@ added: v0.8.0
Silence deprecation warnings.
### `--no-experimental-fetch`
<!-- YAML
added: v18.0.0
-->
Disable experimental support for the [Fetch API][].
### `--no-experimental-global-customevent`
<!-- YAML
added: v19.0.0
-->
Disable exposition of [CustomEvent Web API][] on the global scope.
### `--no-experimental-global-webcrypto`
<!-- YAML
added: v19.0.0
-->
Disable exposition of [Web Crypto API][] on the global scope.
### `--no-experimental-repl-await`
<!-- YAML
added: v16.6.0
-->
Use this flag to disable top-level await in REPL.
### `--no-extra-info-on-fatal-exception`
<!-- YAML
@ -1125,6 +1158,21 @@ added: v16.10.0
Do not search modules from global paths like `$HOME/.node_modules` and
`$NODE_PATH`.
### `--no-network-family-autoselection`
<!-- YAML
added: v19.4.0
changes:
- version: v20.0.0
pr-url: https://github.com/nodejs/node/pull/46790
description: The flag was renamed from `--no-enable-network-family-autoselection`
to `--no-network-family-autoselection`. The old name can still work as
an alias.
-->
Disables the family autoselection algorithm unless connection options explicitly
enables it.
### `--no-warnings`
<!-- YAML
@ -1154,6 +1202,17 @@ Load an OpenSSL configuration file on startup. Among other uses, this can be
used to enable FIPS-compliant crypto if Node.js is built
against FIPS-enabled OpenSSL.
### `--openssl-legacy-provider`
<!-- YAML
added:
- v17.0.0
- v16.17.0
-->
Enable OpenSSL 3.0 legacy provider. For more information please see
[OSSL\_PROVIDER-legacy][OSSL_PROVIDER-legacy].
### `--openssl-shared-config`
<!-- YAML
@ -1172,17 +1231,6 @@ is being linked to Node.js. Sharing the OpenSSL configuration may have unwanted
implications and it is recommended to use a configuration section specific to
Node.js which is `nodejs_conf` and is default when this option is not used.
### `--openssl-legacy-provider`
<!-- YAML
added:
- v17.0.0
- v16.17.0
-->
Enable OpenSSL 3.0 legacy provider. For more information please see
[OSSL\_PROVIDER-legacy][OSSL_PROVIDER-legacy].
### `--pending-deprecation`
<!-- YAML
@ -1275,6 +1323,18 @@ resolving relative paths.
See [`--preserve-symlinks`][] for more information.
### `-p`, `--print "script"`
<!-- YAML
added: v0.6.4
changes:
- version: v5.11.0
pr-url: https://github.com/nodejs/node/pull/5348
description: Built-in libraries are now available as predefined variables.
-->
Identical to `-e` but prints the result.
### `--prof`
<!-- YAML
@ -1444,6 +1504,21 @@ Enables report to be generated when the process exits due to an uncaught
exception. Useful when inspecting the JavaScript stack in conjunction with
native stack and other runtime environment data.
### `-r`, `--require module`
<!-- YAML
added: v1.6.0
-->
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`
<!-- YAML
@ -1541,6 +1616,21 @@ A regular expression that configures the test runner to only execute tests
whose name matches the provided pattern. See the documentation on
[filtering tests by name][] for more details.
### `--test-only`
<!-- YAML
added:
- v18.0.0
- v16.17.0
changes:
- version: v20.0.0
pr-url: https://github.com/nodejs/node/pull/46983
description: The test runner is now stable.
-->
Configures the test runner to only execute top level tests that have the `only`
option set.
### `--test-reporter`
<!-- YAML
@ -1571,21 +1661,6 @@ changes:
The destination for the corresponding test reporter. See the documentation on
[test reporters][] for more details.
### `--test-only`
<!-- YAML
added:
- v18.0.0
- v16.17.0
changes:
- version: v20.0.0
pr-url: https://github.com/nodejs/node/pull/46983
description: The test runner is now stable.
-->
Configures the test runner to only execute top level tests that have the `only`
option set.
### `--test-shard`
<!-- YAML
@ -1935,6 +2010,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`
<!-- YAML
added: v0.1.3
-->
Print node's version.
### `--watch`
<!-- YAML
@ -2009,89 +2092,6 @@ added: v6.0.0
Automatically zero-fills all newly allocated [`Buffer`][] and [`SlowBuffer`][]
instances.
### `-c`, `--check`
<!-- YAML
added:
- v5.0.0
- v4.2.0
changes:
- version: v10.0.0
pr-url: https://github.com/nodejs/node/pull/19600
description: The `--require` option is now supported when checking a file.
-->
Syntax check the script without executing.
### `-e`, `--eval "script"`
<!-- YAML
added: v0.5.2
changes:
- version: v5.11.0
pr-url: https://github.com/nodejs/node/pull/5348
description: Built-in libraries are now available as predefined variables.
-->
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`
<!-- YAML
added: v0.1.3
-->
Print node command-line options.
The output of this option is less detailed than this document.
### `-i`, `--interactive`
<!-- YAML
added: v0.7.7
-->
Opens the REPL even if stdin does not appear to be a terminal.
### `-p`, `--print "script"`
<!-- YAML
added: v0.6.4
changes:
- version: v5.11.0
pr-url: https://github.com/nodejs/node/pull/5348
description: Built-in libraries are now available as predefined variables.
-->
Identical to `-e` but prints the result.
### `-r`, `--require module`
<!-- YAML
added: v1.6.0
-->
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`
<!-- YAML
added: v0.1.3
-->
Print node's version.
## Environment variables
### `FORCE_COLOR=[1, 2, 3]`
@ -2108,6 +2108,11 @@ and `NODE_DISABLE_COLORS` environment variables are ignored.
Any other value will result in colorized output being disabled.
### `NO_COLOR=<any>`
[`NO_COLOR`][] is an alias for `NODE_DISABLE_COLORS`. The value of the
environment variable is arbitrary.
### `NODE_DEBUG=module[,…]`
<!-- YAML
@ -2395,16 +2400,6 @@ appended to if it does. If an error occurs while attempting to write the
warning to the file, the warning will be written to stderr instead. This is
equivalent to using the `--redirect-warnings=file` command-line flag.
### `NODE_REPL_HISTORY=file`
<!-- YAML
added: v3.0.0
-->
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`
<!-- YAML
@ -2416,6 +2411,16 @@ added:
Path to a Node.js module which will be loaded in place of the built-in REPL.
Overriding this value to an empty string (`''`) will use the built-in REPL.
### `NODE_REPL_HISTORY=file`
<!-- YAML
added: v3.0.0
-->
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`
<!-- YAML
@ -2514,11 +2519,6 @@ and the line lengths of the source file (in the key `lineLengths`).
}
```
### `NO_COLOR=<any>`
[`NO_COLOR`][] is an alias for `NODE_DISABLE_COLORS`. The value of the
environment variable is arbitrary.
### `OPENSSL_CONF=file`
<!-- YAML