@@ -23,6 +23,10 @@ const { bench, suite } = require('node:bench');
 
 This module is only available under the `node:` scheme.
 
+## Example benchmark
+
+Save the following as `benchmark.mjs`:
+
 ```mjs
 import { bench, suite } from 'node:bench';
 
@@ -44,6 +48,12 @@ suite('URL', () => {
 });
 ```
 
+Run the benchmark from the command line:
+
+```console
+node --bench benchmark.mjs
+```
+
 Benchmarks are executed serially in declaration order. Declared benchmarks are
 scheduled automatically. Call `run()` during the same turn as the declarations
 to consume the event stream or configure filtering.
@@ -65,6 +75,31 @@ system load can all affect results. Keep raw samples when comparing results and
 investigate noisy or skewed distributions rather than treating a confidence
 interval as a pass/fail threshold.
 
+## Command-line runner
+
+The `--bench` flag runs one or more explicit benchmark files or glob patterns:
+
+```console
+node --bench benchmark.mjs
+node --bench --bench-reporter=json 'benchmarks/**/*.js'
+```
+
+Files are sorted and executed serially. The default
+`--bench-isolation=process` mode runs each file in a separate child process and
+emits one aggregate summary. Structured events are transferred to the parent
+without JSON conversion, preserving BigInt durations, errors, and parameter
+values. Child writes to stdout and stderr are emitted as diagnostic records so
+they do not corrupt reporter output.
+
+`--bench-isolation=none` imports all files into the runner process. This mode
+has lower startup overhead, but module, heap, and process state carry between
+files, and user writes share stdout and stderr with reporters.
+
+Benchmark files passed to `--bench` should declare benchmarks but must not call
+`run()`. The CLI supports `--bench-name-pattern`, `--bench-samples`,
+`--bench-warmup`, `--bench-reporter`, and `--bench-reporter-destination`. See
+the [command-line options documentation][] for details.
+
 ## Benchmark reporters
 
 The built-in reporters are available from the scheme-only
@@ -273,7 +308,11 @@ added: REPLACEME
   * `namePattern` {string|RegExp} Only runs benchmarks whose full hierarchical
     name matches the pattern. String values are interpreted as JavaScript
     regular expressions.
+  * `samples` {number} Overrides the number of measured callback invocations
+    for every benchmark. Must be a positive 32-bit unsigned integer.
   * `signal` {AbortSignal} Allows aborting in-progress benchmark execution.
+  * `warmup` {number} Overrides the number of unreported warmup callback
+    invocations for every benchmark. Must be a 32-bit unsigned integer.
 * Returns: {BenchmarksStream}
 
 Returns the object-mode event stream for the in-process benchmark run. Call
@@ -374,7 +413,9 @@ Every benchmark-scoped event contains `benchId` and `parentId`.
 additional `error` property and may contain samples recorded before the error.
 A skipped result has an additional `skip` property and an empty `samples`
 array. `'bench:diagnostic'` reports suite and hook errors. `'bench:summary'`
-contains overall `success`, `counts`, `duration_ns`, and `file` properties.
+contains overall `success`, `counts`, `duration_ns`, and `file` properties. The
+`file` is {string|null}; it is `null` when the summary aggregates multiple
+files.
 
 ## Sample result
 
@@ -412,3 +453,4 @@ A completed benchmark result contains:
   * `skewness` {number} The skewness of the scaled rate histogram.
 
 [benchmark result]: #benchmark-result
+[command-line options documentation]: cli.md#--bench
@@ -450,6 +450,109 @@ Error: Access to this API has been restricted
 }
 ```
 
+### `--bench`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Starts the Node.js command-line benchmark runner. At least one explicit file or
+glob pattern is required:
+
+```console
+node --bench benchmark.mjs
+node --bench 'benchmarks/**/*.js'
+```
+
+Quote glob patterns to prevent expansion by the shell. Matching files are
+sorted and executed serially. By default, each file runs in a separate child
+process. Benchmark files declare benchmarks using `node:bench`; they must not
+call `run()` themselves. See the [benchmark runner][] documentation for more
+details.
+
+This flag cannot be combined with `--test`, `--watch`, `--watch-path`,
+`--check`, `--eval`, or `--interactive`.
+
+### `--bench-isolation=mode`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Configures benchmark file isolation. When `mode` is `'process'`, each matching
+file runs in a separate child process. This is the default. Files are still run
+serially so their measured work does not overlap.
+
+When `mode` is `'none'`, all matching files and benchmarks run serially in the
+benchmark runner process. This reduces startup overhead but allows module,
+heap, and process state to carry between files. User writes to stdout or stderr
+also share destinations with benchmark reporters in this mode.
+
+### `--bench-name-pattern=pattern`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Only runs benchmarks whose full hierarchical name matches the JavaScript
+regular expression `pattern`. Non-matching benchmarks are reported as skipped.
+
+### `--bench-reporter-destination=destination`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Specifies the destination for the corresponding benchmark reporter. The value
+can be `stdout`, `stderr`, or a file path. A single reporter defaults to
+`stdout` when no destination is specified.
+
+### `--bench-reporter=reporter`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Specifies a benchmark reporter. The built-in reporters are `spec` and `json`.
+The `json` reporter emits newline-delimited JSON. A custom reporter can be
+specified using a module specifier resolved from the current working directory.
+
+This option can be repeated. When multiple reporters are specified, each must
+have a corresponding `--bench-reporter-destination`. The default reporter is
+`spec`.
+
+### `--bench-samples=count`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Overrides the number of measured callback invocations for every selected
+benchmark. `count` must be an integer between `1` and `4294967295`.
+
+### `--bench-warmup=count`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Overrides the number of unreported warmup callback invocations for every
+selected benchmark. `count` must be an integer between `0` and `4294967295`.
+
 ### `--build-sea=config`
 
 <!-- YAML
@@ -3900,6 +4003,12 @@ one is included in the list below.
 * `--allow-openssl-store`
 * `--allow-wasi`
 * `--allow-worker`
+* `--bench-isolation`
+* `--bench-name-pattern`
+* `--bench-reporter-destination`
+* `--bench-reporter`
+* `--bench-samples`
+* `--bench-warmup`
 * `--conditions`, `-C`
 * `--cpu-prof-dir`
 * `--cpu-prof-interval`
@@ -4608,6 +4717,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data
 [`v8.startupSnapshot` API]: v8.md#startup-snapshot-api
 [asynchronous module customization hooks]: module.md#asynchronous-customization-hooks
+[benchmark runner]: bench.md#command-line-runner
 [captured by the built-in snapshot of Node.js]: https://github.com/nodejs/node/blob/b19525a33cc84033af4addd0f80acd4dc33ce0cf/test/parallel/test-bootstrap-modules.js#L24
 [collecting code coverage from tests]: test.md#collecting-code-coverage
 [conditional exports]: packages.md#conditional-exports
 
@@ -281,6 +281,55 @@ Error: Access to this API has been restricted
 }
 .Ed
 .
+.It Fl -bench
+Starts the Node.js command-line benchmark runner. At least one explicit file or
+glob pattern is required:
+.Bd -literal
+node --bench benchmark.mjs
+node --bench 'benchmarks/**/*.js'
+.Ed
+Quote glob patterns to prevent expansion by the shell. Matching files are
+sorted and executed serially. By default, each file runs in a separate child
+process. Benchmark files declare benchmarks using \fBnode:bench\fR; they must not
+call \fBrun()\fR themselves. See the benchmark runner documentation for more
+details.
+This flag cannot be combined with \fB--test\fR, \fB--watch\fR, \fB--watch-path\fR,
+\fB--check\fR, \fB--eval\fR, or \fB--interactive\fR.
+.
+.It Fl -bench-isolation Ns = Ns Ar mode
+Configures benchmark file isolation. When \fBmode\fR is \fB'process'\fR, each matching
+file runs in a separate child process. This is the default. Files are still run
+serially so their measured work does not overlap.
+When \fBmode\fR is \fB'none'\fR, all matching files and benchmarks run serially in the
+benchmark runner process. This reduces startup overhead but allows module,
+heap, and process state to carry between files. User writes to stdout or stderr
+also share destinations with benchmark reporters in this mode.
+.
+.It Fl -bench-name-pattern Ns = Ns Ar pattern
+Only runs benchmarks whose full hierarchical name matches the JavaScript
+regular expression \fBpattern\fR. Non-matching benchmarks are reported as skipped.
+.
+.It Fl -bench-reporter-destination Ns = Ns Ar destination
+Specifies the destination for the corresponding benchmark reporter. The value
+can be \fBstdout\fR, \fBstderr\fR, or a file path. A single reporter defaults to
+\fBstdout\fR when no destination is specified.
+.
+.It Fl -bench-reporter Ns = Ns Ar reporter
+Specifies a benchmark reporter. The built-in reporters are \fBspec\fR and \fBjson\fR.
+The \fBjson\fR reporter emits newline-delimited JSON. A custom reporter can be
+specified using a module specifier resolved from the current working directory.
+This option can be repeated. When multiple reporters are specified, each must
+have a corresponding \fB--bench-reporter-destination\fR. The default reporter is
+\fBspec\fR.
+.
+.It Fl -bench-samples Ns = Ns Ar count
+Overrides the number of measured callback invocations for every selected
+benchmark. \fBcount\fR must be an integer between \fB1\fR and \fB4294967295\fR.
+.
+.It Fl -bench-warmup Ns = Ns Ar count
+Overrides the number of unreported warmup callback invocations for every
+selected benchmark. \fBcount\fR must be an integer between \fB0\fR and \fB4294967295\fR.
+.
 .It Fl -build-sea Ns = Ns Ar config
 Generates a single executable application from a JSON
 configuration file. The argument must be a path to the configuration file. If
@@ -1982,6 +2031,18 @@ one is included in the list below.
 .It
 \fB--allow-worker\fR
 .It
+\fB--bench-isolation\fR
+.It
+\fB--bench-name-pattern\fR
+.It
+\fB--bench-reporter-destination\fR
+.It
+\fB--bench-reporter\fR
+.It
+\fB--bench-samples\fR
+.It
+\fB--bench-warmup\fR
+.It
 \fB--conditions\fR, \fB-C\fR
 .It
 \fB--cpu-prof-dir\fR
 
@@ -15,7 +15,10 @@ const {
 } = require('internal/bench_runner/harness');
 const { run } = require('internal/bench_runner/runner');
 
-emitExperimentalWarning('Benchmarks');
+if (process.env.NODE_BENCH_CONTEXT !== 'child' ||
+    typeof process.send !== 'function') {
+  emitExperimentalWarning('Benchmarks');
+}
 
 module.exports = bench;
 ObjectAssign(module.exports, {
 
@@ -3,12 +3,12 @@
 const {
   ArrayPrototypePush,
   ArrayPrototypeShift,
-  NumberMAX_SAFE_INTEGER,
   Symbol,
 } = primordials;
 const Readable = require('internal/streams/readable');
 
 const kEmitMessage = Symbol('kEmitMessage');
+const kBenchmarksStreamDrain = Symbol('kBenchmarksStreamDrain');
 
 class BenchmarksStream extends Readable {
   #buffer = [];
@@ -18,45 +18,46 @@ class BenchmarksStream extends Readable {
     super({
       __proto__: null,
       objectMode: true,
-      highWaterMark: NumberMAX_SAFE_INTEGER,
     });
   }
 
   _read() {
+    const wasBlocked = !this.#canPush;
     this.#canPush = true;
     while (this.#buffer.length > 0) {
       const record = ArrayPrototypeShift(this.#buffer);
       if (!this.#tryPush(record)) return;
     }
+    if (wasBlocked) this.emit(kBenchmarksStreamDrain);
   }
 
   start(data) {
-    this[kEmitMessage]('bench:start', data);
+    return this[kEmitMessage]('bench:start', data);
   }
 
   sample(data) {
-    this[kEmitMessage]('bench:sample', data);
+    return this[kEmitMessage]('bench:sample', data);
   }
 
   complete(data) {
-    this[kEmitMessage]('bench:complete', data);
+    return this[kEmitMessage]('bench:complete', data);
   }
 
   diagnostic(data) {
-    this[kEmitMessage]('bench:diagnostic', data);
+    return this[kEmitMessage]('bench:diagnostic', data);
   }
 
   summary(data) {
-    this[kEmitMessage]('bench:summary', data);
+    return this[kEmitMessage]('bench:summary', data);
   }
 
   end() {
-    this.#tryPush(null);
+    return this.#tryPush(null);
   }
 
   [kEmitMessage](type, data) {
     this.emit(type, data);
-    this.#tryPush({ type, data });
+    return this.#tryPush({ type, data });
   }
 
   #tryPush(record) {
@@ -71,4 +72,5 @@ class BenchmarksStream extends Readable {
 
 module.exports = {
   BenchmarksStream,
+  kBenchmarksStreamDrain,
 };