Improve the documentation of the node/nodePath/nodeOptions opti…

…ons (#1011)

docs/api.md

@@ -637,12 +637,14 @@ _Default:_ `true` with [`execaNode()`](#execanodescriptpath-arguments-options),
 
 If `true`, runs with Node.js. The first argument must be a Node.js file.
 
+The subprocess inherits the current Node.js [CLI flags](https://nodejs.org/api/cli.html#options) and version. This can be overridden using the [`nodeOptions`](#optionsnodeoptions) and [`nodePath`](#optionsnodepath) options.
+
 [More info.](node.md)
 
 ### options.nodeOptions
 
 _Type:_ `string[]`\
-_Default:_ [`process.execArgv`](https://nodejs.org/api/process.html#process_process_execargv) (current Node.js CLI options)
+_Default:_ [`process.execArgv`](https://nodejs.org/api/process.html#process_process_execargv) (current Node.js CLI flags)
 
 List of [CLI flags](https://nodejs.org/api/cli.html#cli_options) passed to the [Node.js executable](#optionsnodepath).
 

docs/node.md

@@ -18,14 +18,20 @@ await execa({node: true})`file.js argument`;
 await execa`node file.js argument`;
 ```
 
-## Node.js [CLI flags](https://nodejs.org/api/cli.html#options)
+## Node.js CLI flags
+
+When using the [`node`](api.md#optionsnode) option or [`execaNode()`](api.md#execanodescriptpath-arguments-options), the current Node.js [CLI flags](https://nodejs.org/api/cli.html#options) are inherited. For example, the subprocess will use [`--allow-fs-read`](https://nodejs.org/api/cli.html#--allow-fs-read) if the current process does.
+
+The [`nodeOptions`](api.md#optionsnodeoptions) option can be used to set different CLI flags.
 
 ```js
-await execaNode({nodeOptions: ['--no-warnings']})`file.js argument`;
+await execaNode({nodeOptions: ['--allow-fs-write']})`file.js argument`;
 ```
 
 ## Node.js version
 
+The same applies to the Node.js version, which is inherited too.
+
 [`get-node`](https://github.com/ehmicky/get-node) and the [`nodePath`](api.md#optionsnodepath) option can be used to run a specific Node.js version. Alternatively, [`nvexeca`](https://github.com/ehmicky/nvexeca) or [`nve`](https://github.com/ehmicky/nve) can be used.
 
 ```js

types/arguments/options.d.ts

@@ -22,6 +22,8 @@ export type CommonOptions<IsSync extends boolean = boolean> = {
 	/**
 	If `true`, runs with Node.js. The first argument must be a Node.js file.
 
+	The subprocess inherits the current Node.js [CLI flags](https://nodejs.org/api/cli.html#options) and version. This can be overridden using the `nodeOptions` and `nodePath` options.
+
 	@default `true` with `execaNode()`, `false` otherwise
 	*/
 	readonly node?: boolean;
@@ -31,7 +33,7 @@ export type CommonOptions<IsSync extends boolean = boolean> = {
 
 	Requires the `node` option to be `true`.
 
-	@default [`process.execArgv`](https://nodejs.org/api/process.html#process_process_execargv) (current Node.js CLI options)
+	@default [`process.execArgv`](https://nodejs.org/api/process.html#process_process_execargv) (current Node.js CLI flags)
 	*/
 	readonly nodeOptions?: readonly string[];