doc,test: specify and test CLI option precedence rules

Refs: #35098 (comment)

PR-URL: #35106
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Richard Lau <[email protected]>
Reviewed-By: Gerhard Stöbich <[email protected]>
Reviewed-By: Myles Borins <[email protected]>
Reviewed-By: Zeyu Yang <[email protected]>
Reviewed-By: Gireesh Punathil <[email protected]>

Author: addaleax

doc/api/cli.md

@@ -34,6 +34,11 @@ dashes (`-`) or underscores (`_`).
 
 For example, `--pending-deprecation` is equivalent to `--pending_deprecation`.
 
+If an option that takes a single value, for example `--max-http-header-size`,
+is passed more than once, then the last passed value will be used. Options
+from the command line take precedence over options passed through the
+[`NODE_OPTIONS`][] environment variable.
+
 ### `-`
 <!-- YAML
 added: v8.0.0
@@ -1487,6 +1492,7 @@ $ node --max-old-space-size=1536 index.js
 [`--openssl-config`]: #cli_openssl_config_file
 [`Buffer`]: buffer.html#buffer_class_buffer
 [`SlowBuffer`]: buffer.html#buffer_class_slowbuffer
+[`NODE_OPTIONS`]: #cli_node_options_options
 [`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn
 [`tls.DEFAULT_MAX_VERSION`]: tls.html#tls_tls_default_max_version
 [`tls.DEFAULT_MIN_VERSION`]: tls.html#tls_tls_default_min_version

test/parallel/test-cli-options-precedence.js

@@ -0,0 +1,22 @@
+'use strict';
+require('../common');
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+
+// The last option on the command line takes precedence:
+assert.strictEqual(spawnSync(process.execPath, [
+  '--max-http-header-size=1234',
+  '--max-http-header-size=5678',
+  '-p', 'http.maxHeaderSize'
+], {
+  encoding: 'utf8'
+}).stdout.trim(), '5678');
+
+// The command line takes precedence over NODE_OPTIONS:
+assert.strictEqual(spawnSync(process.execPath, [
+  '--max-http-header-size=5678',
+  '-p', 'http.maxHeaderSize'
+], {
+  encoding: 'utf8',
+  env: { ...process.env, NODE_OPTIONS: '--max-http-header-size=1234' }
+}).stdout.trim(), '5678');