docs: rename user-facing lucli references to wheels (CLAUDE.md, test-local, guides) - #2544
Conversation
Sorry, something went wrong.
…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.
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.
Sorry, something went wrong.
Summary
Wheels is built on the LuCLI runtime, but the rebranded wheels binary is the only thing end users install. The codebase still carries historical mentions of lucli as 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 to brew install lucli. When lucli wasn't on PATH (the agent had wheels from brew 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 lucli vs wheels confusion.
What changed
What was deliberately NOT changed
These references are accurate and stay:
Type of Change
Feature Completeness Checklist
Test Plan