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

juanibe · bnb · aduh95 · commit 2f36f8e8631c · 2025-06-10T14:52:19.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
@@ -3057,6 +3057,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
 ```
@@ -3082,6 +3086,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
 ```
