How to get started with Wheels 3.0 without 'modern tooling'

[andoradmiraal]

After spending two entire days trying to run Wheels 3.0 for the first time, I finally figured out the secret souce. So to help others who might be in the same situation, this is my advise on how to install Wheels 3.0:

The hardest part is perhaps figuring out which files to download. I found you need to download 3 files:

• wheels-core
• wheels-base-template
• something called 'Wirebox'.

The first two you can download from the Wheels Github, the last one you can download from https://forgebox.io/view/wirebox (click Versions, then on the three dots behind the latest version, then Download).

1. Extract wheels-base-template to your deployment directory
2. In the directory vendor, which is created in step 1, extract wheels-core so that the directory wheels is directly in the root of vendors
3. In this same vendor directory, create a directory wirebox, and extract all files from the wirebox download here
4. Set your web root (in IIS, or whichever other webserver you're using) to the directory 'public' rather than the regular webroot
5. Now set URL rewriting - create a web.config (when using IIS) with the standard URL rewrite code.

You might need to reboot your website or even your server, but now the Wheels application should run the home page.

Hope this helps!

[bpamiri]

Are you using commandbox for your local environment? Just trying to figure out where the friction is?Can you provide more information on what you are doing and what the issues are.-Peter Amiri Sent from my iPhone (auto-typing mispell disclaimer in effect)On Jan 17, 2026, at 8:30 AM, andoradmiraal ***@***.***> wrote: After building Wheels 2.5 apps for years, I'm hopelessly frustrated that I haven't been able to deploy a first Wheels 3.0 testing application, even after two solid working days trying. Undoubtedly it's me being dumb, but I do hope there will soon be some information on how to (manually) deploy Wheels 3.0 applications. I see a lot that looks really promising, I just wish it wasn't so damn hard to get started. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[andoradmiraal]

Hi Peter,

Thanks for getting back—much appreciated, as is all your work on Wheels 3.

Our use case: Lean IIS/Lucee integration via our own app installers/Git repos. No "modern tooling", dependency injection, etc. We like to keep everything very deliberate and controlled in our repos.

Main friction (coming from pre-3.0 archive downloads):

• No step-by-step docs for minimal setup from repos (core, CLI, base templates, etc.)—which combos for bloat-free? Everything in documentation assumes a certain workflow which we just don't have. Finding the files required for deployment (e.g., skip TestBox, keep WireBox - but where to download and how to install?) requires plenty research/trial/error as not documented.
• Yes, did run installer and CommandBox to add additional webservers/Java/CF engines in order to download the set of Wheels files we hoped to eventually get running on IIS. The whole approach seems quite intrusive and impractical. "Export" didn't work for production, but also wouldn't fit our workflow to begin with, so couldn't find any added value of using CommandBox. Also, feels like loss of control when CommandBox just does stuff and we don't really understand what. Hard to then integrate in our own install scripts.
• Simply using 'core' sounded perfect for our workflow, but Core needs a lot of of manual file generation in order to run a clean, blank copy of wheels that could server as our starting point. Didn't find any guidance on which files we need and how to deploy. Spend a lot of time with AIs trying to figure it out, couldn't get it done. Eventually tried the below combination which hit the jackpot.

What worked: Layering base templates + core + WireBox ≈ Wheels 2.5 experience. A release note pointing to this option would save 2.5→3.0 upgraders grief. Hard to figure out by trial and error that this is what's required to run clean copy of Wheels.

Hope these notes help others. Even basic repo explanations on the GitHub download page would go far.

Wheels 3 now runs great on our production server—excited to upgrade apps! 🎉

[bpamiri]

I understand now. We probably lean too much into simplification and leaned into command box approach. It should be simple enough to download the wheels-base-template-3.0.0+XX.zip and the wheels-core-3.0.0+XX.zip from https://github.com/wheels-dev/wheels/releases  Wheels core is the old Wheels directory from the pre 3.0 day. Just expand it and drop it into the vendor folder. You’ll also need to download wirebox and testbox and drop them into the vendor folder as well.I’ll have to look at what else the install scripts do about variable replacement. Perhaps moving these to an initial setup phase might be better.Thanks for the feedback. It’s good to learn out people are using the framework. While building 3.0 we probably moved more toward new users’ experience with the framework and may have made it more difficult for existing users with existing workflows.-Peter Amiri Sent from my iPhone (auto-typing mispell disclaimer in effect)On Jan 19, 2026, at 6:53 AM, andoradmiraal ***@***.***> wrote: Hi Peter, Thanks for getting back—much appreciated, as is all your work on Wheels 3. Our use case: Lean IIS/Lucee integration via our own app installers/Git repos. Main friction (coming from pre-3.0 archive downloads): No step-by-step docs for minimal setup from repos (core, CLI, base templates, etc.)—which combos for bloat-free? Yes, did run installer and CommandBox to add additional webservers/Java/CF engines, though it feels intrusive for our workflow; extracting deployable files (e.g., skip TestBox, keep WireBox) requires trial/error and eventually poses the same problem as downloading repos directly: how to deploy? "Export" didn't work for production, but also wouldn't fit our workflow to begin with. Core needs a lot of of manual file generation, for which I didn't find any guidance. What worked: Layering base templates + core + WireBox ≈ Wheels 2.5 experience. A release note on this would save 2.5→3.0 upgraders grief. Hope these notes help others. Even basic repo explanations on the GitHub download page would go far. Wheels 3 now runs great on our production server—excited to upgrade apps! 🎉 —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you commented.Message ID: ***@***.***>

[andoradmiraal]

Yes, exactly—that's the approach I found worked nicely for us. Simply documenting this on the releases page in one or a few lines, or addding it as an option to the Downloads page, would help the likes of me a lot. I think there must be more people coming from 2.5 who are unfamiliar with (or adverse to) modern tooling; this would help to keep them on board. There really isn't any reason why we wouldn't use Wheels, CommandBox isn't actually required even if Wirebox (and Testbox?) now are. If you go through the normal download procedure, it feels like Wheels 3 no longer fits a deliberate workflow, when in reality, it works just fine.

[andoradmiraal]

To complete my little guide for people doing an install without ColdBox/CommandBox/WhateverBox...

We didn't run into any issues yet without 'Testbox' installed with Wheels, but officially it's required for Wheels. Finding the download link is quite tricky, so here it is:

1. Go to https://forgebox.io/view/testbox
2. Click on Versions
3. Click the three dots behind the version you wish to us, and select Download.

Hope this helps!😊

[zainforbjs]

@andoradmiraal If you want to install Wheels manually without using CommandBox or the CLI, here’s a clear breakdown of what’s required and how to get it running.

Core pieces you need:

1. wheels-core – the framework itself (routing, ORM, request lifecycle, etc.)
2. wheels-base-template – provides the standard app structure (controllers, models, views, config, events, etc.)
3. WireBox – required for dependency injection and object lifecycle management
4. TestBox – optional if you’re only running the app, but strongly recommended if you want to run or write tests

Step-by-step setup

Create your application directory

• Download the latest stable version of the required packages from forgebox: Wheels-base-template, Wheels-core, Wirebox, Testbox(optional).
• First extract the wheels-base-template in your application directory. It will look something like this:

/my-wheels-app
  /app
  /config
  /db
  /public
  /vendor
  /tests

• Extract wheels-core, wirebox and testbox inside the vendor folder and you are good to go.
• You might need to rename the extracted folder. So, rename the extracted wirebox folder to wirebox, the extracted testbox folder to testbox and the extracted wheels folder to wheels.
• After doing this, your vendor folder will look something like this:

/vendor
  /wheels
  /wirebox
  /testbox

The main entry point for a wheels 3.0 application is "/public/index.cfm". So you must configure that in IIS as the entry point to make sure that the wheels application works correctly.

[andoradmiraal]

Thanks, that's a lovely clear overview 👍 I did figure it out eventually, but adding this info to the download page (vs. assuming CommandBox) would help a lot. Or perhaps replace the part of the docs that literally states "manual install is too obvious to explain" with the above info, that would help us non-CommandBox folk keep our sanity :)

While I'm a tad bit saddened by the new non-optional depencies (especially WireBox, which feels like added weight to us not allowing dependency injection), I'm quite excited to try out Testbox, which seems very useful. And since I've ended up listing my personal pain points here: the name change makes searching harder: "CFWheels" was extremely specific and gave 100% relevant results in Google, the generic "Wheels" does, well, the opposite.

Now after sharing the negatives of my upgrade experience, hopefully constructively, let me note that once we had the files, upgrading 2.5 to 3.0 was remarkably smooth, more so than with previous upgrades, major win 🎉

[zainforbjs]

@andoradmiraal Thanks for valuable feedback, and the downloads page has been updated with required information. Hope you enjoying your upgrades with wheels 3.0, Let us know if you find any difficulty further. Thank you

[marshmob]

have you seen a similar set of instructions for getting the sample app installed. I have tried various combinations of downloads without much luck. I am trying to get it working on a cf2025 / iis installation but was having troubles with relative vs absolute resolution of modules. could get around this and another problem arose. I couldnt decide if installation error or an error in the sample app.

[marshmob]

Installed from wheels/example and all is now working

Thanks for your persistence and all the help.

It can get pretty frustrating doing something like a sample app and having a problem getting it going.

Now the fun can begin!!

[zainforbjs]

My bad. I didn't mention clearly in my first message. You have to use the stable version which is 1.0.0.

[zainforbjs]

Great that you got it working. If you have any more queries let me know.

[marshmob]

Oops I missed the tick and cross on the stable field. I just saw 3.0.0-rc-1 which looked like the same release level as the core. New glasses time.

[zainforbjs]

All good — easy detail to miss. Thanks for clarifying.

[michaeldiederich]

First of all, @andoradmiraal, let me kiss your eyes. I was I afraid, i was just too stupid to get this running (and I am still not sure, if I am).
I downloaded the same files. extracted like you said and I needed a "coldbox" directory, which I also downloaded. My vendor folder looks like:

➜  foobar ls vendor
Controller.cfc                      Public.cfc                          controllers                         public
Dispatch.cfc                        README.md                           databaseAdapters                    testbox
Global.cfc                          Test.cfc                            docs                                tests
Job.cfc                             Testbox.cfc                         events                              tests_testbox
Mapper.cfc                          Wirebox.cfc                         helpers                             vendor
Migrator.cfc                        box.json                            mapper                              view
Model.cfc                           coldbox                             migrator                            wheels-core-3.0.0+42-20260203131222
Plugins.cfc                         controller                          model                               wirebox

I changed the root folder to /public and now I get this error:

Message	invalid component definition, can't find component [wheels.Wirebox]

Stacktrace	The Error Occurred in
/home/foobar/vendor/wirebox/system/ioc/Injector.cfc: line 1708
1706:       // Check if just a plain CFC path and build it
1707:       if ( isSimpleValue( arguments.binder ) ) {
1708:          arguments.binder = createObject( "component", arguments.binder );
1709:       }
1710:

called from /home/foobar/vendor/wirebox/system/ioc/Injector.cfc: line 357
called from /home/foobar/vendor/wirebox/system/ioc/Injector.cfc: line 257
called from /home/foobar/public/Application.cfc: line 268

The documentation about the manual installation says nothing about all this stuff, the example application doesn't have this stuff.
So, what is missing? What did I wrong? Is there a "one zip fits all" to start?

Just in case, here are the other folders:

➜  foobar ls vendor/coldbox 
CONTRIBUTING.md             box.json                    license.txt                 server-adobe@2025.json      server-boxlang@1.json       system
ModuleConfig.bx             build                       readme.md                   server-boxlang-cfml@1.json  server-lucee@5.json         test-harness
apidocs                     changelog.md                server-adobe@2023.json      server-boxlang-cfml@be.json server-lucee@6.json         tests
➜  foobar ls vendor/wirebox
box.json         license.txt      readme.md        system           wirebox-8.0.5+33
➜  foobar ls vendor/testbox
CONTRIBUTING.md            cfml                       run                        server-boxlang-cfml@1.json system
box.json                   changelog.md               run.bat                    server-boxlang@1.json      test-visualizer
build                      license.txt                server-adobe@2021.json     server-lucee@5.json        tests
bx                         readme.md                  server-adobe@2023.json     server-lucee@6.json

[zainforbjs]

@michaeldiederich You don't need a coldbox folder to get wheels to work. It looks like the wheels folder got extracted directly inside vendor folder instead of being in "vendor/wheels". As I said above, you just need to follow these steps:

Core pieces you need:

1. wheels-core – the framework itself (routing, ORM, request lifecycle, etc.)
2. wheels-base-template – provides the standard app structure (controllers, models, views, config, events, etc.)
3. WireBox – required for dependency injection and object lifecycle management
4. TestBox – optional if you’re only running the app, but strongly recommended if you want to run or write tests

Step-by-step setup

Create your application directory

• Download the latest stable version of the required packages from forgebox: Wheels-base-template, Wheels-core, Wirebox, Testbox(optional).
• First extract the wheels-base-template in your application directory. It will look something like this:

/my-wheels-app
  /app
  /config
  /db
  /public
  /vendor
  /tests

• Extract wheels-core, wirebox and testbox inside the vendor folder and you are good to go.
• You might need to rename the extracted folders. So, rename the extracted wirebox-* folder to "wirebox", the extracted testbox-* folder to "testbox" and the extracted wheels-* folder to "wheels".
• After doing this, your vendor folder will look something like this:

/vendor
  /wheels
  /wirebox
  /testbox

The main entry point for a wheels 3.0 application is "/public/index.cfm". So you must configure that in IIS as the entry point to make sure that the wheels application works correctly.

[michaeldiederich]

Thanks, you are right, it now works. Except the tests:

Message	could not find component or class with name [testbox.system.modules.globber.models.PathPatternMatcher]

Stacktrace	The Error Occurred in
/home/foobar/vendor/testbox/system/TestBox.cfc: line 848
846:    private function getSpecPaths( required directory ){
847:       var results            = [];
848:       var pathPatternMatcher = new testbox.system.modules.globber.models.PathPatternMatcher();
849:
850:       // recurse default

called from /home/foobar/vendor/testbox/system/TestBox.cfc: line 280
called from /home/foobar/vendor/testbox/system/TestBox.cfc: line 95
called from /home/foobar/tests/runner.cfm: line 103
called from /home/foobar/vendor/wheels/Public.cfc: line 45
called from /home/foobar/vendor/wheels/Dispatch.cfc: line 237
called from /home/foobar/public/index.cfm: line 5
called from /home/foobar/public/Application.cfc: line 229

➜  foobar ls vendor 
testbox wheels  wirebox

➜  foobar ls vendor/testbox 
CONTRIBUTING.md            cfml                       run                        server-boxlang-cfml@1.json system
box.json                   changelog.md               run.bat                    server-boxlang@1.json      test-visualizer
build                      license.txt                server-adobe@2021.json     server-lucee@5.json        tests
bx                         readme.md                  server-adobe@2023.json     server-lucee@6.json

➜  foobar ls vendor/testbox/system 
Application.cfc           CollectionExpectation.cfc TestBox.cfc               coverage                  runners
Assertion.cfc             Expectation.cfc           TestResult.cfc            mockutils                 stubs
BaseSpec.cfc              MockBox.cfc               compat                    reports                   util

There is no modules folder?

The only change so far was set(urlRewriting="Off");.

Thanks for your help!

[zainforbjs]

TestBox has its own dependencies that are automatically downloaded when you install it via CommandBox. Since you’re not using CommandBox, you’ll need to place these dependencies manually. There are four required modules:

• Globber
• cbMockData
• CBStreams
• cbproxies

Each module must be extracted into a folder with the exact same name as the module (for example, Globber must be extracted into a Globber directory).

After extracting all four modules:

1. Move cbproxies into cbstreams/modules/
2. Move Globber, cbMockData, and CBStreams into vendor/testbox/system/modules/

If the modules directory does not exist, create it. Once this structure is in place, TestBox should run correctly.

[michaeldiederich]

Thank you very much!

[bpamiri]

Hi guys, I just wanted to pipe in and apologize in a way. As I eluted to above we made some assumptions and leaned too much into the modern workflows and reliance on CommandBox, WireBox, and TestBox. I realize now that for those whose normal workflows don't include these tools, using Wheels 3.0 becomes increasingly difficult. Having to manually download multiple packages and manually put them into the right order just to get the framework operational was not what we set out to achieve. By adopting a CommandBox native implementation mechanism we were trying to simplify adoption and use of the framework but now see that we may have had the opposite effect for some veteran users.

I now have some work in flight for the next revision of the framework dubbed 3.1. This revision reorganizes the directory slightly in order to make it completely runnable from a simple GitHub download or clone. It will have zero dependencies as well so you will not have to scramble to download multiple packages just to get the framework running.

The latest round should start to show up in the snapshots and I'll blog about it in a day or so once the dust settles.

[blastiko]

Yeah, good times when i was download the zip, extract it and i was already to go.
Anybody of expert can give me how to cofigure Nginx web server to obtain a work environment?
Because I'm a developer, not system administrator.
Thank bpamiri, I hope that the framework return to be easy to set-up like in the past.

[bpamiri]

I’ve reworked the directory structure on the develop branch so a single download is all you need. No dependencies just point an app server to the /public folder. I hope to have the work finished up in the next few days and be able to update the docs so you can test. It started out as a 3.1 target, but it is starting to look more and more like a 4.0 target. Not in time, most of it is done, but in the scope of what is included. I’ve been a little sidetracked with a side project that is starting to blow up right now. It's an AI agent orchestrator, I know, not another one of those, but needed it for all the work I'm doing in my day job and accross multiple GitHub Orgs. Read about it here: ***@***.***_9391/welcome-to-the-grove-6537759563ee Welcome to the Grove medium.com

…

-Peter

On Mar 23, 2026, at 8:31 AM, blastiko ***@***.***> wrote: Yeah, good times when i was download the zip, extract it and i was alredy to go. Anybody of expert can give me how to cofigure Nginx web server to obtain a work environment? Because I'm a developer, non system administrator. Thank bpamiri, I hope that the framework return to be easy to set-up like in the past. — Reply to this email directly, view it on GitHub <#1838?email_source=notifications&email_token=AABMCS2OJO2VD7BP54YEEZT4SFKGTA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCNRSG43TSOBYUZZGKYLTN5XKOY3PNVWWK3TUUVSXMZLOOSWGM33PORSXEX3DNRUWG2Y#discussioncomment-16277988>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABMCSYNFKHRYFYWZ7WAMR34SFKGTAVCNFSM6AAAAACSAORCNWVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTMMRXG44TQOA>. You are receiving this because you commented.

[andoradmiraal]

Me and my team are so happy to see that Wheels 4 is out! We can't wait to play with it.

However, the whole modern tooling situation seems to have become even more complex, which is quite unfortunate for us lowly, non-dependency-management users. Our Wheels application itself already takes care of its dependency management, and we've consciously kept our stack and workflow as simple and minimalist as possible. As a result, we've held off adopting additional tools for as long as we could.

We've now resigned ourselves to the fact that we need to learn at least some of the modern tooling and terminology just to understand the Getting Started guide on the Wheels website. But there are so many options and technologies, it's really quite overwhelming. Which one to pick?

After doing some research, we think that, for someone who already has an existing Lucee application and simply wants to upgrade to the latest Wheels version, LuCLI is probably the simplest way to get hold of the framework files. Is that correct? Or is it still perfectly reasonable to download the appropriate files directly from the GitHub repository? If so, do the same file selection and directory structure from Wheels 3 still apply?

As it might help others too, here is the glossary we ended up building to be able to understand the Getting Started guide. Please do correct us where we've misunderstood something! Also note that every technology is only described here in terms of obtaining the Wheels framework. Most of them undoubtedly do much more than that, but we've intentionally kept the scope narrow.

CommandBox
A command-line tool that can install, manage and run CFML servers and projects. Popular with many CFML developers. But well, this one pretty much everyone knows about by now, I think.

ForgeBox
A service used by CommandBox for package management. We think that if you want to obtain Wheels using CommandBox, you'll need ForgeBox as well.

LuCLI
We understand this to be a lightweight command-line tool for developing and managing Lucee and CFWheels projects; think of it as CommandBox Lite. It appears to be Lucee-specific for development tasks, but if you're only using it to obtain the Wheels files, the engine you eventually deploy to doesn't really matter, of course, so could be the easiest route to obtain Wheels for everyone.

Homebrew
A package manager for macOS.

Chocolatey
A package manager for Windows. It's mentioned in the documentation, but with the recommendation to use Scoop instead.

Scoop
Another package manager for Windows.

SDKMAN!
A version manager for Java and other JVM-related tools. It appears to be part of the Java-based installation route.

Maven
A Java dependency management and build system used by some supporting tools rather than by Wheels itself. Probably not relevant if your only goal is obtaining the Wheels framework.

Wheels CLI
The piece of software that eventually downloads the Wheels framework. As we understand it, each of the tools above installs the Wheels CLI, and the Wheels CLI is then used to obtain the actual Wheels files.

Wheels binary
This one confused us greatly. According to ChatGPT, it likely refers to the Wheels command-line executable rather than the Wheels framework itself. The existence of this does not mean that Wheels has become a compiled framework. Lucee and ACF still compile the CFML to Java bytecode at runtime, just as before, so don't be let astray by this one!

Wheels JAR
Similarly, we understand this to be a JAR distribution of the Wheels CLI rather than the Wheels framework itself. If you're not planning on using Java to download Wheels, you can probably ignore it.

Wheels bucket
This is Scoop terminology. Just as Git has repositories, Scoop has buckets. The Wheels bucket is simply the Scoop repository containing the Wheels package.

So, this is how we currently understand the documented options to download Wheels:

1. Install one of the following softwares:

   • CommandBox
   • LuCLI
   • Any of the package managers mentioned
   • The JAR distribution

2. Use that to install the Wheels CLI.

3. Use the Wheels CLI to download the Wheels framework

4. Copy the framework to your application and start using it

Hopefully this helps others read and understand the Getting Started guide if they're not using modern tooling.

I'll report back once I've figured out if I can make Wheels work when obtaining the framework files directly from the repository. Or perhaps someone more knowledgeable than us (which at this moment feels like about 99% of the community!) can point us in the right direction. Do the above hints for Wheels 3 still apply?

Trying to read and understand the Getting Started guide left us feeling a bit deflated, especially the "5 minutes!" line. We thought we had good reasons for not switching to modern tooling, but if it means being left behind by the Wheels community, we may need to rethink our entire workflow. That would also mean making significant changes to our Wheels application by replacing our own dependency management with one or more external tools, giving up some of the control in our app that we actually really like in favor of a more complicated workflow.

---

[mikegrogan]

I can echo some of this. We've used Commandbox for local development for years and didn't really want to switch. Still hope to not. Basic install of ACF on windows server with IIS in front as well. Having LuCL now as well seems slightly confusing. Yes, I get that it can maybe do things commandbox couldn't quite do for wheels specifically, but the way we have our wheels setup I don't think it currently plays nice with Lucl.

As much as I think the AI development has helped with great progresses in the wheels code base, and responsiveness on the forums, I think a lot of us our still trying to catch up and figure out how everything fits and how we want to go forward. And the docs can be confusing. Broken links. Maybe outdated information. Wheels 4 information linking back to wheels 3 docs.

I've been reading some of the blog posts though and definitely excited to try some of the new features. But first baby steps trying to get wheels 4 in production. Mostly a time thing at the moment for us. And working through some wheels bugs (edge cases) that were responded to very quickly in the discussions, which i'm grateful for. As always thank you to the developers working on wheels and pushing it forward. Being around for 20 years is no small feat..

[bpamiri]

Hi everyone,

I wanted to chime in and explain the reasoning behind some of the recent decisions. First let's address the switch from CommandBox to Wheels CLI. For years I've been wanting to make a Wheels command line tool that was a first class citizen in the OS. Meaning you simply say wheels new myapp instead of having to have the wheels portion by a subcommand line box wheels new myapp or even lucli wheels new myapp. Working with Mark Drew who was beginning to build out the functionality of LuCLI, he was open to me adding the capability for LuCLI to be while labeled. So the new Wheels CLI is really LuCLI binary renamed to wheels. This new capability allows really any project or team to create their own CLI tool using LuCLI as the base and with a little configuration be able to rename the cli to whatever they want.

This allowed us to inherit all the LuCLI tools and add in our own wheels specific tooling. The next step was how to get this installed on each supported platform. I relied on LuCLI to build the binaries for each platform which included MacOS, Windows, and ARM based and Intel based linux distributions. I just came up with the tooling to make it easier to install the Wheels CLI on each platform. Upon every release of Wheels, we now publish a package for Homebrew (support MacOS and Linux), Scoop (support Windows), apt/yum package managers to support native linux distribution package managers.

Another important distinction for the Wheels CLI was that it embeds the corresponding application template in its local ~/.wheels directory. This means by doing wheels --version you can see what version of the framework is installed on your dev box. And since the template is already embedded you can create wheels projects without needing to download anything or even needing an internet connection.

I hear you about needing more documentation around manual installation. I'll try to get better at creating some of that. I'm glad to see more vocal interest in the framework and welcome your input in how we may want to steer it into the future.

-Peter

[bpamiri]

Following up on my earlier comment with something concrete — everything below is live on the guides site now, not a plan.

First: thank you, genuinely, for the specifics in this thread. The two days @andoradmiraal spent reverse-engineering a manual install, the glossary his team had to build just to read our Getting Started guide, @marshmob's CF2025/IIS walkthrough, @michaeldiederich's TestBox dependency-chain notes, @blastiko's nginx ask, and @mikegrogan's broken-links report — all of it went directly into an evidence-based review of all 188 pages in the v4 guides, including having testers walk the docs cold as each of the people in this thread. The short version of what we found: you were right. There was no manual install path anywhere in the v4 guides (v3 had one; v4 dropped it), no IIS page, no URL-rewriting page, and several of the pages that matter most to you weren't even reachable from the sidebar. That's all been fixed over the past two days, in six merged rounds of changes.

@andoradmiraal — direct answers to your three questions:

1. Is LuCLI/the CLI the simplest way to get the framework files? You don't need it — or any tool — at all. Manual Installation (zip / GitHub) is now a first-class documented path, written against the actual 4.0.5 release zips.
2. Is downloading from GitHub still reasonable? Yes, fully supported, and it got dramatically simpler than Wheels 3: two zips, zero dependencies. wheels-base-template is the app skeleton; wheels-core extracts into vendor/wheels/. That's the complete list.
3. Does the Wheels 3 file selection still apply? Happily, no — you no longer need WireBox or TestBox at all. Wheels 4 has its own built-in DI container and test framework, so the WireBox + TestBox + four-hidden-modules scavenger hunt from this thread is over. The page documents the old 3.x layering only as a historical aside for anyone still maintaining a 3.x app.

And your glossary became a real page: Choosing Your Tooling — your terms, corrected where you asked (the biggest one: the wheels CLI is LuCLI rebranded; you never install one to get the other) and maintained by us from now on. Thank you for writing the first draft the hard way.

@mikegrogan — two things for you. First, plainly: CommandBox teams do not have to switch. box install wheels-base-template and box server start are supported indefinitely, and every task page (migrations, seeding, testing, CI, datasources) now shows a "Without the wheels CLI" path right next to the CLI path — Working Without the CLI is the one-page map of every equivalent, including which are dev-only and what the production-safe alternative is. Second, the broken links and v4→v3 cross-links you mentioned: we found 12 broken internal links (including one in the middle of the tutorial) and 15 pages missing from the sidebar — all fixed.

The rest of what shipped, in one list:

• Upgrading Without the CLI — the framework upgrade is a vendor/wheels/ folder swap; this page is that recipe for patch bumps and the 3.x→4.0 jump, with the manual counterpart to every CLI step in the upgrade guide.
• What's New in 4.0 — the ten-minute "why upgrade" tour for people coming from 3.x.
• URL Rewriting — @blastiko, this one's for you: the one rewrite rule Wheels needs, shown for nginx, Apache, IIS, and Tuckey, with a verification checklist.
• IIS and Windows Deployment — assembled from the CF2025 + IIS + MySQL 8 recipe @marshmob and @zainforbjs worked out in this thread, applied to the 4.0 layout, including the CF Administrator datasource requirement and the MySQL 8 nullCatalogMeansCurrent gotcha. One honest caveat: this page is the newest and least battle-tested — if a step doesn't match what you see on your box, say so here and we'll fix the page.
• Anatomy of a Wheels App — every directory explained, including the 2.x → 4.0 mental mapping.
• The guides landing page now routes by situation — "I don't use CLI tooling" and "I have a 2.x/3.x app" are front doors, not archaeology.

Nothing here walks back the CLI for people who want it — the new-user path is untouched. The change is that not wanting it is now a documented, supported, first-class choice instead of a two-day reverse-engineering project.

Keep the specifics coming — this thread has been the most useful docs review we've ever had, and the fastest way to get a page fixed is to tell us exactly where it's wrong.

[mikegrogan]

Thanks for all the hard work. Will try to review everything soon!