From 8f4567db312db3f36ed37b4fedde20ec2d0bc056 Mon Sep 17 00:00:00 2001
From: James Ross <james@jross.me>
Date: Sun, 19 Jul 2026 22:06:09 +0100
Subject: [PATCH] src: list scripts when `--run` has no command

Signed-off-by: James Ross <james@jross.me>
---
 doc/api/cli.md                 | 11 ++++++++
 doc/node.1                     |  6 +++++
 src/node.cc                    |  3 ++-
 src/node_options-inl.h         | 18 ++++++++++---
 src/node_options.h             |  3 +++
 src/node_task_runner.cc        | 48 ++++++++++++++++++++++------------
 test/message/node_run_list.js  | 14 ++++++++++
 test/message/node_run_list.out | 14 ++++++++++
 test/parallel/test-node-run.js | 35 +++++++++++++++++++++++++
 9 files changed, 130 insertions(+), 22 deletions(-)
 create mode 100644 test/message/node_run_list.js
 create mode 100644 test/message/node_run_list.out

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 76f2aecf75b6..acc7374476f6 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -2657,6 +2657,9 @@ forked processes, or clustered processes.
 <!-- YAML
 added: v22.0.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/64606
+    description: Passing `--run` without a command lists the available scripts.
   - version: v22.3.0
     pr-url: https://github.com/nodejs/node/pull/53032
     description: NODE_RUN_SCRIPT_NAME environment variable is added.
@@ -2673,6 +2676,14 @@ changes:
 This runs a specified command from a package.json's `"scripts"` object.
 If a missing `"command"` is provided, it will list the available scripts.
 
+Passing `--run` without a command lists the available scripts and exits:
+
+```console
+$ node --run
+Available scripts are:
+  test: node --test
+```
+
 `--run` will traverse up to the root directory and finds a `package.json`
 file to run the command from.
 
diff --git a/doc/node.1 b/doc/node.1
index 498e10137abf..8dddfd7cf146 100644
--- a/doc/node.1
+++ b/doc/node.1
@@ -1318,6 +1318,12 @@ forked processes, or clustered processes.
 .It Fl -run
 This runs a specified command from a package.json's \fB"scripts"\fR object.
 If a missing \fB"command"\fR is provided, it will list the available scripts.
+Passing \fB--run\fR without a command lists the available scripts and exits:
+.Bd -literal
+$ node --run
+Available scripts are:
+  test: node --test
+.Ed
 \fB--run\fR will traverse up to the root directory and finds a \fBpackage.json\fR
 file to run the command from.
 \fB--run\fR prepends \fB./node_modules/.bin\fR for each ancestor of
diff --git a/src/node.cc b/src/node.cc
index b368c5873434..15e7e62f9beb 100644
--- a/src/node.cc
+++ b/src/node.cc
@@ -1133,7 +1133,8 @@ InitializeOncePerProcessInternal(const std::vector<std::string>& args,
     }
   }
 
-  if (!per_process::cli_options->run.empty()) {
+  // A bare `--run` (empty value) lists the available scripts; a value runs it.
+  if (per_process::cli_options->has_run) {
     auto positional_args = task_runner::GetPositionalArgs(args);
     result->early_return_ = true;
     task_runner::RunTask(
diff --git a/src/node_options-inl.h b/src/node_options-inl.h
index 877e8ce4ded9..0f93455e93f3 100644
--- a/src/node_options-inl.h
+++ b/src/node_options-inl.h
@@ -6,6 +6,7 @@
 #include <algorithm>
 #include <cstdlib>
 #include <ranges>
+#include <type_traits>
 #include "node_options.h"
 #include "util.h"
 
@@ -453,18 +454,21 @@ void OptionsParser<Options>::Parse(
 
     std::string value;
     if (info.type != kBoolean && info.type != kNoOp && info.type != kV8Option) {
+      // `--run` may be passed without a script name to list available scripts,
+      // so an omitted value is not an error and must not swallow a later flag.
+      const bool optional_value = name == "--run";
       if (equals_index != std::string::npos) {
         value = arg.substr(equals_index + 1);
-        if (value.empty()) {
+        if (value.empty() && !optional_value) {
           missing_argument();
           break;
         }
-      } else {
-        if (args.empty()) {
+      } else if (args.empty() || (optional_value && args.first()[0] == '-')) {
+        if (!optional_value) {
           missing_argument();
           break;
         }
-
+      } else {
         value = args.pop_first();
 
         if (!value.empty() && value[0] == '-') {
@@ -512,6 +516,12 @@ void OptionsParser<Options>::Parse(
       default:
         UNREACHABLE();
     }
+
+    // Record that `--run` was seen so an empty value can be distinguished from
+    // the option being absent. Guarded so it only compiles for the owning type.
+    if constexpr (std::is_same_v<Options, PerProcessOptions>) {
+      if (name == "--run") options->has_run = true;
+    }
   }
   options->CheckOptions(errors, orig_args);
 }
diff --git a/src/node_options.h b/src/node_options.h
index 7d9ff9e5147d..4bdbf8ae58a3 100644
--- a/src/node_options.h
+++ b/src/node_options.h
@@ -355,6 +355,9 @@ class PerProcessOptions : public Options {
   bool print_version = false;
   std::string experimental_sea_config;
   std::string run;
+  // Tracks whether `--run` was passed, since an empty `run` is ambiguous
+  // between "not passed" and "passed without a script name" (lists scripts).
+  bool has_run = false;
 
   std::string build_sea;
 #ifdef NODE_HAVE_I18N_SUPPORT
diff --git a/src/node_task_runner.cc b/src/node_task_runner.cc
index 22c02e83e12e..ef06053754be 100644
--- a/src/node_task_runner.cc
+++ b/src/node_task_runner.cc
@@ -249,6 +249,27 @@ FindPackageJson(const std::filesystem::path& cwd) {
   return {{package_json_path, raw_content, path_env_var}};
 }
 
+// Prints every "name: command" pair in the scripts object to the given stream.
+static void PrintScripts(FILE* out,
+                         simdjson::ondemand::object& scripts_object) {
+  // Reset the object to iterate from the beginning, in case it was read before.
+  scripts_object.reset();
+  simdjson::ondemand::value value;
+  for (auto field : scripts_object) {
+    std::string_view key_str;
+    std::string_view value_str;
+    if (!field.unescaped_key().get(key_str) && !field.value().get(value) &&
+        !value.get_string().get(value_str)) {
+      fprintf(out,
+              "  %.*s: %.*s\n",
+              static_cast<int>(key_str.size()),
+              key_str.data(),
+              static_cast<int>(value_str.size()),
+              value_str.data());
+    }
+  }
+}
+
 void RunTask(const std::shared_ptr<InitializationResultImpl>& result,
              std::string_view command_id,
              const std::vector<std::string_view>& positional_args) {
@@ -300,6 +321,15 @@ void RunTask(const std::shared_ptr<InitializationResultImpl>& result,
     return;
   }
 
+  // With no command (e.g. bare `node --run`), list the available scripts to
+  // stdout and exit successfully, mirroring `npm run`.
+  if (command_id.empty()) {
+    fprintf(stdout, "Available scripts are:\n");
+    PrintScripts(stdout, scripts_object);
+    result->exit_code_ = ExitCode::kNoFailure;
+    return;
+  }
+
   // If the command_id is not found in the scripts object, throw an error.
   std::string_view command;
   if (auto command_error =
@@ -317,23 +347,7 @@ void RunTask(const std::shared_ptr<InitializationResultImpl>& result,
               command_id.data(),
               path.string().c_str());
       fprintf(stderr, "Available scripts are:\n");
-
-      // Reset the object to iterate over it again
-      scripts_object.reset();
-      simdjson::ondemand::value value;
-      for (auto field : scripts_object) {
-        std::string_view key_str;
-        std::string_view value_str;
-        if (!field.unescaped_key().get(key_str) && !field.value().get(value) &&
-            !value.get_string().get(value_str)) {
-          fprintf(stderr,
-                  "  %.*s: %.*s\n",
-                  static_cast<int>(key_str.size()),
-                  key_str.data(),
-                  static_cast<int>(value_str.size()),
-                  value_str.data());
-        }
-      }
+      PrintScripts(stderr, scripts_object);
     }
     result->exit_code_ = ExitCode::kGenericUserError;
     return;
diff --git a/test/message/node_run_list.js b/test/message/node_run_list.js
new file mode 100644
index 000000000000..52e8e5fba235
--- /dev/null
+++ b/test/message/node_run_list.js
@@ -0,0 +1,14 @@
+'use strict';
+
+require('../common');
+const assert = require('node:assert/strict');
+const childProcess = require('node:child_process');
+const fixtures = require('../common/fixtures');
+
+const child = childProcess.spawnSync(
+  process.execPath,
+  [ '--no-warnings', '--run'],
+  { cwd: fixtures.path('run-script'), encoding: 'utf8' },
+);
+assert.strictEqual(child.status, 0);
+console.log(child.stdout);
diff --git a/test/message/node_run_list.out b/test/message/node_run_list.out
new file mode 100644
index 000000000000..5f634a03506b
--- /dev/null
+++ b/test/message/node_run_list.out
@@ -0,0 +1,14 @@
+Available scripts are:
+  test: echo "Error: no test specified" && exit 1
+  ada: ada
+  ada-windows: ada.bat
+  positional-args: positional-args
+  positional-args-windows: positional-args.bat
+  custom-env: custom-env
+  custom-env-windows: custom-env.bat
+  path-env: path-env
+  path-env-windows: path-env.bat
+  special-env-variables: special-env-variables
+  special-env-variables-windows: special-env-variables.bat
+  pwd: pwd
+  pwd-windows: cd
diff --git a/test/parallel/test-node-run.js b/test/parallel/test-node-run.js
index e24117f6b165..325693ea3212 100644
--- a/test/parallel/test-node-run.js
+++ b/test/parallel/test-node-run.js
@@ -222,4 +222,39 @@ describe('node --run [command]', () => {
     assert.strictEqual(child.stdout, '');
     assert.strictEqual(child.code, 1);
   });
+
+  it('lists available scripts to stdout when no command is given', async () => {
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [ '--run'],
+      { cwd: fixtures.path('run-script') },
+    );
+    assert.match(child.stdout, /Available scripts are:/);
+    assert.match(child.stdout, /test: echo "Error: no test specified" && exit 1/);
+    assert.strictEqual(child.stderr, '');
+    assert.strictEqual(child.code, 0);
+  });
+
+  it('does not consume a following flag as the script name', async () => {
+    // `--run` followed by a flag lists scripts rather than treating the flag
+    // as a script name.
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [ '--run', '--no-warnings'],
+      { cwd: fixtures.path('run-script') },
+    );
+    assert.match(child.stdout, /Available scripts are:/);
+    assert.strictEqual(child.code, 0);
+  });
+
+  it('errors when listing scripts without a package.json', async () => {
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [ '--run'],
+      { cwd: __dirname },
+    );
+    assert.match(child.stderr, /Can't find package\.json/);
+    assert.strictEqual(child.stdout, '');
+    assert.strictEqual(child.code, 1);
+  });
 });