Installing Wheels

Install the wheels CLI. Five minutes.

You’ll learn:

• How to install Wheels on macOS, Windows, or Linux
• How to verify the install worked
• How to upgrade later

Adobe ColdFusion or BoxLang user?

The wheels CLI bundles a Lucee runtime — that’s the easiest path for development and what the rest of these docs assume. The framework itself runs on Adobe ColdFusion 2023/2025 and BoxLang too; you’ll use CommandBox to manage the engine instead of the bundled CLI. See CFML Engines for the setup.

Already a CommandBox user?

You can install and serve the framework straight from ForgeBox with box install wheels-base-template and box server start — no wheels CLI required. That path is supported as a server manager and package fetcher, but the generators, migrate, test, and the rest of the CLI feature set still need the wheels binary below. See Installing with CommandBox for the support tiers.

Note

Prerequisite: Java 21 or newer. wheels bundles a CFML runtime (Lucee) that targets JDK 21. Install it from Adoptium if you don’t already have it, or on macOS:

your shell

brew install openjdk@21

On macOS, openjdk@21 is keg-only — Homebrew won’t symlink it into /opt/homebrew. The wheels CLI handles this itself, but if you want to call java directly (or use it from an IDE, Maven, Gradle, etc.) you’ll also need to set JAVA_HOME and add it to your PATH. See Troubleshooting below.

Choose a channel

Wheels ships on two parallel channels. The instructions below install stable (wheels) — the right pick for ~95% of users. If you want bleeding-edge (wheels-be, tracks every merge to develop), see Release Channels for the comparison and install steps.

The two are mutually exclusive — both expose the wheels binary. You install one, not both. You can switch later without losing any of your already-scaffolded apps.

Install the CLI

macOS

Don't have Homebrew yet?

The macOS steps below assume Homebrew is installed. Check with:

your shell

brew --version

If you see “command not found”, install Homebrew first using the official installer:

your shell

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Heads-up while it runs:

• The installer asks for your account password — it needs sudo to create /opt/homebrew (Apple Silicon) or /usr/local (Intel).

• If Xcode Command Line Tools aren’t already installed, the installer triggers them. That opens a system dialog and takes ~5–10 minutes before the brew install resumes.

• When the installer finishes, it prints a “Next steps” block with two commands you must run so brew lands on your PATH. On Apple Silicon those are:

  your shell

  echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
  eval "$(/opt/homebrew/bin/brew shellenv)"

  On Intel, replace /opt/homebrew with /usr/local.

Confirm with brew --version before continuing to step 1 below.

Headless / non-interactive installs

The official installer requires a TTY: it shells out to sudo -n true to check admin rights, which always prompts for a password and never succeeds in a non-interactive context (CI runners, provisioning scripts, agent shells, packer builds). Setting NONINTERACTIVE=1 doesn’t help — the sudo gate still fires. If you need to install Homebrew without a human at the keyboard, the supported options are:

• User-prefix install (no sudo): git clone https://github.com/Homebrew/brew ~/homebrew, then add ~/homebrew/bin to your PATH. Officially “unsupported” by the Homebrew team but works fine — the trade-off is no pre-built bottles, so every install becomes a source build (slower, sometimes much slower).
• Pre-bake the image: install Homebrew once interactively on a base image (Vagrant / Packer / Tart / Anka / VM template) and clone from there for headless work.
• Provisioning frameworks: Ansible’s community.general.homebrew module and similar can drive an expect-style password prompt if you have a way to feed sudo credentials.

On a fresh agent/CI VM with no admin access, the path of least resistance is the user-prefix git clone install.

1. Tap the Wheels Homebrew repo:

   your shell

   brew tap wheels-dev/wheels

   Homebrew 5.1+ asks you to trust third-party taps on first use — run brew trust wheels-dev/wheels once if prompted.

2. Install the CLI:

   your shell

   brew install wheels

3. Verify:

   wheels --version

   You should see a Wheels Version: <version> line followed by ASCII art. A Lucee Version: <version> line may also appear once Lucee Express has been downloaded (typically on first wheels start). Any non-empty version output means the CLI is wired up correctly.

Windows

Don't run `choco install wheels`

The legacy wheels package on chocolatey.org is the CommandBox-based v1.x release and cannot drive this tutorial. Wheels v4 ships on Windows through Scoop instead — see CLI Installation for the full rationale.

1. Install Scoop if you don’t have it (skip if scoop --version already works):

   PowerShell

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression

2. Install git (required by Scoop to add any third-party bucket — skip if git --version already works):

   PowerShell

   scoop install git

   The Scoop installer doesn’t ship git, but scoop bucket add uses git clone under the hood. The default main bucket is the one exception — its metadata is bundled with Scoop, which is why scoop install git from a fresh shell works without any prior bucket setup.

3. Add the Wheels bucket and install a channel:

   PowerShell

   scoop bucket add wheels https://github.com/wheels-dev/scoop-wheels
   scoop install wheels        # stable - tracks v4.0.0 GA tags
   # OR:
   scoop install wheels-be     # bleeding-edge - tracks every develop merge

   Both packages inline OpenJDK 21 — no separate java bucket or JAVA_HOME setup required. Both expose the same wheels shim on PATH, so Scoop refuses to install both at once. See Release Channels for the comparison.

4. Verify:

   PowerShell

   wheels --version

   You should see a Wheels Version: <version> line followed by ASCII art. A Lucee Version: <version> line may also appear once Lucee Express has been downloaded (typically on first wheels start). Any non-empty version output means the CLI is wired up correctly.

Pick LuCLI and Wheels Module versions that are known to be paired — see CLI Installation → Manual JAR install for the canonical version-pairing source.

Linux

Wheels publishes signed native apt and yum repositories at https://apt.wheels.dev and https://yum.wheels.dev. Add the source once, then apt upgrade wheels / dnf upgrade wheels picks up new versions automatically. The package installs /usr/bin/wheels, declares OpenJDK 21 as a runtime dependency (so apt/dnf pulls a JDK in automatically), and on first run syncs the framework module into ~/.wheels/.

GPG signing

The apt and yum repos are GPG-signed with the Wheels Distribution key (fingerprint 6872 16C9 32B4 9F03 94E0 9AED 5D89 AF8F 9C9B 8CFB). apt/dnf verify the signature on every update, so a network-level attacker can’t substitute the package contents. The public half is published at https://apt.wheels.dev/wheels.gpg and https://yum.wheels.dev/wheels.gpg — both files are byte-identical. The sources.list / .repo snippets below wire the signature check in automatically. The published key is ASCII-armored, so the Debian/Ubuntu snippet pipes it through sudo gpg --dearmor before writing /usr/share/keyrings/wheels.gpg — apt expects a binary keyring there and rejects an armored key with an “unsupported filetype” warning and a NO_PUBKEY error.

1. Add the Wheels apt/yum source:

   Debian / Ubuntu — stable

   curl -fsSL https://apt.wheels.dev/wheels.gpg \
     | sudo gpg --dearmor -o /usr/share/keyrings/wheels.gpg
   echo "deb [signed-by=/usr/share/keyrings/wheels.gpg] https://apt.wheels.dev stable main" \
     | sudo tee /etc/apt/sources.list.d/wheels.list
   sudo apt update && sudo apt install wheels

   Fedora / RHEL — stable

   sudo dnf config-manager --add-repo https://yum.wheels.dev/wheels.repo
   sudo dnf install wheels

   Want bleeding-edge?

   The bleeding-edge channel publishes a fresh .deb/.rpm on every merge to develop. It’s served from the same apt.wheels.dev / yum.wheels.dev hosts but under a separate bleeding-edge distribution name, with a distinct package name (wheels-be) so it can coexist with the stable wheels install on the same host:

   Debian / Ubuntu — bleeding-edge

   curl -fsSL https://apt.wheels.dev/wheels.gpg \
     | sudo gpg --dearmor -o /usr/share/keyrings/wheels.gpg
   echo "deb [signed-by=/usr/share/keyrings/wheels.gpg] https://apt.wheels.dev bleeding-edge main" \
     | sudo tee /etc/apt/sources.list.d/wheels-be.list
   sudo apt update && sudo apt install wheels-be

   Fedora / RHEL — bleeding-edge

   sudo dnf config-manager --add-repo https://yum.wheels.dev/wheels-be.repo
   sudo dnf install wheels-be

   Snapshot tags use a SemVer hyphen (v4.0.0-snapshot.1825) and the package’s internal version preserves the ~snapshot.N form so apt/dnf order the version correctly relative to GA. See Release Channels.

2. Verify:

   your shell

   wheels --version

   You should see a Wheels Version: <version> line followed by ASCII art. A Lucee Version: <version> line may also appear once Lucee Express has been downloaded (typically on first wheels start). Any non-empty version output means the CLI is wired up correctly.

Upgrading

macOS

your shell

brew update
brew upgrade wheels

If Homebrew 5.1+ refuses with an “untrusted tap” error, run brew trust wheels-dev/wheels once, then re-run the upgrade.

Windows

Upgrade through Scoop — it pulls the latest LuCLI launcher and Wheels Module from the wheels-dev/scoop-wheels bucket:

PowerShell

scoop update wheels
# or, for the bleeding-edge channel:
scoop update wheels-be

Linux

Once the apt or yum source from the install step is in place, upgrades are a single command — apt/dnf watches the repo and pulls the latest signed package on every refresh:

Debian / Ubuntu

sudo apt update && sudo apt upgrade wheels        # or `wheels-be` for bleeding-edge

Fedora / RHEL

sudo dnf upgrade wheels                            # or `wheels-be` for bleeding-edge

The first wheels invocation after upgrade syncs the new framework module into ~/.wheels/modules/wheels/ automatically.

Troubleshooting

wheels: command not found

Your shell’s PATH doesn’t include the CLI. Restart your shell first — most installs only put the binary on PATH for new shell sessions. On macOS, confirm Homebrew’s bin path is in PATH: echo $PATH | tr ':' '\n' | grep brew. On Linux, the .deb/.rpm package installs /usr/bin/wheels, which should be on every user’s default PATH; if it’s not, check dpkg -L wheels (Debian) or rpm -ql wheels (RHEL) to confirm the package installed and the binary is where expected.

Error: unable to find Java runtime

Install Java 21+ from Adoptium. On macOS: brew install openjdk@21. The wheels wrapper resolves Java on its own, but anything else (java -version, IDEs, Maven, Gradle) needs JAVA_HOME and PATH set in your shell profile:

~/.zshrc or ~/.bashrc

export JAVA_HOME="$(brew --prefix openjdk@21)/libexec/openjdk.jdk/Contents/Home"
export PATH="$JAVA_HOME/bin:$PATH"

If you installed from Adoptium directly instead of Homebrew, use whatever /usr/libexec/java_home -v 21 prints for JAVA_HOME.

brew: cask 'wheels' has no formulae to install from

You skipped brew tap wheels-dev/wheels. Run the tap command, then re-run the install.

Refusing to load formula wheels from untrusted tap wheels-dev/wheels

Homebrew 5.1+ requires trusting third-party taps before installing or upgrading from them. Run brew trust wheels-dev/wheels once, then re-run the command.

Related guides

Your First 15 Minutes Zero to a running page.

Build a Blog The real introduction. Three and a half hours.

Upgrading Wheels Move between Wheels versions.