[cknitt]

rescript rewrote its argv before Cmdliner parsed it, so that command lines written for the Rust build system kept working. This PR removes most of that. What's left is -h as an alias for --help and -V for --version, since Cmdliner only defines the long names.

Command lines that change:

Before	Now
rescript ./pkg builds ./pkg	unknown command; use rescript build ./pkg
rescript -v build, rescript -q watch	error asking for options after the command; use rescript build -v
rescript -vh, rescript -Vh (help/version clustered with other flags)	unknown option; use -h or -V alone
rescript bogus --help printed the root help and exited with 0	unknown command, exit 2

rescript, rescript --prod ./pkg, rescript clean and every command-first form behave as before. rescript-vscode and the create-rescript-app templates put the command first wherever they name one.

Without the rewrite, Cmdliner reads a command name after an option as the default build's folder, so rescript -v build would build a folder named build. The default build therefore rejects a folder spelled exactly like a command and points to ./build for a real folder of that name.

Supersedes #9264, whose bug can't happen once nothing drops positional arguments.

Tests: the cluster and options-first cases are replaced with cases asserting the new errors for a bare folder, -v build and bogus --help/-V. The test scripts that put -q/-v/-vv before the command now put them after it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Kbf3gLt5FhNDjMw2sNude8

[github-actions]

Changelog

💥 Breaking Change

• rescript needs the command before its options and folder, as in rescript build -v ./pkg, and reports an unknown command even when --help or --version follows it.

Semantic Diff

2 commits · Full page

Require the command before options in the build system's CLI

_{0247e6f · cknitt + Claude · Nov 08, 2026, 18:06 UTC}

Why

normalize_argv rewrote argv so that Rust-era forms (a bare folder, options before the command, -h/-V clusters) kept working on Cmdliner. Its help/version precedence dropped positional words, so an unknown command followed by --help or --version printed help or the version and exited with 0. Only -h and -V remain as aliases now.

Diagnostic modified (unknown command with a display flag)

text

 $ rescript invalid --help
-NAME
-       rescript - Fast, Simple, Fully Typed JavaScript from the Future
-…
-exit 0
+Usage: rescript [--help] [COMMAND] …
+rescript: unknown command invalid. Must be one of build, clean,
+          compiler-args, format, help or watch
+exit 2

Diagnostic modified (options before the command)

text

 $ rescript -v build
-(builds the current folder with debug output)
+Usage: rescript [--help] [COMMAND] …
+rescript: options go after the command: rescript build [OPTION]… (write
+          ./build for a folder named build)
+exit 2

Diagnostic modified (bare folder)

text

 $ rescript ./pkg
-(builds ./pkg)
+rescript: unknown command ./pkg. Must be one of build, clean, …
+exit 2

⚠️ Breaking: rescript <folder> becomes rescript build <folder>, options go after the command (rescript build -v), and -h/-V no longer combine with other flags in one cluster.

Review

• Why reject in the default term instead of scanning argv? Options such as -f take a value, so a scan cannot tell -f build from -v build; Cmdliner has already parsed the options when the default term sees a folder named like a command.

✨ Match unknown commands in the CLI test whether or not colors are on

_{3a9a1d2 · cknitt + Claude · Nov 08, 2026, 18:13 UTC · new}

CI forces colors, and Cmdliner then quotes the command name instead of styling it, so the test checks the message and the name separately.

[github-actions]

✅ Compiler benchmarks

Allocated words

In total: 456,989,425 → 456,989,425 (±0.00%).

None of the 257 benchmarks changed by 0.1% or more.

Instructions

In total: 10,226,961,997 → 10,226,961,997 (±0.00%).

None of the 33 benchmarks changed by 0.1% or more.

Pull request 3a9a1d2 compared with base d47adb3 in this run.

[pkg-pr-new]

Open in StackBlitz

rescript

npm i https://pkg.pr.new/rescript@9266

@rescript/belt

npm i https://pkg.pr.new/@rescript/belt@9266

@rescript/darwin-arm64

npm i https://pkg.pr.new/@rescript/darwin-arm64@9266

@rescript/linux-arm64

npm i https://pkg.pr.new/@rescript/linux-arm64@9266

@rescript/linux-x64

npm i https://pkg.pr.new/@rescript/linux-x64@9266

@rescript/runtime

npm i https://pkg.pr.new/@rescript/runtime@9266

@rescript/win32-x64

npm i https://pkg.pr.new/@rescript/win32-x64@9266

commit: 3a9a1d2

[github-actions]

Developer playground preview: https://rescript-lang.github.io/rescript/dev-playground/?version=pr-9266