doc: clarify behavior of --watch-path and --watch flags

juanibe · bnb · targos · commit 62056d40c709 · 2025-05-31T13:25:45.000+02:00
Fixes: #58113 PR-URL: #58136 Reviewed-By: Juan José Arboleda <soyjuanarbol@gmail.com> Reviewed-By: Tierney Cyren <hello@bnb.im> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Co-authored-by: Tierney Cyren <accounts@bnb.im>
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -3076,6 +3076,10 @@ Use `--watch-path` to specify what paths to watch.
 This flag cannot be combined with
 `--check`, `--eval`, `--interactive`, or the REPL.
 
+Note: The `--watch` flag requires a file path as an argument and is incompatible
+with `--run` or inline script input, as `--run` takes precedence and ignores watch
+mode. If no file is provided, Node.js will exit with status code `9`.
+
 ```bash
 node --watch index.js
 ```
@@ -3103,6 +3107,9 @@ combination with `--watch`.
 This flag cannot be combined with
 `--check`, `--eval`, `--interactive`, `--test`, or the REPL.
 
+Note: Using `--watch-path` implicitly enables `--watch`, which requires a file path
+and is incompatible with `--run`, as `--run` takes precedence and ignores watch mode.
+
 ```bash
 node --watch-path=./src --watch-path=./tests index.js
 ```
