doc: describe NODE_OPTIONS interop w/cmd line opts

Fixes #28910

PR-URL: #28928
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
Reviewed-By: Rich Trott <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>

Author: reasonablytall

doc/api/cli.md

@@ -950,16 +950,35 @@ When set to `1`, process warnings are silenced.
 added: v8.0.0
 -->
 
-A space-separated list of command line options. `options...` are interpreted as
-if they had been specified on the command line before the actual command line
-(so they can be overridden). Node.js will exit with an error if an option
-that is not allowed in the environment is used, such as `-p` or a script file.
+A space-separated list of command line options. `options...` are interpreted
+before command line options, so command line options will override or
+compound after anything in `options...`. Node.js will exit with an error if
+an option that is not allowed in the environment is used, such as `-p` or a
+script file.
 
-In case an option value happens to contain a space (for example a path listed in
-`--require`), it must be escaped using double quotes. For example:
+In case an option value happens to contain a space (for example a path listed
+in `--require`), it must be escaped using double quotes. For example:
 
 ```bash
---require "./my path/file.js"
+NODE_OPTIONS='--require "./my path/file.js"'
+```
+
+A singleton flag passed as a command line option will override the same flag
+passed into `NODE_OPTIONS`:
+
+```bash
+# The inspector will be available on port 5555
+NODE_OPTIONS='--inspect=localhost:4444' node --inspect=localhost:5555
+```
+
+A flag that can be passed multiple times will be treated as if its
+`NODE_OPTIONS` instances were passed first, and then its command line
+instances afterwards:
+
+```bash
+NODE_OPTIONS='--require "./a.js"' node --require "./b.js"
+# is equivalent to:
+node --require "./a.js" --require "./b.js"
 ```
 
 Node.js options that are allowed are: