Command Line Tools

wheels packages add

Adds a package into vendor/<name>/ from the registry. To activate it, run wheels reload (or wheels stop && wheels start) — PackageLoader discovers the new vendor/<name>/package.json when onApplicationStart re-fires. An authorized wheels reload is sufficient; a missing or wrong reload password silently skips the restart.

Synopsis

wheels packages add <name>[@<version>] [--force]

Flags

Flag	Description
`--force`	Overwrite `vendor/<name>/` if it already exists.

Version selection

Without a pin, picks the highest versions[] entry whose wheelsVersion constraint is satisfied by the running framework. With a pin:

@1.2.3 — exact match.
@^1.0.0 — caret (compatible-with): >=1.0.0 <2.0.0.
@~1.2.0 — tilde (patch-level): >=1.2.0 <1.3.0.
@>=1.0 <2.0 — space-separated range.

The same SemVer matcher that PackageLoader uses at runtime.

Failure modes

Error	Cause
`Wheels.Packages.UnknownPackage`	Name not in the registry.
`Wheels.Packages.NoCompatibleVersion`	No version satisfies both the runtime and the pin.
`Wheels.Packages.ChecksumMismatch`	Tarball sha256 differs from the manifest’s record. Refusing to install.
`Wheels.Packages.AlreadyInstalled`	`vendor/<name>/` exists. Use `--force`.
`Wheels.Packages.ManifestIncomplete`	Registry hasn’t mirrored this version yet. Wait for the CI run to finish.

Example

$ wheels packages add wheels-sentry
Installed wheels-sentry@1.0.0 → /Users/me/app/vendor/wheels-sentry
Run `wheels reload` (or restart) to activate it.

$ wheels packages add wheels-sentry@1.0.0 --force
Installed wheels-sentry@1.0.0 → /Users/me/app/vendor/wheels-sentry
Run `wheels reload` (or restart) to activate it.