Skip to content

Should node support subcommands? #53483

Open
Open
Should node support subcommands?#53483
Labels
cliIssues and PRs related to the Node.js command-line interface.feature requestIssues requesting new Node.js features.never-staleIssues and PRs exempt from automated stale handling.

Description

@MoLow
MoLow
opened on Jun 17, 2024

What is the problem this feature will solve?

currently, node's cli interface is pretty simple and lean,
it mainly accepts flags that start with two dashes, or sometimes a single dash for some aliases.
additionally, many flags depend on each other or imply using another flag.

now that more and more flags are added to node, (and each new flag is heavily considered before adding to avoid options bloat), I propose we support a more complex cli interface with sub-commands.
this issue has come up before when adding node --run, and to avoid blocking that - the discussion was postponed, so I went ahead and opened this issue.

If I recall, the main concern was node run or node test is a breaking change since it today runs node run.js or node test.js accordingly - that can be addressed with releasing this gradually as semver-major with a deprecation warning for a few versions prior to the actual change

some groups/clusters of commands that might fit using sub commands:

  • node --run
  • node --watch, --watch-path
  • node --test
  • node --build-snapshot

What is the feature you are proposing to solve the problem?

N/A

What alternatives have you considered?

No response

Activity

  1. MoLow
    added
    feature requestIssues requesting new Node.js features.
    cliIssues and PRs related to the Node.js command-line interface.
    on Jun 17, 2024
  2. github-project-automation
    added this to Node.js feature requestson Jun 17, 2024
  3. github-project-automation
    moved this to Pending Triage in Node.js feature requestson Jun 17, 2024

  4. tniessen commented on Jun 17, 2024

    @tniessen
    tniessen
    on Jun 17, 2024
    Member

    I've voiced concerns about this various times in the past, perhaps most recently in this comment. Don't get me wrong, subcommands are great, and if we were to redesign Node.js from scratch we likely should use them. However, ...

    I have reason to believe that a significant number of users rely on the fact that node test runs either test.js or test/index.js, and the same is likely true for node run. So while semver-major releases technically allow us to break things, I think this would cause significant breakage. There's probably many semi-maintained npm modules that use node test (or variations thereof) as their npm test script.

    More generally, accepting either a positional argument or a subcommand in the same location is an anti-pattern in my mind. We unfortunately already have node inspect, so Node.js is already following something that I'd consider an anti-pattern, but that shouldn't be a loophole for us to further commit to that anti-pattern.

    The only semi-reasonable way I see is to fully deprecate node xyz, where xyz would usually cause the execution of whatever xyz resolves to. Of course, this would be a huge breaking change and would likely take years, but anything less than this will introduce more and more inconsistencies, and each new subcommand would cause new breakage and deprecation cycles.

  5. MoLow commented on Jun 17, 2024

    @MoLow
    MoLow
    on Jun 17, 2024
    MemberAuthor

    The only semi-reasonable way I see is to fully deprecate node xyz, where xyz would usually cause the execution of whatever xyz resolves to. Of course, this would be a huge breaking change and would likely take years, but anything less than this will introduce more and more inconsistencies, and each new subcommand would cause new breakage and deprecation cycles.

    why would that take years?

  6. tniessen commented on Jun 17, 2024

    @tniessen
    tniessen
    on Jun 17, 2024
    Member

    We can doc-only deprecate the current behavior right now, and releasing that would take days to weeks. But actually moving node xyz to end-of-life seems like a huge breaking change to me. (Then again, some project members are more open to rapidly breaking things than myself, so maybe it would just take two semver-majors or so.)

    We could take some pragmatic, not very elegant steps to avoid reaching end-of-life status, e.g., by still allowing node xyz whenever xyz looks like a path (e.g., contains a file extension or a directory separator). But in any case, we'll break the very basics of how people run JavaScript files with Node.js.

  7. richardlau commented on Jun 17, 2024

    @richardlau
    richardlau
    on Jun 17, 2024
    Member

    But in any case, we'll break the very basics of how people run JavaScript files with Node.js.

    I think, for example, that preventing node xyz from running xyz would stop Node.js shell scripts (i.e. those that begin

    #!/usr/bin/env node
...

    ) from working.

  8. avivkeller commented on Jun 17, 2024

    @avivkeller
    avivkeller
    on Jun 17, 2024 · Hidden as outdated

  9. richardlau commented on Jun 17, 2024

    @richardlau
    richardlau
    on Jun 17, 2024
    Member

    For files with the same name as commands, the project could adopt what many CLIs do, which is if a value is within quotes, don't treat as a CLI flag (IE "--hello" is a file, while --hello is a CLI argument)

    I'm not aware of anything else that does this, but IMO this would be terribly confusing to users -- in many cases the quotes would be processed by the shell and wouldn't be seen by the program being run (i.e. node).

  10. avivkeller commented on Jun 17, 2024

    @avivkeller
    avivkeller
    on Jun 17, 2024 · Hidden as outdated

  11. MoLow commented on Jun 17, 2024

    @MoLow
    MoLow
    on Jun 17, 2024
    MemberAuthor

    I think, for example, that preventing node xyz from running xyz would stop Node.js shell scripts

    why would adding subcommands break hashbang? I am not following

  12. richardlau commented on Jun 17, 2024

    @richardlau
    richardlau
    on Jun 17, 2024
    Member

    I think, for example, that preventing node xyz from running xyz would stop Node.js shell scripts

    why would adding subcommands break hashbang? I am not following

    Because if you have a file called xyz that begins:

    #!/usr/bin/env node
...

    that has execute permissions and you run it, e.g.

    xyz

    it will end up running the equivalent of

    node xyz

  13. anonrig commented on Jun 18, 2024

    @anonrig
    anonrig
    on Jun 18, 2024
    Member

    I'm +1 on making this breaking change. I think the UX for cli flags are really bad that even I have some trouble understanding if feature X is working with feature Y.

  14. avivkeller
    moved this from Awaiting Triage to Triaged in Node.js feature requestson Jun 26, 2024

  15. github-actions commented on Dec 16, 2024

    @github-actions
    github-actionsbot
    on Dec 16, 2024 – with GitHub Actions
    Contributor

    There has been no activity on this feature request for 5 months. To help maintain relevant open issues, please add the never-stale Issues and PRs exempt from automated stale handling. label or close this issue if it should be closed. If not, the issue will be automatically closed 6 months after the last non-automated comment.
    For more information on how the project manages feature requests, please consult the feature request management document.

  16. github-actions
    added
    staleIssues and PRs marked stale due to inactivity and scheduled for automatic closure.
    on Dec 16, 2024
  17. anonrig
    removed
    staleIssues and PRs marked stale due to inactivity and scheduled for automatic closure.
    on Dec 16, 2024

  18. github-actions commented on Jun 15, 2025

    @github-actions
    github-actionsbot
    on Jun 15, 2025 – with GitHub Actions
    Contributor

    There has been no activity on this feature request for 5 months. To help maintain relevant open issues, please add the never-stale Issues and PRs exempt from automated stale handling. label or close this issue if it should be closed. If not, the issue will be automatically closed 6 months after the last non-automated comment.
    For more information on how the project manages feature requests, please consult the feature request management document.

  19. github-actions
    added
    staleIssues and PRs marked stale due to inactivity and scheduled for automatic closure.
    on Jun 15, 2025
  20. anonrig
    added
    never-staleIssues and PRs exempt from automated stale handling.
    and removed
    staleIssues and PRs marked stale due to inactivity and scheduled for automatic closure.
    on Jun 15, 2025

  21. vassudanagunta commented on Mar 5, 2026

    @vassudanagunta
    vassudanagunta
    on Mar 5, 2026
    Contributor

    While I think I'm ok with the breaking change wrt to node xyz, an alternative to consider is having separate commands:

    node <script, even if "test">
node-test <test script>
node-inspect <script to debug>
node-run <pkg script>

  22. vassudanagunta commented on Mar 5, 2026

    @vassudanagunta
    vassudanagunta
    on Mar 5, 2026
    Contributor

    If node test invoked the test subcommand, then one could use node -- test to force "test" to be treated as an argument.

  23. vassudanagunta commented on Mar 6, 2026

    @vassudanagunta
    vassudanagunta
    on Mar 6, 2026
    Contributor

    Another option, that is backward compatible, is for node test to work as it does today IFF test resolves to a script, and otherwise to invoke the test subcommand.

    If you think of the test subcommand as the built-in default resolution for node test, user overridable by the presence of a script named test in the cwd, there is both rhyme and reason to this behavior.

    Why bother? Because the current node CLI is unwieldy and will only get worse. For example see discussions under #51384 and nodejs/test-runner#13.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    cliIssues and PRs related to the Node.js command-line interface.feature requestIssues requesting new Node.js features.never-staleIssues and PRs exempt from automated stale handling.

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions