LuCLI intercepts --version flag causing failure in wheels deploy command

[zainforbjs]

Describe the bug
Running wheels deploy --version=v1.2.3 fails with a LuCLI argument parsing error:

Invalid value for option '--version': 'v1.2.3' is not a boolean

The error is thrown by LuCLI, not Wheels, because --version is being interpreted as a global CLI flag instead of a command-specific argument.

To Reproduce
Steps to reproduce the behavior:

1. Create a Wheels application using:

wheels new myapp

2. Run the deploy command after the deploy init step and configuration:

wheels deploy --version=v1.2.3

3. Observe the error:

Invalid value for option '--version': 'v1.2.3' is not a boolean

Expected behavior
The deploy command should accept a version string:

wheels deploy --version=v1.2.3

and pass it to the deploy handler without conflict.

Actual behavior

• LuCLI intercepts --version as a global CLI flag
• It expects a boolean (--version)
• Instead receives a string (v1.2.3)
• Command fails before Wheels deploy logic executes

Screenshots

Desktop (please complete the following information):

• OS: macOS
• Version: Wheels 4.0.0 (Development)

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

Suspected layer

cli — see .ai/wheels/cli/ for canonical patterns. The deploy subsystem owns its own arg parser at cli/lucli/Module.cfc:1959 ($deployArgsToOptions), but it never gets a chance to see --version because picocli (LuCLI's root-level option processor) absorbs the flag during argument parsing — see cli/lucli/ARCHITECTURE.md:74 which explicitly lists --version as one of "picocli's root-level absorbed flags." The same file (line 78) confirms picocli processes versionHelp = true flags before call() runs, so the value v1.2.3 is then validated against the boolean flag's expected type and rejected with the reported message.

Fix sketch

The cleanest fix is to introduce a non-conflicting alias for the deploy-scoped flag (e.g., --release or --tag) and keep --version reserved for the LuCLI root banner. The parser in cli/lucli/Module.cfc:1972-1976 would accept the new flag (continuing to populate opts.version), the existing DeployAppCli.cfc:112 "This verb requires --version" user-facing message would be updated to match, and the deploy docs (docs/src/command-line-tools/commands/deploy/) plus any wheels deploy docs strings would mention the rename. An alternative — teaching the wrapper / Module.cfc to detect wheels deploy … and pass through positional/option args verbatim before picocli sees them — is more invasive and touches every other subcommand's contract; the rename is much safer.

Confidence: medium

Layer and root cause are unambiguous, but the fix touches the deploy subsystem, which is on the auto-downgrade list (deploy, migrations, DI) — so capped at medium. Reviewer A/B will critique the chosen alias and the docs/help-text sweep.

<!-- wheels-bot:triage:2674 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:medium -->

[wheels-bot]

Wheels Bot — Fix on hold for human review

The proposed fix touches a sensitive area (cli/lucli/services/deploy/** and the wheels deploy arg-parsing surface in cli/lucli/Module.cfc) and the bot's safety net requires a human in the loop before any code is written.

The triage comment (#issuecomment-4450287501) already flagged this as touching the deploy auto-downgrade scope, and the recommended approach (renaming --version to --release/--tag) has cross-cutting implications:

• It is a user-facing CLI rename on a command that ships in 4.0 — picking the alias is a product decision (--release matches Kamal's version, but --tag matches Docker vocabulary).
• It requires a coordinated sweep across the parser ($deployArgsToOptions), DeployAppCli.cfc:112 user-facing error string, the per-verb help text in wheels deploy docs, and the deployment guides under docs/src/working-with-wheels/deployment/ and docs/src/command-line-tools/commands/deploy/.
• An alternative — having Module.cfc detect wheels deploy … and pass --version/positional args through verbatim before picocli sees them — would preserve the existing CLI surface but changes the contract for every other subcommand and needs an architect-level call.

A maintainer should decide between (a) the rename, (b) the picocli-passthrough route, or (c) a third path before the bot writes a spec or implementation.