INTRODUCTION

Getting Started

Running Local Development Servers

Beginner Tutorial: Hello World

Beginner Tutorial: Hello Database

Tutorial: Wheels, AJAX, and You

Boxlang Support

Frameworks and Wheels

Requirements

Manual Installation

Upgrading

Screencasts

Command Line Tools

CLI Overview

Quick Start Guide

Command Reference

Core Commands

wheels init

wheels info

wheels reload

wheels deps

wheels destroy

Code Generation

wheels generate app

wheels generate app-wizard

wheels generate controller

wheels generate model

wheels generate view

wheels generate property

wheels generate route

wheels generate test

wheels generate snippets

wheels generate scaffold

Database Commands

Database Operations

wheels db create

wheels db drop

Migration Commands

wheels dbmigrate info

wheels dbmigrate latest

wheels dbmigrate up

wheels dbmigrate down

wheels dbmigrate reset

wheels dbmigrate exec

wheels dbmigrate create blank

wheels dbmigrate create table

wheels dbmigrate create column

wheels dbmigrate remove table

Testing Commands

wheels test run

wheels advanced testing

Environment Management

wheels env setup

wheels env list

wheels env merge

wheels env set

wheels env show

wheels env switch

wheels env validate

Code Analysis

wheels analyze code

wheels analyze performance

wheels analyze security

Config

wheels config check

wheels config diff

wheels config dump

Docker Commands

wheels docker init

wheels docker deploy

Get Commands

wheels get environment

wheels get settings

Documentation

wheels docs generate

wheels docs serve

Plugins

wheels plugin install

wheels plugin list

Asset Management

asset management commands

CLI Development Guides

Configuration Management

Creating Commands

Service Architecture

Migrations Guide

Testing Guide

Working with Wheels

Conventions

Configuration and Defaults

Directory Structure

Switching Environments

Testing Your Application

Using the Test Environment

Contributing to Wheels

Contributing to Wheels VS Code Extension

Contributing to Wheels Windows Installer

Submitting Pull Requests

Documenting your Code

Handling Requests with Controllers

Request Handling

Rendering Content

Redirecting Users

Sending Files

Sending Email

Responding with Multiple Formats

Using the Flash

Using Filters

Verification

Event Handlers

Routing

URL Rewriting

Apache

IIS

Tomcat

Nginx

Obfuscating URLs

Caching

Nesting Controllers

CORS Requests

Displaying Views to Users

Pages

Partials

Linking Pages

Layouts

Form Helpers and Showing Errors

Displaying Links for Pagination

Date, Media, and Text Helpers

Creating Custom View Helpers

Localization

Database Interaction Through Models

Object Relational Mapping

Creating Records

Reading Records

Updating Records

Deleting Records

Column Statistics

Dynamic Finders

Getting Paginated Data

Associations

Nested Properties

Object Validation

Object Callbacks

Calculated Properties

Transactions

Dirty Records

Soft Delete

Automatic Time Stamps

Database Migrations

Migrations in Production

Using Multiple Data Sources

Project Documentation

Overview

External Links

Source Code

Issue Tracker

Sponsor Us

Community

Plugins

Installing and Using Plugins

Developing Plugins

Publishing Plugins

Ask or search...

Ctrl K

Quick Start Guide

Get up and running with Wheels CLI in minutes.

Prerequisites

CommandBox 5.0+
Java 8+
Database (MySQL, PostgreSQL, SQL Server, or H2)

Installation

Install CommandBox

# macOS/Linux
curl -fsSl https://downloads.ortussolutions.com/debs/gpg | sudo apt-key add -
echo "deb https://downloads.ortussolutions.com/debs/noarch /" | sudo tee -a /etc/apt/sources.list.d/commandbox.list
sudo apt-get update && sudo apt-get install commandbox

# Windows (PowerShell as Admin)
iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
choco install commandbox

Install Wheels CLI

box install wheels-cli

Creating Your First Application

1. Generate Application

wheels new blog
cd blog

This creates a new Wheels application with:

Complete directory structure
Configuration files
Sample code

2. Configure Database

Edit /config/settings.cfm:

<cfset set(dataSourceName="blog_development")>

Or use H2 embedded database:

wheels new blog --setupH2

Create the database: (Coming Soon)

# If using external database (MySQL, PostgreSQL, etc.)
wheels db create

3. Start Server

box server start

Visit http://localhost:3000

Creating Your First Feature

Let's create a blog post feature:

1. Generate Scaffold

wheels generate scaffold name=post properties=title:string,content:text,published:boolean

This generates:

Model with validations
Controller with CRUD actions
Views for all actions
Database migration
Test files

2. Run Migration

wheels dbmigrate latest

3. Add Routes

Edit /config/routes.cfm:

<cfscript>
    // Add this line
    resources("posts");
</cfscript>

4. Reload Application

wheels reload

5. Test Your Feature

Visit http://localhost:3000/posts

You now have a fully functional blog post management system!

Development Workflow

File Watching

In a new terminal:

wheels watch

Now changes to .cfc and .cfm files trigger automatic reloads.

Running Tests

# Run all tests
wheels test run

# Watch mode
wheels test run --watch

# Specific tests
wheels test run tests/models/PostTest.cfc

Adding Relationships

Let's add comments to posts:

# Generate comment model
wheels generate model comment --properties="author:string,content:text,postId:integer" \
  --belongs-to="post"

# Update post model
wheels generate property post comments --has-many

# Generate comments controller
wheels generate controller comments --rest

# Run migration
wheels dbmigrate latest

Common Tasks

Adding Authentication

# Generate user model
wheels scaffold name=user properties=email:string,password:string,admin:boolean

# Generate session controller
wheels generate controller sessions new,create,delete

# Run migrations
wheels dbmigrate latest

Adding API Endpoints

# Generate API resource
wheels generate api-resource product --properties="name:string,price:decimal"

# Or convert existing to API
wheels generate controller api/posts --api

Working with Views

# Generate specific views
wheels generate view posts featured
wheels generate view users profile

# Add layouts
echo '<cfoutput><!DOCTYPE html>...</cfoutput>' > views/layout.cfm

Best Practices

1. Use Migrations

Always use migrations for database changes:

# Create tables
wheels dbmigrate create table products

# Add columns
wheels dbmigrate create column products featured

# Create indexes
wheels dbmigrate create blank add_index_to_products

2. Write Tests

Generate tests for your code:

# After creating a model
wheels generate test model post

# After creating a controller
wheels generate test controller posts

3. Use Environment Configuration

# Development
wheels reload development

# Testing
wheels reload testing

# Production
wheels reload production

4. Version Control

git init
git add .
git commit -m "Initial Wheels application"

Add to .gitignore:

/db/sql/
/logs/
/temp/
.env

Debugging

Check Logs

tail -f logs/wheels.log

Enable Debug Mode

In /config/settings.cfm:

<cfset set(showDebugInformation=true)>

Common Issues

Port already in use:

box server start port=3001

Database connection failed:

# Check datasource
box server info
box server show

Migration failed:

# Check status
wheels db status

# Run specific migration
wheels dbmigrate exec 20240120000000

# Or rollback and try again
wheels db rollback

Need to reset database:

# Complete reset (careful - destroys all data!)
wheels db reset --force

Access database directly:

# CLI shell
wheels db shell

# Web console (H2 only)
wheels db shell --web

Next Steps

Read the Guides:
Explore Commands:
- wheels --help
- wheels generate --help
- wheels dbmigrate --help
Join the Community:
- Wheels Documentation
- GitHub Discussions
- CFML Slack #wheels channel

Example: Complete Blog Application

Here's a complete blog setup:

# Create application
wheels new myblog --setupH2
cd myblog

# Generate blog structure
wheels scaffold post title:string,slug:string,content:text,publishedAt:datetime
wheels scaffold author name:string,email:string,bio:text
wheels generate model comment author:string,email:string,content:text,postId:integer \
  --belongs-to=post

# Update associations
wheels generate property post authorId:integer --belongs-to=author
wheels generate property post comments --has-many
wheels generate property author posts --has-many

# Add routes
echo '<cfset resources("posts")>' >> config/routes.cfm
echo '<cfset resources("authors")>' >> config/routes.cfm

# Setup and seed database
wheels db setup --seed-count=10

# Start development
wheels server start
wheels watch

# Visit http://localhost:3000/posts

You now have a working blog with posts, authors, and comments!