src: list scripts when `--run` has no command by Cherry · Pull Request #64606 · nodejs/node · GitHub

This extends the behaviour when you run node --run <unknown script> that prints a list of available scripts, to now print available scripts when you simply run node --run, to mimic the behaviour of npm run, etc.

$ node --run
Available scripts are:
  test: node --test
  build: node build.js

Previously, node --run with no command errored with --run requires an argument.

This is my first contribution to Node.js so while I've tried to read and follow everything, please let me know if I'm missing anything!

Fixes: #64870

Review requested:

@nodejs/config
@nodejs/startup

Is there a better solution to modifying the options parser directly? We have other CLI flags that have different behavior depending on whether or not they have an argument passed?

How does --inspect do this?

I'm not entirely familiar with the code, but looking at --inspect, it's a boolean option so works a bit differently I think:

node/src/node_options.cc

Lines 475 to 479 in 0bcc6ef

    
           AddOption("--inspect", 
        
                     "activate inspector on host:port (default: 127.0.0.1:9229)", 
        
                     &DebugOptions::inspector_enabled, 
        
                     kAllowedInEnvvar); 
        
           AddAlias("--inspect=", { "--inspect-port", "--inspect" });

So --inspect and --inspect=1234 work, but --inspect 1234 isn't valid.

If I'm understanding correctly, --run can't do this, because it's space separated.

To avoid the hardcoded name == "--run", what would you suggest?

hmm, perhaps I was mis-remembering that --inspect required an = to run 😓. I'm still wary about changing the parser, since there probably should be a way for a flag to be passed with an optional value, regardless of =.

Sorry about misremembering, I'll ask around to see if there's a way to do this, and if not, we can always add it.

thanks! It's also very possible I'm misreading this or missing something, and this is already supported somewhere - sorry if so!

I doubt that, you (so far) demonstrate a great understanding of the codebase. It's probable that we just never encountered this scenario before.

Great work so far :-)

Implementation LGTM. I'm not giving this the green check while I look into better ways of actually detecting the option-less flag, but everything from that point on is great :)

Codecov Report

❌ Patch coverage is 86.20690% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.13%. Comparing base (cf30b2e) to head (2958891).
⚠️ Report is 117 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_options-inl.h	50.00%	0 Missing and 3 partials ⚠️
src/node_task_runner.cc	95.23%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #64606      +/-   ##
==========================================
+ Coverage   90.11%   90.13%   +0.01%     
==========================================
  Files         752      752              
  Lines      251861   251873      +12     
  Branches    47365    47363       -2     
==========================================
+ Hits       226955   227016      +61     
+ Misses      16238    16186      -52     
- Partials     8668     8671       +3

Files with missing lines	Coverage Δ
src/node.cc	76.53% <100.00%> (ø)
src/node_options.h	95.37% <100.00%> (+0.48%)	⬆️
src/node_task_runner.cc	89.78% <95.23%> (+0.45%)	⬆️
src/node_options-inl.h	83.09% <50.00%> (-0.18%)	⬇️

... and 32 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Just pushed to fix the markdown linting - looks like I needed to prepend to changes, not append, sorry!

The macOS test failure looks to be an unrelated flake, but let me know if not.

Thank you James! @Cherry

GHA is borked on the current PR head, and looks like there will be lint issues to address anyway, so I'm just going to trigger a rebase.

Let me know if I can help with any of the linting (etc.) issues! Thanks all.

Let me know if I can help with any of the linting (etc.) issues! Thanks all.

@Cherry can you rebase and ask your agent to fix the linting errors please?

The only complaint appears to be:

doc/node.1 is out of date; run `make node.1` to regenerate it.

Yeah I can rebase and try and fix that shortly!

Should be good now, thanks!

CI: https://ci.nodejs.org/job/node-test-pull-request/75338/

Overall fine with the idea, but there's a subtly that's worth calling out.

$ export CMD=test
$ node --run $CMD
// Runs the test script

$ export CMD=
$ node --run $CMD
// Lists the available scripts

Re-using the --run could lead to edge case bugs if the user does not realize the CMD env var is not set.

Yeah that's a fair point, though I think this edge-case is a pretty common shell thing - for example node $CMD with an empty var drops you into the REPL (or exits 0 in CI), and npm run $CMD / yarn / pnpm all list scripts and exit 0 the same way.

That said, since --run $CMD used to fail hard here, happy to keep the listing but exit non-zero when no command is given (like bare git) - scripts with a broken env var would still fail, and interactive users still get the list. Let me know if folks would prefer that and I'll update.

That sounds like a reasonable approach to me.

Updated to do a non-zero exit (9 seemed the most appropriate looking at other codes, but happy to tweak), and then print to stderrr. Let me know if there's any other feedback!

CI is looking good! Let me know if there's anything further I can do to help land this. Pushed up changes to resolve the merge conflicts.

Signed-off-by: James Ross <james@jross.me>

CI: https://ci.nodejs.org/job/node-test-pull-request/76329/

Landed in 5e48fb3

nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Jul 19, 2026

Cherry force-pushed the run-list-scripts branch from 228c3da to 141c9e6 Compare July 19, 2026 21:12

avivkeller reviewed Jul 19, 2026

View reviewed changes

Comment thread src/node_task_runner.cc Outdated

Cherry force-pushed the run-list-scripts branch from 141c9e6 to cb3f4d7 Compare July 19, 2026 23:19

avivkeller added the cli Issues and PRs related to the Node.js command line interface. label Jul 19, 2026

Cherry force-pushed the run-list-scripts branch from cb3f4d7 to a39f0dc Compare July 20, 2026 13:00

anonrig approved these changes Jul 31, 2026

View reviewed changes

anonrig added author ready PRs that have at least one approval, no outstanding review comments, and a CI started. request-ci Add this label to start a Jenkins CI on a PR. labels Jul 31, 2026

github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Jul 31, 2026

This comment was marked as outdated.

Sign in to view

Renegade334 force-pushed the run-list-scripts branch from a39f0dc to 95d7a9a Compare July 31, 2026 16:22

Renegade334 removed the author ready PRs that have at least one approval, no outstanding review comments, and a CI started. label Jul 31, 2026

Cherry force-pushed the run-list-scripts branch from 95d7a9a to 8f4567d Compare July 31, 2026 17:11

Cherry mentioned this pull request Jul 31, 2026

tools: fix man-page generation on Windows #64886

Merged

Cherry force-pushed the run-list-scripts branch from 8f4567d to d6729cf Compare August 3, 2026 13:36

src: list scripts when --run has no command

2958891

Signed-off-by: James Ross <james@jross.me>

Cherry force-pushed the run-list-scripts branch from d6729cf to 2958891 Compare August 18, 2026 14:44

This comment was marked as outdated.

Sign in to view

jasnell approved these changes Aug 21, 2026

View reviewed changes

This comment was marked as outdated.

Sign in to view

trivikr added author ready PRs that have at least one approval, no outstanding review comments, and a CI started. commit-queue Add this label to land a pull request using GitHub Actions. labels Aug 23, 2026

nodejs-github-bot merged commit 5e48fb3 into nodejs:main Aug 24, 2026
71 checks passed

nodejs-github-bot removed the commit-queue Add this label to land a pull request using GitHub Actions. label Aug 24, 2026

theoludwig mentioned this pull request Aug 26, 2026

2026-08-26, Version 26.8.0 (Current) #65551

Merged

+                    // `--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";

	AddOption("--inspect",
	"activate inspector on host:port (default: 127.0.0.1:9229)",
	&DebugOptions::inspector_enabled,
	kAllowedInEnvvar);
	AddAlias("--inspect=", { "--inspect-port", "--inspect" });

src: list scripts when `--run` has no command by Cherry · Pull Request #64606 · nodejs/node · GitHub

Uh oh!

Uh oh!

src: list scripts when --run has no command - #64606

src: list scripts when --run has no command#64606nodejs-github-bot merged 1 commit intonodejs:mainnodejs/node:mainfrom Cherry:run-list-scriptsCherry/node:run-list-scriptsCopy head branch name to clipboard

Conversation

Cherry commented Jul 19, 2026 • edited by Renegade334 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nodejs-github-bot commented Jul 19, 2026

Uh oh!

avivkeller Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

Cherry Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

avivkeller Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

Cherry Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

avivkeller Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

avivkeller commented Jul 19, 2026

Uh oh!

codecov Bot commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Cherry commented Jul 20, 2026

Uh oh!

anonrig commented Jul 31, 2026

Uh oh!

This comment was marked as outdated.

Renegade334 commented Jul 31, 2026

Uh oh!

Cherry commented Jul 31, 2026

Uh oh!

anonrig commented Jul 31, 2026

Uh oh!

Renegade334 commented Jul 31, 2026

Uh oh!

Cherry commented Jul 31, 2026

Uh oh!

Cherry commented Jul 31, 2026

Uh oh!

nodejs-github-bot commented Jul 31, 2026

Uh oh!

jasnell commented Aug 2, 2026

Uh oh!

Cherry commented Aug 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jasnell commented Aug 2, 2026

Uh oh!

Cherry commented Aug 3, 2026

Uh oh!

Cherry commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

nodejs-github-bot commented Aug 23, 2026

Uh oh!

Uh oh!

nodejs-github-bot commented Aug 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

src: list scripts when --run has no command#64606
nodejs-github-bot merged 1 commit into
nodejs:mainfrom
Cherry:run-list-scripts

Cherry commented Jul 19, 2026 •
edited by Renegade334
Loading

codecov Bot commented Jul 20, 2026 •
edited
Loading

Cherry commented Aug 2, 2026 •
edited
Loading

Cherry commented Aug 18, 2026 •
edited
Loading