ColdBox CLI
The ColdBox CLI is a powerful command-line interface tool that helps you create, manage, and scaffold ColdBox applications and components with ease.
Welcome to the ColdBox CLI - your ultimate command-line companion for rapid ColdBox development! 🚀 This powerful tool streamlines the creation, management, and scaffolding of ColdBox applications and components for both CFML and BoxLang projects.
🎯 BoxLang First: BoxLang is now the default language for all new applications, reflecting the modern direction of ColdBox development.
📦 CLI Versions & Compatibility
The CLI follows semantic versioning aligned with ColdBox major releases:
ColdBox 8
@8
✅ Current
box install coldbox-cli@8
ColdBox 6
@6
🔶 Legacy
box install coldbox-cli@6
💡 Pro Tip: Always use the CLI version that matches your ColdBox framework version for the best compatibility and latest features.
⚡ Quick Installation
Get started in seconds with CommandBox:
# Install the latest ColdBox CLI (v8)
box install coldbox-cli
# Get help anytime
coldbox --help🔗 Source Code: Explore the CLI on GitHub at coldbox/coldbox-cli - contributions welcome!
🎯 Getting Started
The ColdBox CLI supercharges your development workflow with intelligent scaffolding and modern development tools. Whether you're building BoxLang or CFML applications, the CLI has you covered!
📚 Help is Always Available: Every command supports the
--helpflag for detailed usage information.
🥊 Application Creation
Create stunning ColdBox applications from professionally crafted templates. BoxLang leads the way as the default language for modern development:
# 🎯 Quick Start - Create a BoxLang app (default behavior)
coldbox create app myAwesomeApp
# 🔥 Explicitly choose BoxLang (same as above)
coldbox create app myAwesomeApp --boxlang
# 📜 Create a traditional CFML app
coldbox create app myCFMLApp --cfml🏗️ Application Templates & Features
Choose from various templates and enhance with powerful features:
# 📋 Modern Templates (Recommended)
coldbox create app myApp skeleton=boxlang   # Pure BoxLang template
coldbox create app myApp skeleton=modern     # Contemporary architecture for CFML or BoxLang
# 🔧 Flat Templates (CFML)
coldbox create app myApp skeleton=rest      # REST API focused
coldbox create app myApp skeleton=flat      # Traditional flat structure
coldbox create app myApp skeleton=supersimple  # Minimal setup
coldbox create app myApp skeleton=vite  # Vite
# ⚡ Power Features
coldbox create app myApp --migrations       # 🗃️ Database migrations
coldbox create app myApp --docker          # 🐳 Container ready
coldbox create app myApp --vite           # 🎨 Modern frontend assets
coldbox create app myApp --rest           # 🌐 REST API configuration
# 🎪 Combine Multiple Features
coldbox create app myFullStackApp --migrations --docker --vite --rest🧙♂️ Interactive App Wizard - Perfect for Beginners!
New to ColdBox? The App Wizard is your friendly guide to creating the perfect application setup:
# Launch the interactive wizard
coldbox create app-wizardThe wizard walks you through every decision with helpful prompts:
📁 Location
Create in current folder or new directory?
Project organization
🔥 Language
BoxLang (default) or CFML?
Development preference
🎯 Type
API/REST service or full web app?
Architecture choice
🎨 Frontend
Include Vite for modern UI?
Asset management
🐳 Environment
Docker containerization?
Deployment strategy
🗃️ Database
Need migration support?
Data management
Example Wizard Session:
🧙♂️ Welcome to the ColdBox App Wizard!
📁 Are you currently inside the "myapp" folder? [y/n]: n
🔥 Is this a BoxLang project? [y/n]: y
🎯 Are you creating an API? [y/n]: n
🎨 Would you like to configure Vite as your Front End UI pipeline? [y/n]: y
🐳 Would you like to setup a Docker environment? [y/n]: y
🗃️ Are you going to require Database Migrations? [y/n]: y
✨ Perfect! Creating your customized ColdBox application...💡 Pro Tip: The wizard is perfect for exploring all available options and learning about ColdBox features as you create your app!
📋 Application Templates - Choose Your Foundation
Select from professionally crafted templates or bring your own via ForgeBox ID, GitHub repo, local path, ZIP file, or URL. Our modern templates prioritize BoxLang for cutting-edge development:
🥊 BoxLang Templates (Recommended for Modern Development)
These can be used for BoxLang PRIME projects or CFML projects with the bx-cfml-compat module for compatibility.
boxlang ⭐
Default - Modern ColdBox with latest BoxLang features
New projects, modern architecture
modern
Contemporary app supporting BoxLang + CFML
Hybrid projects, gradual migration
📜 FLAT CFML Templates (Traditional Development)
Can also be used for BoxLang projects but using the bx-cfml-compat modules to ensure compatibility.
flat
Classic flat-structure ColdBox app
Traditional CFML projects
rest
BoxLang-optimized REST API template
Microservices, API development
rest-hmvc
RESTful app with HMVC architecture
Complex API systems
supersimple
Bare-bones minimal setup
Learning, prototyping
vite
CFML app with Vite integration (legacy)
Legacy frontend modernization
🚀 Enhanced Template Features
Modern templates (boxlang, modern) unlock powerful development features through simple flags:
--vite 🎨
Modern frontend with hot reload & optimized builds
Interactive UIs, SPAs
--rest 🌐
REST API configuration with OpenAPI docs
Microservices, APIs
--docker 🐳
Complete containerization setup
Cloud deployment, consistency
--migrations 🗃️
Database migration system
Data-driven apps
Power Combinations:
# 🎯 Full-Stack Modern App
coldbox create app myApp skeleton=modern --vite --migrations --docker
# 🌐 Production-Ready API
coldbox create app myAPI skeleton=rest --docker --migrations
# 🔥 BoxLang Powerhouse
coldbox create app myApp --vite --rest --docker --migrations⚡ Vite Integration - Modern Frontend Made Easy
Transform your frontend development with Vite's lightning-fast build system and hot module replacement:
# 🔥 Create app with Vite power
coldbox create app myApp --vite
# 🎯 Works with modern templates
coldbox create app myApp skeleton=modern --vite🎁 What You Get Out of the Box:
🔧 Pre-configured Setup
vite.config.mjs ready to go
Zero configuration needed
🔥 Hot Module Replacement
Instant updates without refresh
Ultra-fast development
📦 Optimized Builds
Code splitting & tree shaking
Production-ready performance
🎨 Asset Processing
CSS, SCSS, JS, TS support
Modern toolchain
🔗 Dev Server + Proxy
Seamless ColdBox integration
Unified development experience
🚀 Development Workflow:
# Start development with hot reloading
npm run dev            # ⚡ Lightning fast updates
# Build for production
npm run build          # 📦 Optimized & minified
# Preview production build locally
npm run preview        # 🔍 Test before deploy💡 Pro Tip: Vite's dev server automatically proxies to your ColdBox application, giving you the best of both worlds!
🐳 Docker Integration - Deploy Anywhere, Run Everywhere
Containerize your ColdBox applications for consistent development and bulletproof deployments:
# 🐳 Add Docker superpowers
coldbox create app myApp --docker
# 🚀 Ultimate combo - Docker + everything
coldbox create app myApp --docker --vite --migrations --rest🎁 Complete Container Solution:
📦 Multi-stage Dockerfile
Optimized for ColdBox apps
Minimal production images
🔧 docker-compose.yml
Complete dev environment
One-command setup
🗃️ Database Services
PostgreSQL/MySQL ready
Consistent data layer
⚡ Redis Caching
High-performance caching
Speed & scalability
🌐 Environment Config
Secure variable management
Production-ready security
💚 Health Checks
Built-in monitoring
Reliable deployments
🚀 Container Commands:
# Launch your entire development environment
docker-compose up -d           # 🚀 Start all services
# Monitor your application
docker-compose logs -f app     # 👀 Watch real-time logs
# Clean shutdown
docker-compose down           # 🛑 Stop all services gracefully
# Fresh rebuild
docker-compose up --build     # 🔄 Rebuild & restart🎯 Production Ready: The Docker setup includes production optimizations like multi-stage builds, security best practices, and health monitoring!
🎯 Handlers (Controllers) - Your Application Logic
Generate powerful MVC controllers with intelligent scaffolding for actions, views, and tests:
# 🎯 Basic handler for common tasks
coldbox create handler UserController
# 🎪 Handler with specific actions
coldbox create handler Users index,show,edit,delete,create
# 🌐 RESTful API handler
coldbox create handler api/Users --rest
# 🔄 Full CRUD resourceful handler
coldbox create handler Photos --resource
# 🎨 Complete package with views and tests
coldbox create handler Users --views --integrationTests🎁 Handler Generation Options:
--rest
RESTful endpoints (GET, POST, PUT, DELETE)
API development
--resource
Full CRUD operations
Data management
--views
Corresponding view templates
Full-stack apps
--integrationTests
Test files for actions
Quality assurance
💡 Smart Generation: The CLI creates handlers in the correct directory structure and generates appropriate code for your project language (BoxLang/CFML)!
📊 Models & Services - Your Business Logic Powerhouse
Create robust domain models and business services that form the backbone of your application:
# 🎯 Simple domain model
coldbox create model User
# 🏗️ Rich model with properties and accessors
coldbox create model User properties=firstName,lastName,email --accessors
# 🗃️ Model with database migration
coldbox create model Product --migration
# 🔧 Model with accompanying service
coldbox create model User --service
# 🎪 The works - model, service, handler, migration, seeder
coldbox create model Customer --all
# ⚙️ Standalone business service
coldbox create service PaymentService🎁 Model Generation Features:
--accessors
Getter/setter methods
Clean property access
--migration
Database table creation
Data persistence
--service
Business logic layer
Complex operations
--all
Complete MVC stack
Full feature development
💡 Smart Property Generation:
# Creates firstName, lastName, email properties with getters/setters
coldbox create model User properties=firstName,lastName,email --accessors🚀 Pro Tip: Use
--allwhen you need a complete feature with model, service, handler, database migration, and test seeders!
🎨 Views & Layouts - Beautiful User Interfaces
Craft stunning user interfaces with intelligent view and layout generation:
# 🎨 Create a view template
coldbox create view users/index
# 🔧 View with helper functions
coldbox create view users/profile --helper
# 📝 View with initial content
coldbox create view welcome content="<h1>Welcome to Our App!</h1>"
# 🖼️ Create layout template
coldbox create layout main
# 🎯 Layout with view rendering
coldbox create layout admin content="<cfoutput>#renderView()#</cfoutput>"🎁 View Generation Options:
Views
Page content & UI components
Keep focused & reusable
Layouts
Page structure & common elements
Master templates
Helpers
View-specific utility functions
Clean separation of concerns
💡 Smart Content Generation:
- Views are placed in the correct directory structure 
- Layouts include proper view rendering calls 
- Helper files provide utility functions for complex views 
- All generated code follows your project's language (BoxLang/CFML) 
🎨 Design Tip: Use layouts for common page structure (header, navigation, footer) and views for specific page content!
🔧 Resources & CRUD - Complete Feature Development
Generate complete, production-ready resourceful components with full CRUD operations:
# 🎯 Single resource (handler, model, views, routes)
coldbox create resource Photos
# 🎪 Multiple resources at once
coldbox create resource Photos,Users,Categories
# 🎨 Custom handler name for better organization
coldbox create resource photos PhotoGalleryController
# 🧪 Production-ready with tests and migrations
coldbox create resource Users --tests --migration🎁 What Gets Generated:
🎯 Handler
CRUD actions (index, show, create, edit, delete)
handlers/Photos.cfc
📊 Model
Data model with validation
models/Photo.cfc
🎨 Views
Complete UI for all actions
views/photos/*.cfm
🛣️ Routes
RESTful URL patterns
Added to config/Router.cfc
🧪 Tests
Unit & integration tests (optional)
tests/specs/
🗃️ Migration
Database table creation (optional)
resources/database/migrations/
🚀 Generated CRUD Actions:
# Your Photos resource creates these endpoints automatically:
GET    /photos          # index()   - List all photos
GET    /photos/new      # new()     - Show create form
POST   /photos          # create()  - Save new photo
GET    /photos/:id      # show()    - Display photo
GET    /photos/:id/edit # edit()    - Show edit form
PUT    /photos/:id      # update()  - Save changes
DELETE /photos/:id      # delete()  - Remove photo⚡ Instant Productivity: Resources give you a complete feature with working CRUD operations in seconds!
📦 Modules - Reusable Application Components
Create powerful, self-contained modules that can be shared across applications or published to ForgeBox:
# 🎯 Basic module structure
coldbox create module UserManagement
# 🎪 Full-featured module with all components
coldbox create module BlogEngine --models --handlers --views🎁 Module Architecture:
Modules are mini-applications within your ColdBox app, complete with their own:
- 📁 Directory Structure - Organized, self-contained file layout 
- ⚙️ ModuleConfig - Independent configuration and settings 
- 🛣️ Routing - Module-specific URL patterns 
- 📦 Dependencies - Isolated dependency management 
- 🔧 Models & Handlers - Complete MVC architecture (optional) 
- 🎨 Views & Layouts - Independent UI components (optional) 
🚀 Modular Power: Modules enable microservice architecture, code reuse, and team collaboration on large applications!
🧪 Testing - Quality Assurance Made Easy
Generate comprehensive test suites to ensure your application works flawlessly:
# 🎯 Unit tests for business logic
coldbox create unit models.UserServiceTest
# 📋 BDD specs for behavior testing
coldbox create bdd UserAuthenticationSpecs
# 🌐 Integration tests for full workflows
coldbox create integration-test handlers.UsersTest
# 📊 Model-specific testing
coldbox create model-test User
# 🎪 Interceptor testing with action coverage
coldbox create interceptor-test Security --actions=preProcess,postProcess🎁 Testing Types & Their Purpose:
🎯 Unit
Individual methods & functions
Business logic, utilities
📋 BDD
Behavior & requirements
User stories, acceptance criteria
🌐 Integration
Component interactions
Workflows, API endpoints
📊 Model
Data models & validation
Domain logic, persistence
🎪 Interceptor
AOP & cross-cutting concerns
Security, logging, caching
💡 Testing Best Practices:
- Fast Feedback - Unit tests run quickly for immediate validation 
- Behavior Focus - BDD tests document how features should work 
- Real Scenarios - Integration tests verify complete user workflows 
- Data Integrity - Model tests ensure business rules are enforced 
🚀 Quality First: Well-tested applications deploy with confidence and maintain themselves over time!
🗄️ ORM & Database
Work with ORM entities and database operations:
# ORM Entity
coldbox create orm-entity User table=users
# ORM Service
coldbox create orm-service UserService entity=User
# Virtual Entity Service
coldbox create orm-virtual-service UserService
# ORM Event Handler
coldbox create orm-event-handler
# CRUD operations
coldbox create orm-crud User🔗 Interceptors
Create AOP interceptors:
# Basic interceptor
coldbox create interceptor Security
# Interceptor with specific interception points
coldbox create interceptor Logger points=preProcess,postProcess
# With tests
coldbox create interceptor Security --tests🔄 Development Workflow
Manage your development environment:
# Reinitialize ColdBox framework
coldbox reinit
# Auto-reinit on file changes
coldbox watch-reinit
# Open documentation
coldbox docs
coldbox docs search="event handlers"
# Open API documentation
coldbox apidocs🎛️ Global Options - Command Superpowers
Enhance any CLI command with these powerful options for a customized experience:
🌟 Universal Command Options
--force ⚡
Overwrite existing files without prompting
coldbox create handler Users --force
--open 📂
Auto-open generated files in your editor
coldbox create model User --open
--help ❓
Show detailed command help
coldbox create app --help
🏗️ Application Creation Flags
--migrations 🗃️
Database migration system
Data-driven applications
--docker 🐳
Complete containerization
Cloud deployments, consistency
--vite ⚡
Modern frontend asset pipeline
Interactive UIs, SPAs
--rest 🌐
REST API configuration
Microservices, API development
🔥 Language Control
The CLI automatically detects your project language but you can override when needed:
Default 🎯
BoxLang for new apps, auto-detect for existing
Most scenarios
--boxlang 🥊
Force BoxLang generation
Override detection
--cfml 📜
Force CFML generation
Legacy projects, specific requirements
🎪 Power Combinations:
# 🚀 Create a modern app with all the bells and whistles
coldbox create app myApp --vite --docker --migrations --rest --open
# 🔧 Force CFML for a legacy project with immediate editing
coldbox create handler Users --cfml --force --open
# 📋 Get detailed help for any command
coldbox create resource --help💡 BoxLang Support
The CLI automatically detects BoxLang projects and generates appropriate code. You can also force BoxLang mode using the --boxlang flag.
🔍 Automatic Detection
The CLI detects BoxLang projects using three methods (in order of precedence):
- Server Engine Detection: Running on a BoxLang server 
- TestBox Runner Setting: When - testbox.runneris set to- "boxlang"in- box.json
- Language Property: When - languageis set to- "boxlang"in- box.json
⚙️ Configuration Examples
Method 1: Language Property (Recommended)
{
    "name": "My BoxLang App",
    "language": "boxlang",
    "testbox": {
        "runner": "/tests/runner.bxm"
    }
}Method 2: TestBox Runner Setting
{
    "name": "My App",
    "testbox": {
        "runner": "boxlang"
    }
}🚀 Usage Examples
# Default behavior (creates BoxLang code)
coldbox create handler users
coldbox create model User
# Explicit BoxLang generation (usually not needed)
coldbox create handler users --boxlang
# Force CFML generation for legacy projects
coldbox create handler users --cfml
coldbox create app myApp --cfml📝 Generated Code Differences
When BoxLang mode is detected or forced:
- Uses - .bxfile extensions instead of- .cfc
- Generates - classsyntax instead of- component
- Uses BoxLang-specific template variants 
- Creates BoxLang test files ( - .bxmextensions)
🤖 AI Coding Assistance
The CLI now includes Copilot instructions to enhance AI-powered development workflows. These instructions help AI assistants understand ColdBox project structure and generate appropriate code:
Features
- Intelligent Code Generation: AI assistants can better understand ColdBox conventions and patterns 
- Template-Aware Suggestions: Context-aware code suggestions based on your project type 
- BoxLang & CFML Support: Appropriate suggestions for both language targets 
- Framework Integration: Deep understanding of ColdBox architecture and best practices 
Copilot Instructions
The CLI includes specialized instruction sets:
- Modern Apps: Instructions optimized for contemporary ColdBox applications 
- Legacy Projects: Support for traditional flat-structure applications 
- BoxLang Focus: Enhanced support for BoxLang-specific patterns 
- Framework Patterns: MVC, HMVC, and REST API architectural guidance 
These instructions are automatically included in modern application templates to provide the best AI coding experience out of the box.
📖 Getting Help - Never Get Stuck
The ColdBox CLI has your back with comprehensive help at every level:
🎯 Quick Help Commands
# 📋 See all available commands
coldbox help
# 🔍 Get detailed help for any command
coldbox create handler --help
coldbox create model --help
coldbox create app --help
# 📊 Check your CLI version
coldbox --version🆘 When You Need Help
🤔 What can I do?
coldbox help
Full command list
📋 How do I use this command?
coldbox create app --help
Detailed usage & examples
🐛 Something's not working
coldbox --version
Version info for troubleshooting
💡 Pro Help Tips
- Every command has - --help- never hesitate to use it!
- Help shows examples, options, and flags for each command 
- When reporting issues, always include your CLI version 
- The GitHub repository has extensive documentation and examples 
🎓 Learning Path: Start with
coldbox create app-wizardto explore all options interactively, then use specific commands as you become more comfortable!
Last updated
Was this helpful?
