From b62ed5a37e22b4414e28a5008ca201d700897d4c Mon Sep 17 00:00:00 2001
From: Joyee Cheung <joyeec9h3@gmail.com>
Date: Fri, 8 May 2026 01:11:57 +0200
Subject: [PATCH] debugger: add --help to `node inspect` and improve docs

- Add `--help` / `-h` to `node inspect` covering both interactive and
  non-interactive probe modes. The help text is printed when
  `--help`/`-h` appears before any positional argument to avoid
  hijacking `--help` passed to a child script.
- Improve the documentation of probe mode and add examples, explain
  same-location probe coalescing, TDZ caveat for let/const bindings,
  basename matching and exit code behavior. Also move it to a
  section parallel to interactive mode. Remove recommendation of
  evaluating structured expressions as that is prone to missing
  info in JSON mode.

Drive-by: When probe mode exits due to invalid arguments, exit with
`kInvalidCommandLineArgument` (9) instead of `kGenericUserError` (1).

Signed-off-by: Joyee Cheung <joyeec9h3@gmail.com>
---
 doc/api/debugger.md                           | 387 ++++++++++++------
 lib/internal/debugger/inspect.js              |  77 +++-
 lib/internal/debugger/inspect_helpers.js      |  74 +++-
 lib/internal/debugger/inspect_probe.js        |  64 +--
 .../test-debugger-inspect-help-forwarding.mjs |  34 ++
 test/parallel/test-debugger-inspect-help.js   |  37 ++
 .../test-debugger-probe-missing-expr.js       |   2 +-
 .../test-debugger-probe-requires-separator.js |   2 +-
 8 files changed, 460 insertions(+), 217 deletions(-)
 create mode 100644 test/parallel/test-debugger-inspect-help-forwarding.mjs
 create mode 100644 test/parallel/test-debugger-inspect-help.js

diff --git a/doc/api/debugger.md b/doc/api/debugger.md
index 691b025c1d9929..43f713ad824206 100644
--- a/doc/api/debugger.md
+++ b/doc/api/debugger.md
@@ -10,6 +10,14 @@ Node.js includes a command-line debugging utility. The Node.js debugger client
 is not a full-featured debugger, but simple stepping and inspection are
 possible.
 
+The debugger supports two modes of operation: [interactive mode][] and [non-interactive probe mode][].
+
+## Interactive mode
+
+```console
+$ node inspect [--port=<port>] [<node-option> ...] [<script> [<script-args>] | <host>:<port> | -p <pid>]
+```
+
 To use it, start Node.js with the `inspect` argument followed by the path to the
 script to debug.
 
@@ -90,6 +98,138 @@ steps to the next line. Type `help` to see what other commands are available.
 Pressing `enter` without typing a command will repeat the previous debugger
 command.
 
+### Watchers
+
+It is possible to watch expression and variable values while debugging. On
+every breakpoint, each expression from the watchers list will be evaluated
+in the current context and displayed immediately before the breakpoint's
+source code listing.
+
+To begin watching an expression, type `watch('my_expression')`. The command
+`watchers` will print the active watchers. To remove a watcher, type
+`unwatch('my_expression')`.
+
+## Command reference
+
+### Stepping
+
+* `cont`, `c`: Continue execution
+* `next`, `n`: Step next
+* `step`, `s`: Step in
+* `out`, `o`: Step out
+* `pause`: Pause running code (like pause button in Developer Tools)
+
+#### Breakpoints
+
+* `setBreakpoint()`, `sb()`: Set breakpoint on current line
+* `setBreakpoint(line)`, `sb(line)`: Set breakpoint on specific line
+* `setBreakpoint('fn()')`, `sb(...)`: Set breakpoint on a first statement in
+  function's body
+* `setBreakpoint('script.js', 1)`, `sb(...)`: Set breakpoint on first line of
+  `script.js`
+* `setBreakpoint('script.js', 1, 'num < 4')`, `sb(...)`: Set conditional
+  breakpoint on first line of `script.js` that only breaks when `num < 4`
+  evaluates to `true`
+* `clearBreakpoint('script.js', 1)`, `cb(...)`: Clear breakpoint in `script.js`
+  on line 1
+
+It is also possible to set a breakpoint in a file (module) that
+is not loaded yet:
+
+```console
+$ node inspect main.js
+< Debugger listening on ws://127.0.0.1:9229/48a5b28a-550c-471b-b5e1-d13dd7165df9
+< For help, see: https://nodejs.org/learn/getting-started/debugging
+<
+connecting to 127.0.0.1:9229 ... ok
+< Debugger attached.
+<
+Break on start in main.js:1
+> 1 const mod = require('./mod.js');
+  2 mod.hello();
+  3 mod.hello();
+debug> setBreakpoint('mod.js', 22)
+Warning: script 'mod.js' was not loaded yet.
+debug> c
+break in mod.js:22
+ 20 // USE OR OTHER DEALINGS IN THE SOFTWARE.
+ 21
+>22 exports.hello = function() {
+ 23   return 'hello from module';
+ 24 };
+debug>
+```
+
+It is also possible to set a conditional breakpoint that only breaks when a
+given expression evaluates to `true`:
+
+```console
+$ node inspect main.js
+< Debugger listening on ws://127.0.0.1:9229/ce24daa8-3816-44d4-b8ab-8273c8a66d35
+< For help, see: https://nodejs.org/learn/getting-started/debugging
+<
+connecting to 127.0.0.1:9229 ... ok
+< Debugger attached.
+Break on start in main.js:7
+  5 }
+  6
+> 7 addOne(10);
+  8 addOne(-1);
+  9
+debug> setBreakpoint('main.js', 4, 'num < 0')
+  1 'use strict';
+  2
+  3 function addOne(num) {
+> 4   return num + 1;
+  5 }
+  6
+  7 addOne(10);
+  8 addOne(-1);
+  9
+debug> cont
+break in main.js:4
+  2
+  3 function addOne(num) {
+> 4   return num + 1;
+  5 }
+  6
+debug> exec('num')
+-1
+debug>
+```
+
+#### Information
+
+* `backtrace`, `bt`: Print backtrace of current execution frame
+* `list(5)`: List scripts source code with 5 line context (5 lines before and
+  after)
+* `watch(expr)`: Add expression to watch list
+* `unwatch(expr)`: Remove expression from watch list
+* `unwatch(index)`: Remove expression at specific index from watch list
+* `watchers`: List all watchers and their values (automatically listed on each
+  breakpoint)
+* `repl`: Open debugger's repl for evaluation in debugging script's context
+* `exec expr`, `p expr`: Execute an expression in debugging script's context and
+  print its value
+* `profile`: Start CPU profiling session
+* `profileEnd`: Stop current CPU profiling session
+* `profiles`: List all completed CPU profiling sessions
+* `profiles[n].save(filepath = 'node.cpuprofile')`: Save CPU profiling session
+  to disk as JSON
+* `takeHeapSnapshot(filepath = 'node.heapsnapshot')`: Take a heap snapshot
+  and save to disk as JSON
+
+#### Execution control
+
+* `run`: Run script (automatically runs on debugger's start)
+* `restart`: Restart script
+* `kill`: Kill script
+
+#### Various
+
+* `scripts`: List all loaded scripts
+* `version`: Display V8's version
+
 ## Probe mode
 
 <!-- YAML
@@ -100,30 +240,39 @@ added:
 > Stability: 1 - Experimental
 
 `node inspect` supports a non-interactive probe mode for inspecting runtime values
-in an application via the flag `--probe`. Probe mode launches the application,
-sets one or more source breakpoints, evaluates one expression whenever a
-matching breakpoint is hit, and prints one final report when the session ends
-(either on normal completion or timeout). This allows developers to perform
+in an application via the flag `--probe`.
+
+Currently, probe mode only supports launching a new process from the entry point
+script specified on the command line.
+
+The probe mode sets one or more source breakpoints, evaluates specified
+expressions whenever the execution reaches a breakpoint, and prints one
+final report of all the evaluated expressions when the session ends
+(either on normal completion, error, or timeout). This allows developers to perform
 printf-style debugging without having to modify the application code and
-clean up afterwards, and it supports structured output for tool use.
+clean up afterwards. It also supports structured JSON output for tool use.
 
 ```console
-$ node inspect [--json] [--preview] [--timeout=<ms>] [--port=<port>] \
-    --probe app.js:10 --expr 'x' \
-    [--probe app.js:20 --expr 'y' ...] \
-    [--] [<node-option> ...] <script.js> [args...]
+$ node inspect --probe <file>:<line>[:<col>] --expr <expr>
+              [--probe <file>:<line>[:<col>] --expr <expr> ...]
+              [--json] [--preview] [--timeout=<ms>] [--port=<port>]
+              [--] [<node-option> ...] <script> [<script-args> ...]
 ```
 
-* `--probe <file>:<line>[:<col>]`: Source location to probe. Line and column number
-  are 1-based.
+* `--probe <file>:<line>[:<col>]`: Source location of the probe. When execution
+  reaches the location, the provided expressions are evaluated and printed in
+  the output. Line and column numbers are 1-based. When omitted, column defaults to 1.
+* `--expr <expr>`: JavaScript expression to evaluate whenever execution reaches
+  the location specified by the preceding `--probe`.
+  Must immediately follow the `--probe` it belongs to.
 * `--timeout=<ms>`: A global wall-clock deadline for the entire probe session.
   The default is `30000`. This can be used to probe a long-running application
   that can be terminated externally.
 * `--json`: If used, prints a structured JSON report instead of the default text report.
 * `--preview`: If used, non-primitive values will include CDP property previews for
   object-like JSON probe values.
-* `--port=<port>`: Selects the local inspector port used for the `--inspect-brk`
-  launch path. Probe mode defaults to `0`, which requests a random port.
+* `--port=<port>`: Selects the local inspector port where the probing session
+  will listen. Defaults to `0`, which requests a random port.
 * `--` is optional unless the child needs its own Node.js flags.
 
 Additional rules about the `--probe` and `--expr` arguments:
@@ -133,18 +282,21 @@ Additional rules about the `--probe` and `--expr` arguments:
 * `--timeout`, `--json`, `--preview`, and `--port` are global probe options
   for the whole probe session. They may appear before or between probe pairs,
   but not between a `--probe` and its matching `--expr`.
+* If additional Node.js execution arguments need to be passed to the child
+  script, `--` must be used to separate the probe options from the Node.js
+  options for the child script.
 
-If a single probe needs to evaluate more than one value,
-evaluate a structured value in `--expr`, for example `--expr "{ foo, bar }"`
-or `--expr "[foo, bar]"`, and use `--preview` to include property previews for
-any object-like values in the output.
+Example:
 
-Probe mode only prints the final probe report to stdout, and otherwise silences
-stdout/stderr from the child process. If the child exits with an error after the
-probe session starts, the final report records a terminal `error` event with the
-exit code and captured child stderr. Invalid arguments and fatal launch or
-connect failures may still print diagnostics to stderr without a final probe
-result.
+```console
+$ node inspect --probe app.js:10 --expr "user"
+               --probe src/utils.js:5:15 --expr "config.options"
+               --json --preview -- --no-warnings app.js --arg-for-app=foo
+```
+
+### Probe output format
+
+When the probe session ends, the probing process prints a final report of all the probe hits and results.
 
 Consider this script:
 
@@ -157,7 +309,7 @@ for (let i = 0; i < 2; i++) {
 }
 ```
 
-If `--json` is not used, the output is printed in a human-readable text format:
+Without `--json`, by default the output is printed in a human-readable text format:
 
 ```console
 $ node inspect --probe cli.js:5 --expr 'rss' cli.js
@@ -241,137 +393,102 @@ $ node inspect --json --probe cli.js:5 --expr 'rss' cli.js
 }
 ```
 
-## Watchers
+### Output and exit codes from the probed process
 
-It is possible to watch expression and variable values while debugging. On
-every breakpoint, each expression from the watchers list will be evaluated
-in the current context and displayed immediately before the breakpoint's
-source code listing.
+Probe mode only prints the final probe report to stdout, and otherwise silences
+stdout/stderr from the child process. When the probing session ends,
+`node inspect` typically exits with code `0` and prints a final report to
+stdout. If the child process exits with a non-zero code before the
+probe session ends, the final report records a terminal `error` event along
+with the exit code and captured child stderr. The probing process itself
+still exits with code `0` in this case.
 
-To begin watching an expression, type `watch('my_expression')`. The command
-`watchers` will print the active watchers. To remove a watcher, type
-`unwatch('my_expression')`.
+Invalid arguments and fatal launch or connect failures may cause the
+probing process to exit with a non-zero code and print an error message
+to stderr without a final probe report.
 
-## Command reference
+### Probing multiple expressions at the same execution point
 
-### Stepping
+When multiple `--probe`/`--expr` pairs share the same `--probe`, the
+expressions will be evaluated on the same pause in the order they appear
+on the command line.
 
-* `cont`, `c`: Continue execution
-* `next`, `n`: Step next
-* `step`, `s`: Step in
-* `out`, `o`: Step out
-* `pause`: Pause running code (like pause button in Developer Tools)
+```js
+// app.js
+const x = { x: 42 };       // line 2
+const y = { y: 35 };       // line 3
+const z = { ...x, ...y };  // line 4
+```
 
-### Breakpoints
+```console
+$ node inspect --probe app.js:4 --expr 'x' --probe app.js:4 --expr 'y' -- app.js
+```
 
-* `setBreakpoint()`, `sb()`: Set breakpoint on current line
-* `setBreakpoint(line)`, `sb(line)`: Set breakpoint on specific line
-* `setBreakpoint('fn()')`, `sb(...)`: Set breakpoint on a first statement in
-  function's body
-* `setBreakpoint('script.js', 1)`, `sb(...)`: Set breakpoint on first line of
-  `script.js`
-* `setBreakpoint('script.js', 1, 'num < 4')`, `sb(...)`: Set conditional
-  breakpoint on first line of `script.js` that only breaks when `num < 4`
-  evaluates to `true`
-* `clearBreakpoint('script.js', 1)`, `cb(...)`: Clear breakpoint in `script.js`
-  on line 1
+Prints
 
-It is also possible to set a breakpoint in a file (module) that
-is not loaded yet:
+```text
+Hit 1 at app.js:4
+  x = {x: 42}
+Hit 1 at app.js:4
+  y = {y: 35}
+Completed
+```
 
 ```console
-$ node inspect main.js
-< Debugger listening on ws://127.0.0.1:9229/48a5b28a-550c-471b-b5e1-d13dd7165df9
-< For help, see: https://nodejs.org/learn/getting-started/debugging
-<
-connecting to 127.0.0.1:9229 ... ok
-< Debugger attached.
-<
-Break on start in main.js:1
-> 1 const mod = require('./mod.js');
-  2 mod.hello();
-  3 mod.hello();
-debug> setBreakpoint('mod.js', 22)
-Warning: script 'mod.js' was not loaded yet.
-debug> c
-break in mod.js:22
- 20 // USE OR OTHER DEALINGS IN THE SOFTWARE.
- 21
->22 exports.hello = function() {
- 23   return 'hello from module';
- 24 };
-debug>
+$ node inspect --probe app.js:4 --expr 'x' --probe app.js:4 --expr 'y' --json --preview -- app.js
 ```
 
-It is also possible to set a conditional breakpoint that only breaks when a
-given expression evaluates to `true`:
+Prints
+
+```json
+{"v":1,"probes":[{"expr":"x","target":["app.js",4]},{"expr":"y","target":["app.js",4]}],"results":[{"probe":0,"event":"hit","hit":1,"result":{"type":"object","description":"Object","preview":{"type":"object","description":"Object","overflow":false,"properties":[{"name":"x","type":"number","value":"42"}]}}},{"probe":1,"event":"hit","hit":1,"result":{"type":"object","description":"Object","preview":{"type":"object","description":"Object","overflow":false,"properties":[{"name":"y","type":"number","value":"35"}]}}},{"event":"completed"}]}
+```
+
+### Selecting the probe location
+
+The expressions are evaluated in the lexical scope of the probe location when
+execution reaches it. Avoid probing a variable declared by `let` or `const` at its
+declaration site, as this leads to a `ReferenceError` caused by
+accessing the variable in its temporal dead zone (TDZ).
+
+```js
+// app.js
+const x = 42;        // line 2
+console.log(x);      // line 3
+```
 
 ```console
-$ node inspect main.js
-< Debugger listening on ws://127.0.0.1:9229/ce24daa8-3816-44d4-b8ab-8273c8a66d35
-< For help, see: https://nodejs.org/learn/getting-started/debugging
-<
-connecting to 127.0.0.1:9229 ... ok
-< Debugger attached.
-Break on start in main.js:7
-  5 }
-  6
-> 7 addOne(10);
-  8 addOne(-1);
-  9
-debug> setBreakpoint('main.js', 4, 'num < 0')
-  1 'use strict';
-  2
-  3 function addOne(num) {
-> 4   return num + 1;
-  5 }
-  6
-  7 addOne(10);
-  8 addOne(-1);
-  9
-debug> cont
-break in main.js:4
-  2
-  3 function addOne(num) {
-> 4   return num + 1;
-  5 }
-  6
-debug> exec('num')
--1
-debug>
+$ node inspect --probe app.js:1 --expr 'x' app.js
+Hit 1 at app.js:1
+  [error] x = ReferenceError: Cannot access 'x' from debugger
+  ...
+Completed
 ```
 
-### Information
+Instead, probe at a location where the variable is already initialized:
 
-* `backtrace`, `bt`: Print backtrace of current execution frame
-* `list(5)`: List scripts source code with 5 line context (5 lines before and
-  after)
-* `watch(expr)`: Add expression to watch list
-* `unwatch(expr)`: Remove expression from watch list
-* `unwatch(index)`: Remove expression at specific index from watch list
-* `watchers`: List all watchers and their values (automatically listed on each
-  breakpoint)
-* `repl`: Open debugger's repl for evaluation in debugging script's context
-* `exec expr`, `p expr`: Execute an expression in debugging script's context and
-  print its value
-* `profile`: Start CPU profiling session
-* `profileEnd`: Stop current CPU profiling session
-* `profiles`: List all completed CPU profiling sessions
-* `profiles[n].save(filepath = 'node.cpuprofile')`: Save CPU profiling session
-  to disk as JSON
-* `takeHeapSnapshot(filepath = 'node.heapsnapshot')`: Take a heap snapshot
-  and save to disk as JSON
+```console
+$ node inspect --probe app.js:3 --expr 'x' app.js
+Hit 1 at app.js:3
+  x = 42
+Completed
+```
 
-### Execution control
+Probe paths are matched against loaded script URLs by basename, similar to how
+native debuggers typically match breakpoints. Given:
 
-* `run`: Run script (automatically runs on debugger's start)
-* `restart`: Restart script
-* `kill`: Kill script
+```text
+project/
+  - src/utils.js
+  - lib/utils.js
+```
 
-### Various
+`--probe utils.js:10` binds to _both_ files and produces one hit per match.
+To disambiguate, specify a fuller path that only matches the intended file:
 
-* `scripts`: List all loaded scripts
-* `version`: Display V8's version
+```console
+$ node inspect --probe src/utils.js:10 --expr 'x' main.js   # matches only src/utils.js
+```
 
 ## Advanced usage
 
@@ -413,3 +530,5 @@ debugging sessions.)
 
 [Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/
 [`debugger`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger
+[interactive mode]: #interactive-mode
+[non-interactive probe mode]: #probe-mode
diff --git a/lib/internal/debugger/inspect.js b/lib/internal/debugger/inspect.js
index bb54e0ef570448..41157dab97baa2 100644
--- a/lib/internal/debugger/inspect.js
+++ b/lib/internal/debugger/inspect.js
@@ -27,10 +27,11 @@ const {
 const InspectClient = require('internal/debugger/inspect_client');
 const {
   launchChildProcess,
-  writeUsageAndExit,
+  writeInspectUsageAndExit,
 } = require('internal/debugger/inspect_helpers');
 const {
-  startProbeMode,
+  parseProbeTokens,
+  runProbeMode,
 } = require('internal/debugger/inspect_probe');
 const createRepl = require('internal/debugger/inspect_repl');
 
@@ -39,6 +40,7 @@ const debuglog = util.debuglog('inspect');
 const {
   exitCodes: {
     kGenericUserError,
+    kInvalidCommandLineArgument,
     kNoFailure,
   },
 } = internalBinding('errors');
@@ -220,7 +222,7 @@ class NodeInspector {
   }
 }
 
-function parseArgv(args) {
+function parseInteractiveArgs(args) {
   const target = ArrayPrototypeShift(args);
   let host = '127.0.0.1';
   let port = 9229;
@@ -264,20 +266,83 @@ function parseArgv(args) {
   };
 }
 
+const kInspectArgOptions = {
+  __proto__: null,
+  expr: { type: 'string' },
+  help: { type: 'boolean', short: 'h' },
+  json: { type: 'boolean' },
+  // Port and timeout use type 'string' because parseArgs has no
+  // numeric type; the values are parsed to integers by parseProbeTokens().
+  port: { type: 'string' },
+  preview: { type: 'boolean' },
+  probe: { type: 'string' },
+  timeout: { type: 'string' },
+};
+
+// Parses args once and decides whether the user wants the inspect help, probe
+// mode, or interactive mode. The mode is determined by the first option,
+// option-terminator, or positional token in the input.
+//
+// Returns one of:
+//   { mode: 'help' }
+//   { mode: 'probe', tokens, args }
+//   { mode: 'interactive' }
+function parseInspectMode(args) {
+  const { tokens } = util.parseArgs({
+    args,
+    allowPositionals: true,
+    options: kInspectArgOptions,
+    strict: false,
+    tokens: true,
+  });
+
+  for (const token of tokens) {
+    if (token.kind === 'option') {
+      if (token.name === 'help') return { mode: 'help' };
+      if (token.name === 'probe') {
+        // `--probe --help` / `--probe -h` (no value) consumes the help flag
+        // as the probe's "value"; surface help instead of a probe error.
+        if (!token.inlineValue &&
+            (token.value === '--help' || token.value === '-h')) {
+          return { mode: 'help' };
+        }
+        return { mode: 'probe', tokens, args };
+      }
+    }
+    if (token.kind === 'option-terminator' || token.kind === 'positional') {
+      break;
+    }
+  }
+  return { mode: 'interactive' };
+}
+
 function startInspect(argv = ArrayPrototypeSlice(process.argv, 2),
                       stdin = process.stdin,
                       stdout = process.stdout) {
   const invokedAs = `${process.argv0} ${process.argv[1]}`;
 
   if (argv.length < 1) {
-    writeUsageAndExit(invokedAs);
+    writeInspectUsageAndExit(invokedAs, undefined, kInvalidCommandLineArgument);
   }
 
-  if (startProbeMode(invokedAs, argv, stdout)) {
+  const parsed = parseInspectMode(argv);
+
+  if (parsed.mode === 'help') {
+    writeInspectUsageAndExit(invokedAs);
+  }
+
+  if (parsed.mode === 'probe') {
+    let probeOptions;
+    try {
+      probeOptions = parseProbeTokens(parsed.tokens, parsed.args);
+    } catch (error) {
+      writeInspectUsageAndExit(invokedAs, error.message, kInvalidCommandLineArgument);
+    }
+    runProbeMode(stdout, probeOptions);
     return;
   }
 
-  const options = parseArgv(argv);
+  const options = parseInteractiveArgs(argv);
   const inspector = new NodeInspector(options, stdin, stdout);
 
   stdin.resume();
diff --git a/lib/internal/debugger/inspect_helpers.js b/lib/internal/debugger/inspect_helpers.js
index 61c07f4150441f..0511f06f5176a5 100644
--- a/lib/internal/debugger/inspect_helpers.js
+++ b/lib/internal/debugger/inspect_helpers.js
@@ -61,21 +61,67 @@ function ensureTrailingNewline(text) {
   return StringPrototypeEndsWith(text, '\n') ? text : `${text}\n`;
 }
 
-function writeUsageAndExit(invokedAs, message, exitCode = kInvalidCommandLineArgument) {
+function writeInspectUsageAndExit(invokedAs, message, exitCode) {
+  const code = exitCode ?? (message ? kInvalidCommandLineArgument : 0);
+  const out = code === 0 ? process.stdout : process.stderr;
   if (message) {
-    process.stderr.write(`${message}\n`);
+    out.write(`${message}\n`);
   }
-  const text =
-    `Usage: ${invokedAs} script.js\n` +
-    `       ${invokedAs} <host>:<port>\n` +
-    `       ${invokedAs} --port=<port> Use 0 for random port assignment\n` +
-    `       ${invokedAs} -p <pid>\n` +
-    `       ${invokedAs} [--json] [--timeout=<ms>] [--port=<port>] ` +
-    `--probe <file>:<line>[:<col>] --expr <expr> ` +
-    `[--probe <file>:<line>[:<col>] --expr <expr> ...] ` +
-    `[--] [<node-option> ...] <script.js> [args...]\n`;
-  process.stderr.write(text);
-  process.exit(exitCode);
+  out.write(`Usage: ${invokedAs} [--port=<port>] [<node-option> ...]
+                      [<script> [<script-args>] | <host>:<port> | -p <pid>]
+       ${invokedAs} --probe <file>:<line>[:<col>] --expr <expr>
+                      [--probe <file>:<line>[:<col>] --expr <expr> ...]
+                      [--json] [--preview] [--timeout=<ms>] [--port=<port>]
+                      [--] [<node-option> ...] <script> [<script-args> ...]
+
+Interactive mode: Starts a live debugging session.
+
+Example:
+  $ node inspect script.js
+
+Options:
+  --port=<port>         Inspector port for the debuggee (default: 9229)
+  <script>              The script to launch and debug.
+  <host>:<port>         Remote debugger to connect to.
+  -p <pid>              Attach to a running Node.js process by PID
+
+Semantics:
+* If neither a script nor a host:port nor -p is provided, node inspect starts
+  the REPL.
+
+Non-interactive probe mode: Evaluates expressions whenever execution reaches
+specified source locations and prints all the evaluation results to stdout.
+
+Example:
+  $ node inspect --probe app.js:10 --expr "user"
+                 --probe src/utils.js:5:15 --expr "config.options"
+                 --json --preview -- --no-warnings app.js --arg-for-app=foo
+
+Options:
+  --probe <file>:<line>[:<col>]
+                    Source location of the probe (1-based, col defaults
+                    to 1). Matches by file basename, use a fuller path to
+                    disambiguate. Must be immediately followed by --expr.
+  --expr <expr>     Expression to evaluate in the lexical scope of the
+                    preceding --probe each time execution reaches it.
+                    Avoid probing let/const-bound variables at their
+                    declaration site or a ReferenceError may be thrown.
+  --json            Output JSON if specified, otherwise human-readable text.
+  --preview         Include V8 object previews in JSON output.
+  --timeout <ms>    Global session timeout (default: 30000).
+  --port <port>     Inspector port for the debuggee (default: 0 = random).
+
+Semantics:
+* Multiple --probe/--expr pairs are allowed. Same-location --probes share
+  a pause and scope, their --exprs are evaluated in command-line order.
+* Use -- before any Node.js flags intended for the child process.
+* Target errors are surfaced in the report as a terminal 'error' event.
+  The probing process exits 0 unless it encounters an error itself.
+
+See https://nodejs.org/api/debugger.html for details, including the
+probe output schema.
+`);
+  process.exit(code);
 }
 
 async function launchChildProcess(childArgs, inspectHost, inspectPort,
@@ -128,5 +174,5 @@ async function launchChildProcess(childArgs, inspectHost, inspectPort,
 module.exports = {
   ensureTrailingNewline,
   launchChildProcess,
-  writeUsageAndExit,
+  writeInspectUsageAndExit,
 };
diff --git a/lib/internal/debugger/inspect_probe.js b/lib/internal/debugger/inspect_probe.js
index ccee22e1691fa5..c872202f1876f7 100644
--- a/lib/internal/debugger/inspect_probe.js
+++ b/lib/internal/debugger/inspect_probe.js
@@ -23,14 +23,12 @@ const {
 } = primordials;
 
 const { clearTimeout, setTimeout } = require('timers');
-const util = require('util');
 const { SideEffectFreeRegExpPrototypeSymbolReplace } = require('internal/util');
 
 const InspectClient = require('internal/debugger/inspect_client');
 const {
   ensureTrailingNewline,
   launchChildProcess,
-  writeUsageAndExit,
 } = require('internal/debugger/inspect_helpers');
 
 const { ERR_DEBUGGER_STARTUP_ERROR } = require('internal/errors').codes;
@@ -46,17 +44,6 @@ const kProbeVersion = 1;
 const kProbeDisconnectSentinel = 'Waiting for the debugger to disconnect...';
 const kDigitsRegex = /^\d+$/;
 const kInspectPortRegex = /^--inspect-port=(\d+)$/;
-const kProbeArgOptions = {
-  __proto__: null,
-  expr: { type: 'string' },
-  json: { type: 'boolean' },
-  // Port and timeout use type 'string' because parseArgs has no
-  // numeric type; the values are parsed to integers in parseProbeArgv().
-  port: { type: 'string' },
-  preview: { type: 'boolean' },
-  probe: { type: 'string' },
-  timeout: { type: 'string' },
-};
 
 function parseUnsignedInteger(value, name, allowZero = false) {
   if (typeof value !== 'string' || RegExpPrototypeExec(kDigitsRegex, value) === null) {
@@ -274,29 +261,7 @@ function buildProbeTextReport(report) {
   return ensureTrailingNewline(ArrayPrototypeJoin(lines, '\n'));
 }
 
-function hasTopLevelProbeOption(args) {
-  const { tokens } = util.parseArgs({
-    args,
-    allowPositionals: true,
-    options: kProbeArgOptions,
-    strict: false,
-    tokens: true,
-  });
-
-  for (const token of tokens) {
-    if (token.kind === 'option' && token.name === 'probe') {
-      return true;
-    }
-
-    if (token.kind === 'option-terminator' || token.kind === 'positional') {
-      return false;
-    }
-  }
-
-  return false;
-}
-
-function parseProbeArgv(args) {
+function parseProbeTokens(tokens, args) {
   let port = 0;
   let preview = false;
   let timeout = kProbeDefaultTimeout;
@@ -307,14 +272,6 @@ function parseProbeArgv(args) {
   let expectedExprIndex = -1;
   const probes = [];
 
-  const { tokens } = util.parseArgs({
-    args,
-    allowPositionals: true,
-    options: kProbeArgOptions,
-    strict: false,
-    tokens: true,
-  });
-
   for (const token of tokens) {
     if (token.kind === 'option-terminator') {
       sawSeparator = true;
@@ -764,22 +721,7 @@ async function runProbeMode(stdout, probeOptions) {
   }
 }
 
-function startProbeMode(invokedAs, args, stdout) {
-  if (!hasTopLevelProbeOption(args)) {
-    return false;
-  }
-
-  let probeOptions;
-  try {
-    probeOptions = parseProbeArgv(args);
-  } catch (error) {
-    writeUsageAndExit(invokedAs, error.message, kGenericUserError);
-  }
-
-  runProbeMode(stdout, probeOptions);
-  return true;
-}
-
 module.exports = {
-  startProbeMode,
+  parseProbeTokens,
+  runProbeMode,
 };
diff --git a/test/parallel/test-debugger-inspect-help-forwarding.mjs b/test/parallel/test-debugger-inspect-help-forwarding.mjs
new file mode 100644
index 00000000000000..796fcf36cc7bee
--- /dev/null
+++ b/test/parallel/test-debugger-inspect-help-forwarding.mjs
@@ -0,0 +1,34 @@
+// Tests that --help / -h are forwarded to the debuggee when a script is
+// also passed, instead of being hijacked as the inspect help flag.
+
+import { skipIfInspectorDisabled } from '../common/index.mjs';
+
+skipIfInspectorDisabled();
+
+import * as fixtures from '../common/fixtures.mjs';
+import startCLI from '../common/debugger.js';
+
+import assert from 'assert';
+
+async function getEvaluatedArgv(flag) {
+  const script = fixtures.path('debugger', 'empty.js');
+  const cli = startCLI([script, flag]);
+  try {
+    await cli.waitForInitialBreak();
+    await cli.waitForPrompt();
+    await cli.command('exec process.argv');
+    return cli.output;
+  } finally {
+    await cli.quit();
+  }
+}
+
+async function checkForwardedHelp(flag) {
+  const output = await getEvaluatedArgv(flag);
+  assert(output.includes(`'${flag}'`),
+         `expected debuggee process.argv to include "${flag}", got:\n${output}`);
+  assert.doesNotMatch(output, /Usage: .+ inspect/);
+}
+
+await checkForwardedHelp('--help');
+await checkForwardedHelp('-h');
diff --git a/test/parallel/test-debugger-inspect-help.js b/test/parallel/test-debugger-inspect-help.js
new file mode 100644
index 00000000000000..3dfc1f79af7166
--- /dev/null
+++ b/test/parallel/test-debugger-inspect-help.js
@@ -0,0 +1,37 @@
+'use strict';
+
+// Tests that `node inspect` help text is printed when
+// `--help` / `-h` is passed and there is no script,
+// or when there are no additional arguments.
+const common = require('../common');
+common.skipIfInspectorDisabled();
+
+const {
+  spawnSyncAndAssert,
+  spawnSyncAndExit,
+} = require('../common/child_process');
+
+const usageRegex = /^Usage: .+ inspect .*debugger\.html/ms;
+
+// --help / -h prints the usage to stdout and exits with code 0,
+// for both interactive and probe-mode invocations.
+const helpArgs = [
+  ['inspect', '--help'],
+  ['inspect', '-h'],
+  ['inspect', '--probe', '--help'],
+  ['inspect', '--probe', '-h'],
+];
+
+for (const args of helpArgs) {
+  spawnSyncAndAssert(process.execPath, args, {
+    stdout: usageRegex,
+  });
+}
+
+// `node inspect` with no args prints the usage to stderr and exits
+// with kInvalidCommandLineArgument (9).
+spawnSyncAndExit(process.execPath, ['inspect'], {
+  status: 9,
+  signal: null,
+  stderr: usageRegex,
+});
diff --git a/test/parallel/test-debugger-probe-missing-expr.js b/test/parallel/test-debugger-probe-missing-expr.js
index e6d4f13ac6f26d..57adb70b1b7f35 100644
--- a/test/parallel/test-debugger-probe-missing-expr.js
+++ b/test/parallel/test-debugger-probe-missing-expr.js
@@ -13,7 +13,7 @@ spawnSyncAndExit(process.execPath, [
   probeScript,
 ], {
   signal: null,
-  status: 1,
+  status: 9,
   stderr: /Each --probe must be followed immediately by --expr/,
   trim: true,
 });
diff --git a/test/parallel/test-debugger-probe-requires-separator.js b/test/parallel/test-debugger-probe-requires-separator.js
index 8aae48052c1a29..bbbefb0069805f 100644
--- a/test/parallel/test-debugger-probe-requires-separator.js
+++ b/test/parallel/test-debugger-probe-requires-separator.js
@@ -15,7 +15,7 @@ spawnSyncAndExit(process.execPath, [
   probeScript,
 ], {
   signal: null,
-  status: 1,
+  status: 9,
   stderr: /Use -- before child Node\.js flags in probe mode/,
   trim: true,
 });