fix(cli): pass through flags

[JuicyBenjamin]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://refine.dev/docs/guides-concepts/contributing/#commit-convention

Bugs / Features

• Related issue(s) linked
• Tests for the changes have been added
• Docs have been added / updated
• Changesets have been added https://refine.dev/docs/guides-concepts/contributing/#creating-a-changeset

What is the current behavior?

When users try to pass command-line flags to the underlying build tools (Vite, Next.js, Remix, etc.) using refine dev, refine start, or refine build, the flags are not passed through.

Example:

npm run dev -- --host  # Flags are ignored, --host never reaches Vite

This happens because:

1. Commander.js with .allowUnknownOption(true) accepts the flags but doesn't capture them in the variadic [args...] parameter
2. Users need to use the awkward npm run dev -- --host syntax (double dash)
3. Even with double dash, the flags weren't being passed through due to missing .passThroughOptions() configuration

What is the new behavior?

Users can now pass flags directly to the underlying build tools with improved UX:

# Works cleanly (thanks to package.json scripts ending with --)
npm run dev --host
npm run dev --port 3001
npm run build --sourcemap

# Manual double dash also still works
npm run dev -- --host

Changes made:

Part 1: CLI Code (4 files)

• Added .passThroughOptions() to dev, start, and build commands in packages/cli/src/commands/runner/{dev,start,build}/index.ts
• Added .enablePositionalOptions() to parent command in packages/cli/src/cli.ts
• This ensures Commander.js properly captures and passes unknown flags to the underlying tools

Part 2: Package.json Scripts (198 examples + 1 utility script)

• Updated all example package.json files: "dev": "refine dev" → "dev": "refine dev --"
• By adding -- at the end of the script, npm automatically treats everything after as arguments to pass through
• Created scripts/update-refine-scripts.js for future maintenance

Why both changes are needed:

1. CLI fix alone = flags pass through, but users still need npm run dev -- --host
2. Package.json fix alone = doesn't work without the CLI fix (flags wouldn't be captured)
3. Both together = users can simply do npm run dev --host ✨

Notes for reviewers

Testing completed locally:

• ✅ Manually tested with Vite project using --host flag - confirmed network exposure works
• ✅ CLI builds successfully
• ✅ Lint-staged checks passed

Pending CI verification:

• All automated tests pass
• No breaking changes detected

Security: No concerns - this only affects argument passing to already-trusted build tools (vite, next, remix) resolved from node_modules/.bin. Arguments are properly escaped by execa.

Example flags this enables:

• Vite: --host, --port, --open, --strictPort
• Next.js: --turbo, --port, --hostname
• Build tools: --sourcemap, --minify, --watch

[changeset-bot]

🦋 Changeset detected

Latest commit: 985be11

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@refinedev/cli	Patch
@refinedev/devtools	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[alicanerdurmaz]

I believe we can remove this scripts/update-refine-scripts.js

[alicanerdurmaz]

I can already pass arguments to Vite and others without .passThroughOptions(). I don't understand what does this actually do?

---

In Refine project:

---

In Refine monorepo:

---