Copyright Since 2005 ColdBox Platform by Luis Majano and Ortus Solutions, Corp
coldbox.org » boxlang.io » ortussolutions.com

This is the official ColdBox CLI for CommandBox. It is a collection of commands to help you work with ColdBox and its ecosystem for building, testing, and deploying BoxLang and CFML applications. It provides commands for scaffolding applications, creating tests, modules, models, views, and much more.

• Table of Contents
• License
• ColdBox CLI Versions
• Installation
• Usage
  • 📱 Application Creation
    • 🧙‍♂️ Interactive App Wizard
  • Application Templates
    • 🚀 cbGenesis — The Official ColdBox Starter
    • 🥊 BoxLang Templates (Recommended)
    • 📜 Legacy CFML Templates
    • 🚀 Template Features
    • ⚡ Vite Integration
    • 🐳 Docker Integration
  • 🎯 Handlers (Controllers)
  • 📊 Models & Services
  • 🎨 Views & Layouts
  • 🔧 Resources & CRUD
  • 📦 Modules
  • 🧪 Testing
  • 🗄️ ORM & Database
  • 🔗 Interceptors
  • 🔄 Development Workflow
  • 🎛️ Global Options
    • Application-Specific Flags
    • Language Generation Control
  • 💡 BoxLang Support
    • 🔍 Automatic Detection
    • ⚙️ Configuration Examples
      • Method 1: Language Property (Recommended)
      • Method 2: TestBox Runner Setting
  • 🗂️ App Layout Detection
    • Modern Layout (e.g. boxlang, cbgenesis templates)
    • Flat Layout (e.g. flat, legacy templates)
    • 🚀 Usage Examples
    • 📝 Generated Code Differences
  • 🤖 AI Integration
    • Setup & Management
    • AI Directory Structure
    • AI Agents
    • Guidelines
    • Skills
    • MCP Servers
    • AI Context Management
  • 📖 Getting Help
• Credits & Contributions
  • The Daily Bread

Apache License, Version 2.0.

The CLI matches the major version of ColdBox. Current version: 8

• If you are using ColdBox 8, use CLI @8 (recommended)
• If you are using ColdBox 7, use CLI @7.8.0 (recommended)

This versioning ensures you get the correct commands and features for your version of ColdBox.

Install the commands via CommandBox like so:

box install coldbox-cli

The ColdBox CLI provides powerful scaffolding and development tools for both CFML and BoxLang applications. All commands support the --help flag for detailed information.

Create new ColdBox applications from various templates. BoxLang is now the default language for new applications:

# Create a basic ColdBox app (BoxLang by default)
coldbox create app myApp
coldbox create app myApp --boxlang   # Force BoxLang (default)

# Create a CFML app explicitly
coldbox create app myApp --cfml

# Create with specific templates
coldbox create app myApp skeleton=tiered
coldbox create app myApp skeleton=rest
coldbox create app myApp skeleton=cbgenesis

# Create with additional features
coldbox create app myApp --migrations     # Database migrations support
coldbox create app myApp --docker         # Docker environment setup
coldbox create app myApp --vite          # Vite frontend asset building
coldbox create app myApp --rest          # REST API configuration

# Combine multiple features
coldbox create app myApp --migrations --docker --vite

# Interactive app wizard (recommended for beginners)
coldbox create app-wizard

The app-wizard command provides an interactive, step-by-step process for creating new applications. It's perfect for beginners or when you want to explore all available options:

coldbox create app-wizard

The wizard will guide you through:

1. Project Location: Whether to create in current directory or a new folder
2. Language Selection: Choose between BoxLang (default) or CFML
3. Project Type: API/REST service or full web application
4. Frontend Setup: Optional Vite integration for web applications
5. Environment: Optional Docker containerization
6. Database: Optional migrations support

Example Wizard Flow:

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

The CLI supports multiple application templates (skeletons), or you can use your own via any FORGEBOX ID, GitHub repo, local path, zip or URL. BoxLang templates are now the primary focus for modern development:

cbGenesis is the official production-ready ColdBox starter for BoxLang: authentication, RBAC, and an admin panel ready to build on, so you spend day one building features instead of scaffolding auth.

coldbox create app myApp skeleton=cbgenesis

Batteries included — already wired up and tested, not a TODO in the README:

• 🔐 Auth & RBAC — Session auth via cbauth, Google SSO via cbSSO, passkeys, @secured handler annotations, and a resource:action permission model
• 🎟️ JWT & API Tokens — First-class token auth alongside sessions; issue, list, and revoke tokens from the user profile
• 🛡️ Security by Convention — CSRF token rotation, IP-based rate limiting on auth endpoints, BaseSecureHandler enforcement
• 🖥️ Admin Panel — Dashboard, users, roles & permissions, and audit log UI included
• 🗄️ ORM + Migrations — Hibernate ORM via cborm with BaseEntity/BaseService conventions, cfmigrations, and qb
• 🎨 Alpine.js + Bootstrap 5 UI — Server-rendered BXM views with Alpine components, compiled by Vite with hot module reload
• ✅ A Real Test Suite — TestBox unit specs for every entity and service, plus integration specs over real HTTP
• 🐳 Production Ready — Docker support, a go-live checklist, and a choice of CommandBox or the BoxLang MiniServer

Requirements: BoxLang 1.16+, Java 21+, Node 18+. Migrations, Docker, and Vite are already configured — no feature flags needed. Docs: cbgenesis.coldbox.org · GitHub: coldbox-templates/cbGenesis

• boxlang (default) - A modern ColdBox app using BoxLang as the primary language with latest features
• desktop - A BoxLang desktop application template
• tiered - A security-first template supporting both BoxLang and CFML with /app outside the webroot
• rest - A ColdBox REST API template optimized for BoxLang development
• cbgenesis - ⭐ The official production-ready starter: auth, RBAC, admin panel, ORM + migrations, Vite UI, and a real test suite (featured above)

• flat - A classic ColdBox app with a flat structure for traditional CFML development
• rest-hmvc - A RESTful ColdBox app using HMVC architecture
• supersimple - A bare-bones template for minimal setups
• vite - A ColdBox app integrated with Vite for frontend development (legacy)

Modern templates (boxlang, tiered) support additional features via flags:

• --vite - Integrates Vite for modern frontend asset building and hot reloading
• --rest - Configures the application as a REST API service
• --docker - Includes Docker configuration for containerized development
• --migrations - Sets up database migrations support

The CLI now supports Vite integration for modern frontend development with hot module replacement and optimized builds:

# Create app with Vite support
coldbox create app myApp --vite

# Available for BoxLang and Tiered templates
coldbox create app myApp skeleton=tiered --vite

Vite Features Included:

• Pre-configured vite.config.mjs with ColdBox/BoxLang integration
• Hot module replacement (HMR) for development
• Optimized production builds with code splitting
• Asset preprocessing for CSS, SCSS, JavaScript, and TypeScript
• Development server with proxy configuration
• Build scripts in package.json

Development Workflow:

# Start development server with hot reloading
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

The CLI provides Docker integration to containerize your ColdBox applications for consistent development and deployment environments:

# Create app with Docker support
coldbox create app myApp --docker

# Combine with other features
coldbox create app myApp --docker --vite --migrations

Docker Features Included:

• Multi-stage Dockerfile optimized for ColdBox applications
• docker-compose.yml for local development with services
• Database service configuration (PostgreSQL/MySQL)
• Redis caching service setup
• Environment variable configuration
• Production-ready container optimization
• Health checks and monitoring setup

Docker Commands:

# Build and start development environment
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Rebuild containers
docker-compose up --build

Generate MVC handlers with actions and optional views:

# Basic handler
coldbox create handler myHandler

# Handler with specific actions
coldbox create handler users index,show,edit,delete

# REST handler
coldbox create handler api/users --rest

# Resourceful handler (full CRUD)
coldbox create handler photos --resource

# Generate with views and tests
coldbox create handler users --views --integrationTests

Create domain models and business services:

# Basic model
coldbox create model User

# Model with properties and accessors
coldbox create model User properties=fname,lname,email --accessors

# Model with migration
coldbox create model User --migration

# Model with service
coldbox create model User --service

# Model with everything (service, handler, migration, seeder)
coldbox create model User --all

# Standalone service
coldbox create service UserService

Generate view templates and layouts:

# Create a view
coldbox create view users/index

# View with helper file
coldbox create view users/show --helper

# View with content
coldbox create view welcome content="<h1>Welcome!</h1>"

# Create layout
coldbox create layout main

# Layout with content
coldbox create layout admin content="<cfoutput>#view()#</cfoutput>"

Generate complete resourceful components:

# Single resource (handler, model, views, routes)
coldbox create resource photos

# Multiple resources
coldbox create resource photos,users,categories

# Custom handler name
coldbox create resource photos PhotoGallery

# With specific features
coldbox create resource users --tests --migration

Create reusable ColdBox modules:

# Create module
coldbox create module myModule

# Module with specific features
coldbox create module myModule --models --handlers --views

Generate various types of tests:

# Unit tests
coldbox create unit models.UserTest

# BDD specs
coldbox create bdd UserServiceTest

# Integration tests
coldbox create integration-test handlers.UsersTest

# Model tests
coldbox create model-test User

# Interceptor tests
coldbox create interceptor-test Security --actions=preProcess,postProcess

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

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

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

Most commands support these common options:

• --force - Overwrite existing files without prompting
• --open - Open generated files in your default editor
• --boxlang - Force BoxLang code generation (usually not needed as it's the default)
• --cfml - Force CFML code generation (overrides BoxLang default)
• --help - Show detailed help for any command

For application creation commands:

• --migrations - Include database migrations support
• --docker - Include Docker configuration and containerization
• --vite - Include Vite frontend asset building (modern/BoxLang templates)
• --rest - Configure as REST API application (BoxLang templates)

The CLI supports both automatic detection and manual override of the target language. BoxLang is now the default language for all new applications and generated code:

• Default: BoxLang code generation for new applications and components
• Automatic: Uses detection methods (server engine, box.json settings) for existing projects
• Force CFML: Use --cfml flag to generate CFML code regardless of detection
• Force BoxLang: Use --boxlang flag to explicitly generate BoxLang code (usually not needed as it's the default)

The CLI automatically detects BoxLang projects and generates appropriate code. You can also force BoxLang mode using the --boxlang flag.

The CLI detects BoxLang projects using three methods (in order of precedence):

1. Server Engine Detection: Running on a BoxLang server
2. TestBox Runner Setting: When testbox.runner is set to "boxlang" in box.json
3. Language Property: When language is set to "boxlang" in box.json

{
    "name": "My BoxLang App",
    "language": "boxlang",
    "testbox": {
        "runner": "/tests/runner.bxm"
    }
}

{
    "name": "My App",
    "testbox": {
        "runner": "boxlang"
    }
}

The CLI automatically detects whether your project uses a modern or flat layout and generates files in the correct location.

/app             - Application source code
  /config        - Configuration
  /handlers      - Event handlers
  /models        - Models & services
  /views         - View templates
  /layouts       - Layout wrappers
  /interceptors  - Interceptors
/public          - Web root
/modules         - ColdBox modules
/tests           - Test suites
/resources       - Migrations, seeders, etc.

/config          - Configuration
/handlers        - Event handlers
/models          - Models & services
/views           - View templates
/layouts         - Layout wrappers
/interceptors    - Interceptors
/modules         - ColdBox modules
/tests           - Test suites

When you run a generation command in a modern-layout project, the CLI automatically targets the correct directory:

# In a flat layout project → creates /handlers/users.cfc
# In a modern layout project → creates /app/handlers/users.cfc
coldbox create handler users

# In a flat layout project → creates /models/User.cfc
# In a modern layout project → creates /app/models/User.cfc
coldbox create model User

You can always override the target directory explicitly:

coldbox create model User directory=app/models

# 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

When BoxLang mode is detected or forced:

• Uses .bx file extensions instead of .cfc
• Generates class syntax instead of component
• Uses BoxLang-specific template variants
• Creates BoxLang test files (.bxm extensions)

The ColdBox CLI provides a comprehensive AI integration system that enhances your development workflow with intelligent coding assistance. This includes guidelines, skills, agent configurations, and MCP (Model Context Protocol) servers.

# Install AI integration
coldbox ai install                    # Interactive setup
coldbox ai install agent=claude    # Setup with specific agent

# View current configuration
coldbox ai info                       # Show configuration summary
coldbox ai tree                       # Visual hierarchy of AI components
coldbox ai stats                      # Context usage and statistics
coldbox ai stats --verbose            # Detailed breakdown with model utilization

# Sync with installed modules
coldbox ai refresh                    # Update guidelines and skills

# Diagnose issues
coldbox ai doctor                     # Check AI integration health

After coldbox ai install, your project will have a .agents/ directory containing:

/.agents/
├── guidelines/         # AI framework and domain documentation
│   ├── core/          # ColdBox & BoxLang/CFML language guidelines (framework built-ins)
│   ├── custom/        # Your project-specific guidelines
│   └── overrides/     # Custom versions of core/module guidelines
├── skills/            # Implementation cookbooks for specific features
│   ├── {skill-name}/
│   │   └── SKILL.md   # Step-by-step implementation guide
│   └── overrides/     # Override core/module skills
└── manifest.json     # AI integration metadata (generated)

# Agent-specific skill symlinks (auto-managed, relative links to .agents/skills/):
.claude/skills/{skill-name}        → ../../.agents/skills/{skill-name}
.cursor/rules/{skill-name}         → ../../.agents/skills/{skill-name}
.github/instructions/{skill-name}  → ../../.agents/skills/{skill-name}
.kilo/skills/{skill-name}          → ../../.agents/skills/{skill-name}
.pi/skills/{skill-name}            → ../../.agents/skills/{skill-name}

• Guidelines: Framework documentation and best practices (ColdBox, BoxLang, CFML, etc.)
• Skills: Specialized coding cookbooks for implementing specific features, canonically stored in .agents/skills/ and exposed to each agent via symlinks in their native skills directories
• Manifest: Tracks installed guidelines, skills, agents, and MCP servers

Configure AI assistants for your project (Claude, GitHub Copilot, Cursor, etc.):

# Manage agents
coldbox ai agents list                # List available agents
coldbox ai agents add claude copilot  # Add multiple agents
coldbox ai agents remove cursor       # Remove an agent
coldbox ai agents refresh             # Regenerate all configurations

Per-Agent Skill Discovery: Each agent discovers skills through its own native skills directory via automatically managed directory symlinks:

When a skill is installed, the CLI creates a relative directory symlink in each active agent's dedicated skills directory (e.g. .claude/skills/{name} → ../../.agents/skills/{name}). This lets every agent discover skills through its own expected path without duplicating content. Symlinks are automatically removed when a skill is removed or pruned during coldbox ai refresh.

Framework documentation and best practices for AI assistants:

# View guidelines
coldbox ai guidelines list            # List all installed guidelines
coldbox ai guidelines list --verbose  # Show details and descriptions

# Manage guidelines
coldbox ai guidelines add coldbox testbox        # Install by name
coldbox ai guidelines add https://example.com/   # Install from URL
coldbox ai guidelines remove testbox              # Remove guideline
coldbox ai guidelines refresh                        # Update from modules

Guideline Types: Core (framework), Module (from installed modules), Custom (project-specific), Override (custom versions of core)

AI coding cookbooks with practical how-to examples. Skills are stored canonically at .agents/skills/{name}/ and automatically exposed to each AI agent through relative directory symlinks in the agent's native skills directory.

# View skills
coldbox ai skills list                # List all installed skills
coldbox ai skills list --verbose      # Show details
coldbox ai skills list --json         # JSON output for scripting

# Manage skills
coldbox ai skills install creating-handlers async-programming
coldbox ai skills remove async-programming
coldbox ai skills update              # Update all installed registry skills
coldbox ai skills update {name}       # Update a single installed registry skill
coldbox ai skills refresh             # Update from modules

Skill Categories: Scaffolding, Testing, Configuration, Database, REST APIs, Security, Performance, and more

Automatic Symlinks: When a skill is installed via coldbox ai install, coldbox ai skills install, or coldbox ai refresh, the skill is created at .agents/skills/{name}/ and a relative directory symlink is created inside every active agent's dedicated skills directory (e.g. .claude/skills/{name} → ../../.agents/skills/{name}). Symlinks are automatically cleaned up when a skill is removed (coldbox ai skills remove) or pruned during refresh. No duplication, no manual linking required.

Model Context Protocol documentation servers provide live, up-to-date documentation access for AI agents. ColdBox CLI manages three types of MCP servers and keeps them in sync in both the manifest and the root .mcp.json file (compatible with VS Code, Claude Desktop, and other MCP clients):

# View MCP configuration
coldbox ai mcp list                  # List all configured servers
coldbox ai mcp list --verbose        # Show descriptions and URLs

# Install cbMCP (live ColdBox app introspection)
coldbox ai mcp install               # Install cbmcp module + register at http://localhost:8888/cbmcp
coldbox ai mcp install --port=8080   # Custom port
coldbox ai mcp install --force       # Overwrite existing cbmcp config

# Add/remove custom servers
coldbox ai mcp add company-docs --url=https://docs.company.com/mcp
coldbox ai mcp remove company-docs
coldbox ai mcp remove cbsecurity --force   # Force remove a module server

MCP Server Types:

• Core (auto-configured): coldbox, boxlang, testbox, wirebox, cachebox, logbox, commandbox
• Module (auto-detected from box.json): cbsecurity, quick, cfmigrations, cbvalidation, cbwire, and 20+ more
• Custom: Any URL-based or stdio MCP server you add manually
• cbMCP (local app): Your running ColdBox application exposed as an MCP server via coldbox ai mcp install

What cbMCP provides: Once installed and your server is running, AI agents can query your live application for current routes, handler actions, model interfaces, and more — enabling context-aware code generation tailored to your actual project structure.

Subagent Pattern: ColdBox CLI uses an optimized architecture that keeps agent files lean while providing full capability on-demand:

• Core Guidelines Referenced (~0 tokens in agent file): ColdBox framework + language guidelines stored in .agents/guidelines/core/ and loaded on-demand via read_file when needed
• Resource Inventories (~13KB): Module guidelines and skills listed with descriptions for on-demand loading
• Total Base Context: ~250 lines per agent file (down from ~1,000 lines when guidelines were inlined)

The CLI tracks and analyzes your AI context usage:

• Context Estimation: Calculates total KB and token usage
• Usage Indicators: Shows Low/Moderate/High/Very High warnings
• Model Compatibility: Displays utilization for Claude, GPT-4, GPT-3.5-Turbo, Gemini
• Optimization Tips: Monitors context efficiency with the subagent pattern

coldbox ai stats                      # Quick overview
coldbox ai stats --verbose            # Full analysis with model breakdowns
coldbox ai stats --json               # Machine-readable output

Every command provides detailed help:

# General help
coldbox help

# AI integration help
coldbox ai help

# Specific command help
coldbox create handler --help
coldbox ai agents --help
coldbox ai stats --help

I THANK GOD FOR HIS WISDOM IN THIS PROJECT

"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12