Installing with CommandBox

CommandBox is Ortus Solutions' CFML package manager and server runner. Wheels publishes its framework artifacts to ForgeBox, so you can install and serve a Wheels app with box alone — no wheels CLI required.

This page exists because CommandBox-centric 2.x/3.x teams need a clear answer to one question: what is my supported workflow on Wheels 4?

What CommandBox is supported for

In Wheels 4, CommandBox is supported as a server manager and package fetcher — and that's the whole of it.

| You want to… | CommandBox? | Tool | |---|---|---| | Install the framework from ForgeBox | Yes | box install wheels-base-template | | Run a CFML server (Lucee / Adobe CF / BoxLang) | Yes | box server start | | Vendor wheels-core into an existing app | Yes | box install wheels-core | | Scaffold an app, generators, migrate, test, console | No | the wheels CLI | | The packages registry, MCP server, deploy | No | the wheels CLI |

The short version: CommandBox gets you the framework and a running server. Reach for the wheels CLI for scaffolding — generators, wheels migrate, wheels test, wheels console, the MCP server, the packages registry, and wheels deploy. None of those run through CommandBox.

Two different package systems

ForgeBox (CommandBox) ships the framework itself — wheels-core and the app template. The Wheels packages registry (wheels packages ...) is a separate, wheels-CLI-only system for first-party add-ons like wheels-hotwire and wheels-basecoat. It is not on ForgeBox. See Packages.

The ForgeBox packages

Every stable Wheels release publishes four packages to ForgeBox (see .github/workflows/release.yml):

| Slug | What it is | |---|---| | wheels-base-template | The full app skeleton. Declares wheels-core as a dependency, so installing it pulls the framework into vendor/wheels/ too. Start here. | | wheels-core | The framework core only — installs into vendor/wheels/. Use it to vendor or upgrade the framework inside an existing app. | | wheels-cli | The deprecated legacy CommandBox CLI module. Predates 4.0 and does not know the 4.0 commands — see below. | | wheels-starter-app | A pre-built sample app for demos and experiments. |

All four track the current release version (4.0.x at time of writing).

Supported: install the framework

1. Install CommandBox if you don't have it:

   illustrative — install CommandBox

   # macOS
   brew install commandbox
   # Windows
   choco install commandbox
   # Linux: see https://commandbox.ortusbooks.com/setup/installation

2. Install the base template into an empty directory. This pulls wheels-core into vendor/wheels/ via the template's declared installPaths:

   illustrative — box pulls from ForgeBox

   mkdir myapp && cd myapp
   box install wheels-base-template

   You'll get the modern Wheels 4.0 layout: app/, config/, db/, public/ (the web root), tests/, a server.json, and the framework core in vendor/wheels/.

Vendoring the framework into an existing app

If you already have a Wheels app and just want to add or upgrade the framework, install wheels-core on its own — it lands in vendor/wheels/:

illustrative

box install wheels-core

Use box install wheels-core --force to cleanly replace an older vendor/wheels/.

Supported: serve

The template ships a server.json, so a server start is a one-liner from the app root:

illustrative — box server start

box server start

Pin a specific engine the same way the CFML Engines page describes — CommandBox downloads it on first use:

illustrative — pin the engine

box server start cfengine=lucee@7        # or adobe@2025, or boxlang@latest

Reload the framework after a config or code change by hitting the reload URL directly (there is no wheels reload on this path):

illustrative — reload URL

http://localhost:<port>/?reload=true&password=<your reload password>

Not supported via CommandBox: the wheels CLI feature set

CommandBox fetches and serves; it does not replace the developer CLI. The following all require the LuCLI-based wheels binary (install it from brew / scoop / apt / yum or a manual JAR):

• Scaffolding — wheels new, and every generator (wheels generate model/controller/scaffold/...).
• Migrations — wheels migrate latest|up|down|info|doctor.
• Testing — wheels test.
• Console — wheels console.
• MCP server — wheels mcp wheels.
• The packages registry — wheels packages ... (first-party add-ons; not on ForgeBox).
• Deploy — wheels deploy.

The legacy `wheels-cli` ForgeBox module is deprecated

The CommandBox module published as wheels-cli is the pre-4.0 CLI. It does not know the 4.0+ command set and is scheduled for removal in Wheels 5 (see Upgrading 3.x → 4.x). Do not install it for new work. The supported developer CLI is the standalone wheels binary — see Installing Wheels.

Coming from a 2.x / 3.x box workflow

The 3.x getting-started spine was built on CommandBox. Here's how each old step maps onto Wheels 4:

| 2.x / 3.x (CommandBox) | Wheels 4 | |---|---| | box install wheels-cli | Install the standalone wheels CLI (brew / scoop / apt / yum) | | wheels generate app myApp / wheels g app | wheels new myApp | | box server start | Still works — or wheels start (Lucee, bundled with the CLI) | | ForgeBox plugins (box install ..., forgebox install) | The wheels packages registry (CLI-only; not ForgeBox) | | box install cfwheels-base-template | Slug changed — box install wheels-base-template (the cfwheels--prefixed slug is dead; see below) |

The `cfwheels-base-template` slug is gone — use `wheels-base-template`

If your 2.x muscle memory is box install cfwheels-base-template, that command no longer works. The pre-rebrand cfwheels--prefixed ForgeBox slugs are dead — cfwheels-base-template has been unlisted from ForgeBox entirely, so box install cfwheels-base-template fails with entry slug invalid or does not exist. The framework rebranded to Wheels at 3.0, and the supported 4.x slugs dropped the prefix:

• cfwheels-base-template → wheels-base-template
• cfwheels → wheels-core
• cfwheels-cli → the standalone wheels CLI (the ForgeBox cfwheels-cli module is the pre-rebrand CommandBox CLI; even its renamed successor, the wheels-cli slug, is deprecated)

Install the modern slug instead:

illustrative — the supported 4.x slug

box install wheels-base-template

The practical recommendation: keep CommandBox if you rely on it for Adobe CF or BoxLang server management, and add the wheels CLI alongside it for everything in the feature-set list above.

Related

Installing Wheels Get the wheels CLI — generators, migrate, test, and more.

CFML Engines Run Wheels on Lucee, Adobe CF, or BoxLang via CommandBox.

Packages First-party add-ons via the wheels packages registry.

Upgrading 3.x → 4.x What changed, including the wheels-cli deprecation.