Conversation
…t-local, guides Wheels is built on the LuCLI runtime, but the rebranded `wheels` binary is the only thing end users install. The codebase still has historical mentions of `lucli` as the user-facing command — left over from the period when the project was migrating off CommandBox onto LuCLI. The mismatch confused at least one Claude Code session: a recent agent followed `tools/test-local.sh`'s "brew install lucli" docstring instead of using the `wheels` command that was actually on PATH, then concluded LuCLI was uninstallable and gave up running the test suite locally. Surgical scope, not a blanket find-and-replace: - CLAUDE.md gets an explicit "wheels IS the CLI" callout in the testing section so future sessions don't repeat the mistake. Updated install instructions to recommend `brew install wheels`, `wheels server run`, `~/.wheels/express`. - tools/test-local.sh switches `lucli` → `wheels` for command invocations and prerequisites; falls back to scanning both `~/.wheels/express` and `~/.lucli/express` for the JDBC lib so the script keeps working through the rename for older installs. - web/sites/guides/.../testing/browser-tests.mdx and running-tests-locally.mdx fix the user-facing "brew install lucli" and `lucli server run` directions. - CHANGELOG entry under [Unreleased] / Changed. References to LuCLI as the upstream runtime project (installation docs that explain how the rebrand works, runtime-specific env vars like `LUCLI_HOME`, dotted CFC paths like `cli.lucli.services.X`, filesystem paths under `cli/lucli/`, framework-dev tooling that genuinely tests the LuCLI module distribution flow) are intentionally retained — they are accurate context, not user instructions. Closes the loose end from PR #2543's review thread.
![wheels-bot[bot]](https://avatars.githubusercontent.com/in/3657588?s=60&v=4){kind=small}
There was a problem hiding this comment.
Wheels Bot — Reviewer A
TL;DR: This is a clean, well-scoped documentation PR that fixes a real contributor-confusion bug (agents concluding `lucli` was a separate install requirement). The change is correct, the rationale is solid, and the "what was deliberately NOT changed" section in the PR body shows good judgement about scope. Three nits below — none are blocking.
Conventions
wheels start vs wheels server run — inconsistency across files
`CLAUDE.md` (manual method section) was changed to:
```bash
CLAUDE.md, manual method section
wheels start --port=8080
```
But `tools/test-local.sh` and `browser-tests.mdx` were updated to:
```bash
tools/test-local.sh line 92
nohup wheels server run --port="$PORT" --force > /tmp/wheels-test-server.log 2>&1 &
browser-tests.mdx
wheels server run --port=8080
```
The dev-tools table in `CLAUDE.md` documents `wheels start|stop|status` as the CLI surface, so `wheels start` is likely the canonical short form and `wheels server run` the explicit form. But having both across different files in the same PR will recreate the same confusion the PR was meant to eliminate — a future reader (or agent) will wonder whether `wheels start` and `wheels server run` are the same command and which one to use. Suggest picking one form and using it everywhere (probably `wheels server run` with flags for the manual/guide examples since it's self-documenting, matching the test script).
Missed `lucli` reference in `running-tests-locally.mdx`
`web/sites/guides/src/content/docs/v4-0-0-snapshot/testing/running-tests-locally.mdx` has one uncleaned reference immediately above the line that was updated:
```md
- `JAVA_HOME` set — LuCLI's preflight refuses to start if this is unset …
```
The bullet right below it was updated to say "The Wheels CLI is built on the LuCLI runtime", but this line still says "LuCLI's preflight" as a user-facing instruction. It should read something like "The CLI's preflight refuses to start…" — the internal runtime detail doesn't need surfacing here.
Docs
Dead variable `WHEELS_VER` in `tools/test-local.sh`
```bash
tools/test-local.sh, {project} placeholder block
WHEELS_VER=$(wheels --version 2>/dev/null | head -1 | grep -oE '[0-9]+.[0-9]+.[0-9]+' || echo "0.0.0")
```
`WHEELS_VER` (formerly `LUCLI_VER`) is computed but never read. The accompanying comment about the version-gated code path was already removed in the original, and the PR removes the remaining comment. The variable can be dropped entirely — the comment above it explains why the `sed` replacement is always done unconditionally.
Commits
Single commit `docs: rename user-facing lucli references to wheels in CLAUDE.md, test-local, guides` — type `docs`, no scope, 79-char subject. Conforms to commitlint.
Overall verdict: comment — the three items above are nits that don't affect correctness or runtime behavior. The PR is shippable as-is; the inconsistency between `wheels start` and `wheels server run` is the only one worth a follow-up if the project wants fully consistent docs.
1 participant
Summary
Wheels is built on the LuCLI runtime, but the rebranded
wheelsbinary is the only thing end users install. The codebase still carries historical mentions ofluclias the user-facing command — left over from the period when the project was migrating off CommandBox onto LuCLI. This PR is a surgical pass to fix the references that mislead users and developers.The trigger: in PR #2543's session,
tools/test-local.sh's docstring told the agent tobrew install lucli. Whenlucliwasn't on PATH (the agent hadwheelsfrombrew install wheels), it concluded LuCLI was uninstallable and gave up running the test suite locally. This is exactly the kind of confusion the rebrand was supposed to eliminate.Related Issue
No GitHub issue — follow-up to #2530 / PR #2543 reviewer thread, where Peter pointed out the
luclivswheelsconfusion.What changed
wheelsIS the CLI" callout in the "Running Tests Locally" section so future Claude sessions don't repeat the mistake. Updated install instructions to recommendbrew install wheels,wheels server run,~/.wheels/express. Replaced "LuCLI canonical form" / "LuCLI stdio MCP" / "LuCLI 0.3.3+" phrasings with "Wheels CLI" where they were referring to the user-facing tool.tools/test-local.sh— Switchedlucli→wheelsfor command invocations and prerequisites. Falls back to scanning both~/.wheels/expressand~/.lucli/expressfor the JDBC lib so the script keeps working for anyone who still has the old standalone install.web/sites/guides/.../testing/browser-tests.mdx— Fixedlucli server run --port=8080example.web/sites/guides/.../testing/running-tests-locally.mdx— Fixed the "brew install lucli, choco install lucli" prerequisite line.[Unreleased]→Changeddocumenting the doc-level rename and the explicit CLAUDE.md callout.What was deliberately NOT changed
These references are accurate and stay:
cli/lucli/services/...,cli.lucli.services.Xdotted CFC paths. Renaming the directory is a much larger refactor; out of scope here.LUCLI_HOME. That's the LuCLI runtime's own env var; renaming it would mean changing the binary, not docs.web/sites/guides/.../command-line-tools/installation.mdxlegitimately explains the relationship ("the LuCLI launcher and the Wheels Module", "rename it towheelsso LuCLI's binary-name detection activates the Wheels branding") — those are accurate context, not user instructions.tools/ci/smoke-test-module.sh,tools/test-onboarding.sh,tools/test-cli-local.sh. Those scripts test installing the Wheels module into a LuCLI runtime and use LuCLI runtime APIs (LUCLI_HOME,lucli modules list) on purpose. Changing them defeats their purpose.web/content/blog/,docs/superpowers/plans/,docs/superpowers/specs/,docs/releases/blog-skeletons/. These are time-stamped records.Type of Change
Feature Completeness Checklist
[Unreleased]→Changedtools/test-local.shstill does the same work, just viawheels server runinstead oflucli server run(verifiedwheels server run --port=N --forceis a working drop-in)Test Plan
wheels server run --port=9099 --forceboots the same Lucee server on a fresh worktree (verified locally — see PR description).bash tools/test-local.shshould now work on machines that only havebrew install wheels(previously requiredbrew install lucliseparately).