You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Apr 21, 2026. It is now read-only.
@@ -4,79 +4,314 @@ description: Install Wheels and get a local development server running
4
4
5
5
# Getting Started
6
6
7
-
By far the quickest way to get started with Wheels is via [CommandBox](https://www.ortussolutions.com/products/commandbox). CommandBox brings a whole host of command line capabilities to the CFML developer. It allows you to write scripts that can be executed at the command line written entirely in CFML. It allows you to start a CFML server from any directory on your machine and wire up the code in that directory as the web root of the server. What's more is, those servers can be either Lucee servers or Adobe ColdFusion servers. You can even specify what version of each server to launch. Lastly, CommandBox is a package manager for CFML. That means you can take some CFML code and package it up into a module, host it on ForgeBox.io, and make it available to other CFML developers. In fact we make extensive use of these capabilities to distribute Wheels plugins and templates. More on that later.
7
+
The quickest way to get started with Wheels 3.1 is via [LuCLI](https://github.com/cybersonic/LuCLI) — a lightweight, Lucee-native command line tool. LuCLI starts in under a second, includes built-in MCP support for AI-assisted development, and provides everything you need for your daily development workflow.
8
8
9
-
One module that we have created is a module that extends CommandBox itself with commands and features specific to the Wheels framework. The Wheels CLI module for CommandBox is modeled after the Ruby on Rails CLI module and gives similar capabilities to the Wheels developer.
9
+
If you're already using [CommandBox](https://www.ortussolutions.com/products/commandbox), it continues to work with Wheels 3.1. See the [alternative setup with CommandBox](#alternative-setup-with-commandbox) section below, or the full [Migration Guide](command-line-tools/cli-guides/migration-from-commandbox.md) for a detailed comparison.
10
10
11
-
### Install CommandBox
11
+
## Install LuCLI
12
+
13
+
Install LuCLI using your platform's package manager:
12
14
13
-
The first step is to get [CommandBox](https://www.ortussolutions.com/products/commandbox) downloaded and running. CommandBox is available for Windows, Mac & Linux, and can be installed manually or using one of the respective package managers for each OS. You can use [Chocolatey](https://chocolatey.org) on Windows, [Homebrew](https://brew.sh) on MacOS, or Yum/Apt on Linux depending on your flavor of Linux. Please follow the instructions on how to install CommandBox on your particular operating system. At the end of the installation process you want to make sure the `box` command is part of your system path so you can call the command from any directory on your system.
15
+
```bash
16
+
# macOS
17
+
brew install lucli
14
18
15
-
Once installed, you can either double-click on the `box` executable which opens the CommandBox shell window, or run `box` from a CMD window in Windows, Terminal window in MacOS, or shell prompt on a Linux server. Sometimes you only want to call a single CommandBox command and don't need to launch a whole CommandBox shell window to do that, for these instances you can call the CommandBox command directly from your default system terminal window by prefixing the command with the `box` prefix.
19
+
# Windows
20
+
choco install lucli
16
21
17
-
So to run the CommandBox `version` command you could run box version from the shell or you could launch the CommandBox shell and run version inside it.
22
+
# Manual (any OS)
23
+
# Download from https://github.com/cybersonic/LuCLI/releases
24
+
```
18
25
19
-
{% tabs %}
20
-
{% tab title="Shell" %}
21
-
box version
22
-
{% endtab %}
26
+
Verify the installation:
23
27
24
-
{% tab title="CommandBox" %}
25
-
version
26
-
{% endtab %}
27
-
{% endtabs %}
28
+
```bash
29
+
lucli --version
30
+
```
28
31
29
-
This is a good concept to grasp, cause depending on your workflow, you may find it easier to do one versus the other. Most of the commands you will see in these CLI guides will assume that you are entering the command in the actual CommandBox shell so the `box` prefix is left off.
32
+
### Install the Wheels Module
30
33
31
-
### Install the wheels-cli CommandBox Module
34
+
LuCLI uses modules to extend its functionality. Install the Wheels module to get all framework-specific commands:
32
35
33
-
Okay, now that we have CommandBox installed, let's add the Wheels CLI module.
36
+
```bash
37
+
lucli modules install wheels
38
+
```
34
39
35
-
{% tabs %}
36
-
{% tab title="CommandBox" %}
37
-
install wheels-cli
38
-
{% endtab %}
39
-
{% endtabs %}
40
+
This adds the `wheels` command to your terminal with commands for creating applications, generating code, running migrations, testing, and more.
40
41
41
-
Installing this module will add a number of commands to your default CommandBox installation. All of these commands are prefixed by the `wheels` name space. There are commands to create a brand new Wheels application or scaffold out sections of your application. We'll see some of these commands in action momentarily.
42
+
## Create Your First Application
42
43
43
-
### Start a new Application using the Wizard
44
+
### Using the Wizard (Recommended)
44
45
45
-
To install a new application using version 3.0, we can use the new application wizard and select Bleeding Edge when prompted to select the template to use.
46
+
The interactive wizard walks you through project setup options — template selection, database configuration, and more:
46
47
47
-
{% tabs %}
48
-
{% tab title="CommandBox" %}
48
+
```bash
49
49
wheels new
50
-
{% endtab %}
51
-
{% endtabs %}
50
+
```
51
+
52
+
Follow the prompts to configure your application. For your first project, the defaults work well.
53
+
54
+
### Using the Command Line
55
+
56
+
If you prefer a single command, use `wheels generate app` (or the shorthand `wheels g app`):
57
+
58
+
```bash
59
+
wheels generate app myApp
60
+
cd myApp
61
+
```
62
+
63
+
This scaffolds a complete Wheels application with:
64
+
65
+
- The standard MVC directory structure (`app/controllers/`, `app/models/`, `app/views/`)
- An embedded H2 database (ready to use, no setup needed)
68
+
- The Wheels framework in `vendor/wheels/`
69
+
70
+
{% hint style="info" %}
71
+
**Command Aliases**
52
72
53
-
### Start a New Application Using the Command Line
73
+
`generate` can be shortened to `g`, so `wheels generate app` and `wheels g app` are identical. LuCLI also supports shorthand aliases for common generators: `m` (model), `c` (controller), `v` (view), `s` (scaffold).
74
+
{% endhint %}
54
75
55
-
Now that we have CommandBox installed and extended it with the Wheels CLI module, let's start our first Wheels app from the command line. We'll look at the simplest method for creating a Wheels app and starting our development server.
76
+
## Start the Development Server
56
77
57
-
{% tabs %}
58
-
{% tab title="CommandBox" %}
59
-
wheels generate app myApp\
60
-
server start
61
-
{% endtab %}
62
-
{% endtabs %}
78
+
From your application directory, start the embedded Lucee server:
So what just happened? Since we only passed the application name `myApp` to the `wheels generate app` command, it used default values for most of its parameters and downloaded our Base template (wheels-base-template) from ForgeBox.io, then downloaded the framework core files (wheels.dev) from ForgeBox.io and placed it in the `vendor/wheels` directory, then configured the application name and reload password, and started a Lucee server on a random port.
88
+
The server runs on a local port (shown in the terminal output). Your application code is served from the `public/` directory, and code changes are reflected immediately — no restart needed.
71
89
72
-
{% hint style="info" %}
73
-
**A Word About Command Aliases**
90
+
To stop the server:
91
+
92
+
```bash
93
+
wheels stop
94
+
```
95
+
96
+
## Build a Feature
97
+
98
+
Let's create a simple blog post resource to see the full development workflow.
99
+
100
+
### 1. Generate a Scaffold
101
+
102
+
A scaffold creates the model, controller, views, migration, and tests all at once:
103
+
104
+
```bash
105
+
wheels generate scaffold Post title:string body:text published:boolean
106
+
```
107
+
108
+
### 2. Run the Migration
109
+
110
+
Apply the database migration to create the `posts` table:
111
+
112
+
```bash
113
+
wheels migrate latest
114
+
```
115
+
116
+
### 3. Add Routes
117
+
118
+
Open `config/routes.cfm` and add a resource route for posts. Place it before the wildcard route:
119
+
120
+
```cfm
121
+
mapper()
122
+
.resources("posts")
123
+
.wildcard()
124
+
.root(to="wheels##congratulations", method="get")
125
+
.end();
126
+
```
127
+
128
+
### 4. Reload and Visit
129
+
130
+
Reload the application to pick up the new routes:
131
+
132
+
```bash
133
+
wheels reload
134
+
```
135
+
136
+
Visit `http://localhost:<port>/posts` in your browser. You now have a working CRUD interface for blog posts — list, create, edit, and delete — all generated from a single command.
137
+
138
+
## Run Tests
139
+
140
+
Wheels generates test files alongside your code. Run them with:
|`config/routes.cfm`| URL routing — maps URLs to controller actions |
184
+
|`lucee.json`| Server port, JVM settings, Lucee mappings |
185
+
|`app/views/layout.cfm`| HTML layout wrapping all views |
186
+
187
+
## Configure a Database
74
188
75
-
CommandBox commands have the capability to be called by multiple names or aliases. The command above `wheels generate app` can also be initiated by typing `wheels g app`. In fact `g` is an alias for `generate` so wherever you see a command in the CLI documentation that has `generate` in it you can substitute `g` instead.
189
+
New applications come with an embedded H2 database that works out of the box. When you're ready to use MySQL, PostgreSQL, or another database:
76
190
77
-
In addition to shortening `generate` to `g`, aliases can completely change the name space as well. A command that you haven't seen yet is the `wheels generate app-wizard` command. This command guides the user through a series of menu options, building up all the parameters needed to customize the start of a new Wheels project. You're likely to use the wizard when starting a new Wheels application so it's good to become familiar with it.
191
+
1.**Set the datasource name** in `config/settings.cfm`:
78
192
79
-
This command has the normal alias referenced above at `wheels g app-wizard` but it also has an additional alias at `wheels new` which is the command more prevalent in the Rails community. So the three commands `wheels generate app-wizard`, `wheels g app-wizard`, and `wheels new` all call the same functionality which guides the user though a set of menus, collecting details on how to configure the desired app. Once all the parameters have been gathered, this command actually calls the `wheels generate app` command to create the actual Wheels application.
193
+
```cfm
194
+
set(dataSourceName="myapp_dev");
195
+
```
196
+
197
+
2.**Define the datasource connection** in `config/app.cfm`:
See the [Hello Database](introduction/readme/beginner-tutorial-hello-database.md) tutorial for a complete walkthrough of database interaction.
215
+
216
+
## Set Up AI-Assisted Development
217
+
218
+
LuCLI includes a built-in MCP server that integrates with AI editors like Claude Code, Cursor, and VS Code Copilot. This gives your AI assistant direct access to Wheels commands — generating code, running migrations, and running tests.
219
+
220
+
Start the MCP server:
221
+
222
+
```bash
223
+
lucli mcp wheels
224
+
```
225
+
226
+
For Claude Code, add this to your project's `.mcp.json`:
227
+
228
+
```json
229
+
{
230
+
"mcpServers": {
231
+
"wheels": {
232
+
"command": "lucli",
233
+
"args": ["mcp", "wheels"]
234
+
}
235
+
}
236
+
}
237
+
```
238
+
239
+
Once configured, your AI editor can use tools like `wheels_generate`, `wheels_migrate`, and `wheels_test` directly.
240
+
241
+
## Deploy to Production
242
+
243
+
When you're ready to deploy your Wheels application:
244
+
245
+
1.**Set the environment** to production in `config/environment.cfm` or via your server's configuration.
246
+
247
+
2.**Configure a production datasource** in `config/production/settings.cfm`:
248
+
249
+
```cfm
250
+
set(dataSourceName="myapp_production");
251
+
set(reloadPassword="a-strong-secret");
252
+
```
253
+
254
+
3.**Run migrations** on the production database:
255
+
256
+
```bash
257
+
wheels migrate latest
258
+
```
259
+
260
+
4.**Deploy your code** to a Lucee or Adobe ColdFusion server. Wheels runs on any CFML engine behind Apache, Nginx, IIS, or Tomcat. See the [Requirements](introduction/requirements.md) page for supported engines and databases.
261
+
262
+
{% hint style="info" %}
263
+
**Docker Deployment**
264
+
265
+
For containerized deployments, use `wheels docker init` to generate a `Dockerfile` and `docker-compose.yml` tailored to your CFML engine and database. See [Running Local Development Servers](introduction/readme/running-local-development-servers.md) for details.
80
266
{% endhint %}
81
267
82
-
This **Getting Started** guide has taken you from the very beginning and gotten you to the point where you can go into any empty directory on your local development machine and start a Wheels project by issuing a couple of CLI commands. In later guides we'll explore these options further and see what else the CLI can do for us.
268
+
## Next Steps
269
+
270
+
You now have a working Wheels application with a database-backed feature, tests, and a development server. Here's where to go next:
271
+
272
+
-**[Hello World Tutorial](introduction/readme/beginner-tutorial-hello-world.md)** — Build a controller and view from scratch to understand the MVC fundamentals
273
+
-**[Hello Database Tutorial](introduction/readme/beginner-tutorial-hello-database.md)** — Create a full CRUD application with forms, validations, and database interaction
274
+
-**[Conventions](working-with-wheels/conventions.md)** — Learn the naming conventions that make Wheels productive
275
+
-**[Routing](handling-requests-with-controllers/routing.md)** — Define URL patterns for your application
276
+
-**[CLI Command Reference](command-line-tools/commands/README.md)** — Explore all available commands
277
+
278
+
## Alternative Setup with CommandBox
279
+
280
+
[CommandBox](https://www.ortussolutions.com/products/commandbox) is a full-featured CFML toolbox that also works with Wheels. It offers additional capabilities like ForgeBox package management, an interactive REPL, and support for both Lucee and Adobe ColdFusion servers.
281
+
282
+
### Install CommandBox
283
+
284
+
```bash
285
+
# macOS
286
+
brew install commandbox
287
+
288
+
# Windows
289
+
choco install commandbox
290
+
```
291
+
292
+
### Install the Wheels CLI Module
293
+
294
+
```bash
295
+
box install wheels-cli
296
+
```
297
+
298
+
### Create and Start an Application
299
+
300
+
```bash
301
+
wheels new myApp
302
+
cd myApp
303
+
box server start
304
+
```
305
+
306
+
### Command Differences
307
+
308
+
The daily workflow is nearly identical. The key differences:
309
+
310
+
| Task | LuCLI | CommandBox |
311
+
|------|-------|-----------|
312
+
| Start server |`wheels start`|`box server start`|
313
+
| Run migrations |`wheels migrate latest`|`wheels dbmigrate latest`|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments