|
| 1 | +--- |
| 2 | +title: Installing with CommandBox |
| 3 | +description: Install and serve the Wheels framework from ForgeBox with CommandBox. Supported as a server manager and package fetcher — not as the Wheels developer CLI. |
| 4 | +type: howto |
| 5 | +sidebar: |
| 6 | + order: 7 |
| 7 | +--- |
| 8 | + |
| 9 | +import { Aside, Steps, CardGrid, LinkCard } from '@astrojs/starlight/components'; |
| 10 | + |
| 11 | +[CommandBox](https://www.ortussolutions.com/products/commandbox) is Ortus Solutions' CFML package manager and server runner. Wheels publishes its framework artifacts to [ForgeBox](https://forgebox.io/), so you can install and serve a Wheels app with `box` alone — no `wheels` CLI required. |
| 12 | + |
| 13 | +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?** |
| 14 | + |
| 15 | +## What CommandBox is supported for |
| 16 | + |
| 17 | +In Wheels 4, CommandBox is supported as a **server manager and package fetcher** — and that's the whole of it. |
| 18 | + |
| 19 | +| You want to… | CommandBox? | Tool | |
| 20 | +|---|---|---| |
| 21 | +| Install the framework from ForgeBox | **Yes** | `box install wheels-base-template` | |
| 22 | +| Run a CFML server (Lucee / Adobe CF / BoxLang) | **Yes** | `box server start` | |
| 23 | +| Vendor `wheels-core` into an existing app | **Yes** | `box install wheels-core` | |
| 24 | +| Scaffold an app, generators, migrate, test, console | **No** | the [`wheels` CLI](/v4-0-0/start-here/installing/) | |
| 25 | +| The packages registry, MCP server, deploy | **No** | the [`wheels` CLI](/v4-0-0/start-here/installing/) | |
| 26 | + |
| 27 | +The short version: **CommandBox gets you the framework and a running server. Reach for the [`wheels` CLI](/v4-0-0/start-here/installing/) for scaffolding** — generators, `wheels migrate`, `wheels test`, `wheels console`, the MCP server, the [packages registry](/v4-0-0/digging-deeper/packages/), and `wheels deploy`. None of those run through CommandBox. |
| 28 | + |
| 29 | +<Aside type="note" title="Two different package systems"> |
| 30 | +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](/v4-0-0/digging-deeper/packages/). |
| 31 | +</Aside> |
| 32 | + |
| 33 | +## The ForgeBox packages |
| 34 | + |
| 35 | +Every stable Wheels release publishes four packages to ForgeBox (see `.github/workflows/release.yml`): |
| 36 | + |
| 37 | +| Slug | What it is | |
| 38 | +|---|---| |
| 39 | +| `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.** | |
| 40 | +| `wheels-core` | The framework core only — installs into `vendor/wheels/`. Use it to vendor or upgrade the framework inside an existing app. | |
| 41 | +| `wheels-cli` | The **deprecated** legacy CommandBox CLI module. Predates 4.0 and does not know the 4.0 commands — see below. | |
| 42 | +| `wheels-starter-app` | A pre-built sample app for demos and experiments. | |
| 43 | + |
| 44 | +All four track the current release version (4.0.x at time of writing). |
| 45 | + |
| 46 | +## Supported: install the framework |
| 47 | + |
| 48 | +<Steps> |
| 49 | + |
| 50 | +1. Install CommandBox if you don't have it: |
| 51 | + |
| 52 | + ```bash title="illustrative — install CommandBox" |
| 53 | + # macOS |
| 54 | + brew install commandbox |
| 55 | + # Windows |
| 56 | + choco install commandbox |
| 57 | + # Linux: see https://commandbox.ortusbooks.com/setup/installation |
| 58 | + ``` |
| 59 | + |
| 60 | +2. Install the base template into an empty directory. This pulls `wheels-core` into `vendor/wheels/` via the template's declared `installPaths`: |
| 61 | + |
| 62 | + ```bash title="illustrative — box pulls from ForgeBox" |
| 63 | + mkdir myapp && cd myapp |
| 64 | + box install wheels-base-template |
| 65 | + ``` |
| 66 | + |
| 67 | + 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/`. |
| 68 | + |
| 69 | +</Steps> |
| 70 | + |
| 71 | +<Aside type="tip" title="Vendoring the framework into an existing app"> |
| 72 | +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/`: |
| 73 | + |
| 74 | +```bash title="illustrative" |
| 75 | +box install wheels-core |
| 76 | +``` |
| 77 | + |
| 78 | +Use `box install wheels-core --force` to cleanly replace an older `vendor/wheels/`. |
| 79 | +</Aside> |
| 80 | + |
| 81 | +## Supported: serve |
| 82 | + |
| 83 | +The template ships a `server.json`, so a server start is a one-liner from the app root: |
| 84 | + |
| 85 | +```bash title="illustrative — box server start" |
| 86 | +box server start |
| 87 | +``` |
| 88 | + |
| 89 | +Pin a specific engine the same way the [CFML Engines](/v4-0-0/start-here/cfml-engines/) page describes — CommandBox downloads it on first use: |
| 90 | + |
| 91 | +```bash title="illustrative — pin the engine" |
| 92 | +box server start cfengine=lucee@7 # or adobe@2025, or boxlang@latest |
| 93 | +``` |
| 94 | + |
| 95 | +Reload the framework after a config or code change by hitting the reload URL directly (there is no `wheels reload` on this path): |
| 96 | + |
| 97 | +```text title="illustrative — reload URL" |
| 98 | +http://localhost:<port>/?reload=true&password=<your reload password> |
| 99 | +``` |
| 100 | + |
| 101 | +## Not supported via CommandBox: the `wheels` CLI feature set |
| 102 | + |
| 103 | +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](/v4-0-0/start-here/installing/) or a [manual JAR](/v4-0-0/command-line-tools/installation/#manual-jar-install)): |
| 104 | + |
| 105 | +- **Scaffolding** — `wheels new`, and every generator (`wheels generate model/controller/scaffold/...`). |
| 106 | +- **Migrations** — `wheels migrate latest|up|down|info|doctor`. |
| 107 | +- **Testing** — `wheels test`. |
| 108 | +- **Console** — `wheels console`. |
| 109 | +- **MCP server** — `wheels mcp wheels`. |
| 110 | +- **The packages registry** — `wheels packages ...` (first-party add-ons; **not** on ForgeBox). |
| 111 | +- **Deploy** — `wheels deploy`. |
| 112 | + |
| 113 | +<Aside type="caution" title="The legacy `wheels-cli` ForgeBox module is deprecated"> |
| 114 | +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](/v4-0-0/upgrading/3x-to-4x/)). Do not install it for new work. The supported developer CLI is the standalone `wheels` binary — see [Installing Wheels](/v4-0-0/start-here/installing/). |
| 115 | +</Aside> |
| 116 | + |
| 117 | +## Coming from a 2.x / 3.x `box` workflow |
| 118 | + |
| 119 | +The 3.x getting-started spine was built on CommandBox. Here's how each old step maps onto Wheels 4: |
| 120 | + |
| 121 | +| 2.x / 3.x (CommandBox) | Wheels 4 | |
| 122 | +|---|---| |
| 123 | +| `box install wheels-cli` | Install the standalone [`wheels` CLI](/v4-0-0/start-here/installing/) (brew / scoop / apt / yum) | |
| 124 | +| `wheels generate app myApp` / `wheels g app` | `wheels new myApp` | |
| 125 | +| `box server start` | Still works — or `wheels start` (Lucee, bundled with the CLI) | |
| 126 | +| ForgeBox plugins (`box install ...`, `forgebox install`) | The [`wheels packages`](/v4-0-0/digging-deeper/packages/) registry (CLI-only; not ForgeBox) | |
| 127 | +| `box install wheels-base-template` + `wheels-core` | Unchanged — still the supported way to fetch the framework with CommandBox | |
| 128 | + |
| 129 | +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](#not-supported-via-commandbox-the-wheels-cli-feature-set). |
| 130 | + |
| 131 | +## Related |
| 132 | + |
| 133 | +<CardGrid> |
| 134 | + <LinkCard |
| 135 | + title="Installing Wheels" |
| 136 | + href="/v4-0-0/start-here/installing/" |
| 137 | + description="Get the wheels CLI — generators, migrate, test, and more." |
| 138 | + /> |
| 139 | + <LinkCard |
| 140 | + title="CFML Engines" |
| 141 | + href="/v4-0-0/start-here/cfml-engines/" |
| 142 | + description="Run Wheels on Lucee, Adobe CF, or BoxLang via CommandBox." |
| 143 | + /> |
| 144 | + <LinkCard |
| 145 | + title="Packages" |
| 146 | + href="/v4-0-0/digging-deeper/packages/" |
| 147 | + description="First-party add-ons via the wheels packages registry." |
| 148 | + /> |
| 149 | + <LinkCard |
| 150 | + title="Upgrading 3.x → 4.x" |
| 151 | + href="/v4-0-0/upgrading/3x-to-4x/" |
| 152 | + description="What changed, including the wheels-cli deprecation." |
| 153 | + /> |
| 154 | +</CardGrid> |
0 commit comments