Coldbox CLI

ColdBox CLI Skill

When to Use This Skill

Use this skill when:

• Creating a new ColdBox application from a skeleton
• Scaffolding any ColdBox artifact: handler, model, service, view, layout, interceptor, module
• Generating ORM entities, services, or CRUD scaffolding
• Generating test specs (BDD or xUnit, unit or integration)
• Running the interactive app-wizard for guided project creation
• Managing AI integration (installing guidelines, skills, agents, MCP servers)
• Choosing between BoxLang (default) and CFML output

Language Mode Reference

Examples use BoxLang (.bx) syntax by default. Adapt for your target language:

CFML Compat Mode: With BoxLang + CFML Compat module, .bx and .cfc files coexist freely. BoxLang-native classes use class {} (.bx files); CFML-compat classes use component {} (.cfc files).

Command Quick Reference

All commands are prefixed with coldbox.

coldbox create — Code Generation

coldbox ai — AI Integration

Language Handling

BoxLang is the Default

All coldbox create commands generate BoxLang (.bx) files by default. CFML (.cfc) output is opt-in.

Auto-Detection Logic (isBoxLangProject())

The CLI automatically detects the project language using:

1. Running server engine — serverInfo.cfengine contains "boxlang"
2. box.json → testbox.runner == "boxlang"
3. box.json → language == "boxlang"

If none of the above match and no flag is passed, BoxLang is still the default for new projects.

Language Flags

Output File Extensions

Component → Class Conversion

When generating BoxLang files, the CLI transforms CFML component keyword to BoxLang class automatically. You never need to handle this manually.

App Creation

Skeletons

coldbox create app myApp                   # BoxLang (default)
coldbox create app myApp --cfml            # CFML Modern layout
coldbox create app myApp skeleton=rest     # REST API skeleton

Any valid ForgeBox endpoint ID, Git URL, or HTTP URL can also be passed as skeleton:

coldbox create app skeleton=http://site.com/myTemplate.zip
coldbox create app skeleton=coldbox-templates/rest

Feature Flags for App Creation

# Full-featured BoxLang REST API with all extras
coldbox create app myAPI \
  skeleton=rest \
  --migrations \
  --docker \
  --ai \
  --aiAgent=claude,copilot

# Modern CFML app with Docker
coldbox create app myApp --cfml --docker --migrations

Interactive Wizard

Use the wizard for a guided experience that prompts for language, skeleton, features, AI setup, and more:

coldbox create app-wizard

Code Generation Commands

Handler

Generates an event handler (controller) with optional actions, views, and tests.

coldbox create handler users
coldbox create handler users actions=index,show,create,update,delete --views
coldbox create handler api/Users --rest
coldbox create handler photos --resource --integrationTests

Model

Generates a model class with optional properties, accessors, persistence, migration, seeder, and handler.

coldbox create model User
coldbox create model User properties=firstName,lastName,email
coldbox create model Post properties=title,body,publishedDate:timestamp --accessors --persistence
coldbox create model Product properties=name,price:numeric,stock:integer --all

Service

Generates a service model with optional methods and tests.

coldbox create service UserService
coldbox create service OrderService methods=create,cancel,refund,getByUser --tests

Resource

Full RESTful scaffolding: handler + model + views/API actions + optional tests, migration, and seeder.

Standard resource actions generated:

API resources omit new and edit (HTML form) actions.

# Basic resource
coldbox create resource photos

# Multiple resources at once
coldbox create resource photos,users,categories

# API resource with tests and migration
coldbox create resource photos --api --tests --migration

# ORM-backed resource
coldbox create resource photos singularName=Photo --persistent --migration --seeder

View

Generates a view template.

coldbox create view users/index
coldbox create view users/show --helper  # also creates view helper
coldbox create view home --cfml          # force CFML .cfm extension

Layout

Generates a layout template.

coldbox create layout default
coldbox create layout admin --helper

Interceptor

Generates an interceptor with optional interception points and tests.

coldbox create interceptor SecurityInterceptor
coldbox create interceptor AuditInterceptor points=preProcess,postProcess --tests
coldbox create interceptor SessionInterceptor points=afterAspectsLoad,preEvent

Module

Generates a full ColdBox module scaffold.

coldbox create module myModule author="Jane Doe" description="My custom module"
coldbox create module payments version=2.0.0 --ai

ORM Commands

ORM Entity

Generates an ORM-mapped entity class.

coldbox create orm-entity User
coldbox create orm-entity Post table=blog_posts properties=title,body,publishedAt:timestamp
coldbox create orm-entity Product --activeEntity properties=name,price:numeric --all

ORM Service

Generates an ORM service extending cborm.models.VirtualEntityService.

coldbox create orm-service User
coldbox create orm-service Post --queryCaching --eventHandling cacheRegion=postCache

ORM CRUD

Generates a handler + views for full CRUD based on an existing ORM entity.

coldbox create orm-crud User
coldbox create orm-crud Product pluralName=Products --tests

ORM Virtual Service

Generates a virtual entity service (no concrete class needed).

coldbox create orm-virtual-service User
coldbox create orm-virtual-service Post --queryCaching

ORM Event Handler

Generates an ORM event handler for Hibernate lifecycle events.

coldbox create orm-event-handler

Testing Commands

Integration Test

Generates a ColdBox integration test spec.

coldbox create integration-test users
coldbox create integration-test users actions=index,show,create
coldbox create integration-test users --xunit

BDD Spec

Generates a TestBox BDD spec (delegates to testbox-cli).

coldbox create bdd UserSpec

Unit Test

Generates a TestBox xUnit bundle (delegates to testbox-cli).

coldbox create unit UserTest

AI Integration

Install AI Integration

Installs AI context files into the application's .ai/ directory.

# Default: BoxLang project, Claude agent
coldbox ai install

# Multiple agents
coldbox ai install --aiAgent=claude,copilot,cursor

# CFML project
coldbox ai install --cfml

# Force re-install
coldbox ai install --force

Installed structure:

.ai/
├── guidelines/          # Framework docs (boxlang, coldbox, cborm, cbAuth, etc.)
├── skills/              # On-demand implementation cookbooks
├── manifest.json        # Tracks what is installed (version, agents, guidelines, skills, MCP)
CLAUDE.md                # (if --aiAgent=claude)
.github/copilot-instructions.md  # (if --aiAgent=copilot)
.cursorrules             # (if --aiAgent=cursor)
AGENTS.md                # (if --aiAgent=codex or opencode)
GEMINI.md                # (if --aiAgent=gemini)

Supported agents: claude, copilot, cursor, codex, gemini, opencode

Refresh AI Integration

Syncs guidelines and skills from newly installed CommandBox modules:

coldbox ai refresh

Diagnostics

coldbox ai info      # Show current guidelines, skills, agents, and MCP servers
coldbox ai doctor    # Diagnose configuration issues
coldbox ai tree      # Tree view of .ai/ directory
coldbox ai stats     # AI context character/token usage stats

Guideline Sub-Commands

coldbox ai guidelines list
coldbox ai guidelines add cborm
coldbox ai guidelines remove cborm

Core guidelines available: boxlang, cfml, coldbox Module guidelines (40+): bcrypt, cbauth, cborm, testbox, wirebox, and many more

Skill Sub-Commands

coldbox ai skills list
coldbox ai skills add handler-development
coldbox ai skills remove handler-development

Over 71 skills are available, covering BoxLang core, ColdBox framework, ORM, security, testing, and modules.

MCP Server Sub-Commands

coldbox ai mcp list
coldbox ai mcp add coldbox
coldbox ai mcp remove coldbox

Over 30 Ortus MCP documentation servers available (ColdBox, TestBox, WireBox, CacheBox, LogBox, QB, Quick, CBSecurity, and more).

Template Tokens Reference

All code templates use |TOKEN| markers that are replaced with generated values. You typically do not interact with templates directly, but knowing the tokens helps you understand what the CLI configures.

Layout Detection

The CLI automatically detects whether the project uses a modern or flat directory layout and adjusts all generated paths.

Modern layout:          Flat layout:
app/                    handlers/
  handlers/             models/
  models/               views/
  views/                tests/specs/
tests/specs/

You never need to configure this — detection is automatic.

Common Workflows

New BoxLang REST API from Scratch

# 1. Create the app
coldbox create app myAPI skeleton=rest --migrations --docker --ai --aiAgent=copilot

# 2. Create a resource endpoint
coldbox create resource products --api --tests --migration

# 3. Create a service layer
coldbox create service ProductService methods=list,findById,create,update,delete

# 4. Create an authentication interceptor
coldbox create interceptor JWTInterceptor points=preProcess --tests

New CFML App with Full CRUD

# 1. Create the app
coldbox create app myApp --cfml --migrations

# 2. Scaffold a full ORM-backed resource
coldbox create resource blog/posts \
  singularName=Post \
  --persistent \
  --tests \
  --migration \
  --seeder

# 3. Generate integration tests for the posts handler
coldbox create integration-test blog/Posts actions=index,show,create,update,delete

Add AI Integration to an Existing App

# From your app root
coldbox ai install --aiAgent=claude,copilot

# After installing new CommandBox modules (e.g., cbsecurity):
coldbox ai refresh

# Check what was installed
coldbox ai info
coldbox ai stats

Scaffold a ColdBox Module

# Create the module
coldbox create module payments author="Acme Corp" description="Payment integrations" version=1.0.0

# Add a handler inside the module
cd modules/payments
coldbox create handler Checkout actions=index,process,confirm --views

# Add a service
coldbox create service PaymentGatewayService methods=charge,refund,void

Tips & Best Practices

• Always run commands from the application root — the CLI uses the current directory to locate handlers/, models/, views/, and tests/ correctly.
• Use --force carefully — it silently overwrites existing files. Omit it to get a confirmation prompt.
• Use --open to immediately open newly created files in your editor.
• Combine --all on model/resource — coldbox create model User --all is the fastest way to get a handler + migration + seeder in one command.
• coldbox create resource is the quickest path to a full CRUD feature — it scaffolds handler, model, views/API actions, tests, migration, and seeder in one step.
• Use app-wizard for new projects — it guides you through language, skeleton, feature selection, and AI setup interactively.
• Refresh AI integration after installing new CommandBox modules (coldbox ai refresh) to pick up module-specific guidelines and skills automatically.
• Semicolons are not needed in generated code (BoxLang optional; CFML convention followed by the templates) except on property declarations: property name="foo" type="string";