Repository navigation
wheels packages --help advertises 'install' but the working verb is 'add' — help text drift #2713
Description
Severity: docs / discoverability.
Surfaced by: titan Phase 2.1 (Wheels 4.0 upgrade), 2026-05-15. Sibling to #2706 (install is a silent no-op).
Description
wheels packages --help documents:
install <name> [--force] Install a package
The working command is wheels packages add <name> (which is not in the help output). See #2706 for the install no-op bug.
Even if #2706 is fixed by aliasing install to add, the help text should describe both verbs (or list the canonical one).
Suggested fix
Sync the wheels packages help output with the actual implementation:
- If
installis aliased toadd(per wheels packages install <name> is a silent no-op — canonical install command in docs doesn't actually install #2706 resolution): documentaddas canonical, listinstallas alias. - If
installis removed: just documentadd. - Either way: don't ship a verb in
--helpthat doesn't work.
cc @bpamiri
Activity
wheels-bot commentedon May 15, 2026
Wheels Bot — Triage
Classified as bug.
The
wheels packages --helpoutput advertises a verb (install) that does not work — this is observable wrong behavior in shipped help text, not just a docs site gap. Thedocslabel on the issue reflects the surface (help text), but the defect is in the CLI module itself.Suspected layer
cli— see.ai/wheels/cli/for canonical patterns; the package dispatcher lives atcli/lucli/Module.cfc:2053(packages()function) andcli/lucli/services/packages/PackagesMainCli.cfc.Fix sketch
The
packages()function hint atcli/lucli/Module.cfc:2033-2052already documentsaddas the canonical verb and explains whyinstallis intercepted by LuCLI's built-in extension installer (same trap that bitwheels browser install→wheels browser setupin #2345). The literal help rowinstall <name> [--force] Install a packagereported in the issue doesn't appear verbatim in the source — propose-fix's first task is to locate the help-text generator (most likely LuCLI's introspection of module functions, or a static help table) and sync the verbs. The two plausible resolutions are: (1) dropinstallfrom emitted help entirely and documentadd, or (2) documentaddas canonical and listinstallas an intercepted alias with a redirect note. Resolution depends on whether sibling #2706 reclassifiesinstallas a usable alias.Confidence:
mediumLayer is unambiguous (CLI help text), but the help-text emission path needs investigation, and the right wording depends on how #2706 lands.
<!-- wheels-bot:triage:2713 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:medium -->
wheels-bot commentedon May 15, 2026
Wheels Bot — Fix proposed
Draft PR: #2729
Spec:
cli/lucli/tests/specs/commands/PackagesCommandSpec.cfc— failing → passingImplementation:
cli/lucli/Module.cfc— new$packagesHelp(), short-circuit inpackages(),--help/-hparsing in$packagesArgsToOptionsand$packagesStripFlagsA human review is required before merge. Reviewer A and Reviewer B will weigh in shortly. Doc updates (MDX guides,
.ai/wheels/,CLAUDE.md) are handled separately bybot-update-docs.yml.fix(cli): drop dead -h guard clause and unblock TDD gate for cli/lucl…
fix(cli): `wheels packages` help now documents `add` as canonical ins…