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:
# 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 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:
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!
Last updated
Was this helpful?