wheels packages

wheels packages is the CLI surface for the wheels-packages registry — a curated, git-based distribution channel for Wheels ecosystem packages. Every verb talks to the registry over plain HTTPS and installs into vendor/<name>/, where PackageLoader picks it up on next reload.

The install verb is add. install is an alias of it, so wheels packages install <name> works the same way. Earlier CLI releases could intercept the literal install subcommand before it reached this command, so add is the form that works on every 4.x CLI.

There is no ForgeBox and no CommandBox. The registry manifest is authoritative, tarballs live on the registry’s GitHub Releases, and every tarball has a sha256 in the manifest that the installer verifies before extraction. Supply-chain attacks via force-pushed tags or drifted source archives are defeated by this design.

Synopsis

"

wheels packages list [--tag=<tag>]
wheels packages search <query>
wheels packages show <name>
wheels packages add <name>[@<version>] [--force]
wheels packages update <name> --yes
wheels packages update --all --yes
wheels packages remove <name> --yes
wheels packages registry refresh
wheels packages registry info

Verbs

Running wheels packages with no verb runs list. An unknown verb prints the valid verbs and exits non-zero.

Verb	Description
list	Show every package in the registry, optionally filtered by --tag.
search	Substring match against name, description, and tags.
show	Detail page for a package: versions, homepage, license, install state.
add	Download, verify, extract into vendor/<name>/.
update	Re-install the latest compatible version. Explicit: requires --yes.
remove	Delete vendor/<name>/. Explicit: requires --yes. Refuses dirs without a package.json.
registry refresh	Bust the 24h cache.
registry info	Print registry URL, branch, cache state.

Design principles

• Explicit updates only. update is never implicit. There is no auto-pull on reload, no background upgrade. This is the only defense against malicious version-bump attacks — the user reviews every bump.
• Registry-hosted tarballs. tarball URLs always point at wheels-dev/wheels-packages releases, never at the author’s repo. GitHub’s source-archive URLs drift; release assets don’t.
• sha256 is mandatory. Installation aborts on mismatch. There is no --skip-checksum flag.
• 24h manifest cache. <CLI home>/cache/packages/ (~/.wheels/cache/packages/ on a normal install; LUCLI_HOME moves it). A registry other than the default (WHEELS_PACKAGES_REGISTRY) caches under its own registries/<hash>/ subdirectory. Respects GitHub’s 60 req/hr unauthenticated limit. registry refresh busts it. With --offline, cached data is used even after it expires.
• Compatibility is checked against the app’s framework. Inside a project, a version’s wheelsVersion range is matched against vendor/wheels; outside one, against the CLI’s own version. A dev build of the CLI (0.0.0-dev) treats every range as compatible.

Configuration

Env var	Purpose	Default
WHEELS_PACKAGES_REGISTRY	Override the registry <org>/<repo>. Used for forks, mirrors, and test registries.	wheels-dev/wheels-packages

Writing a package

See the registry’s CONTRIBUTING.md for the full submission checklist. The tl;dr:

1. Build your package in its own repo with a valid package.json (same schema as the first-party packages — see wheels-sentry for a reference).
2. Tag a release on your repo (e.g. v1.0.0).
3. Open a PR to wheels-packages adding packages/<your-name>/manifest.json with the version entry (leave tarball and sha256 blank — CI fills them).
4. After merge, the mirror-tarball workflow packages your tag, uploads it as a registry release asset, computes the sha256, and commits it back.
5. Users can now wheels packages add <your-name>.