Commandbox setup

CommandBox Setup & Installation

Overview

CommandBox is a standalone CLI tool for Windows, Mac, and Linux that provides a command line interface for CFML/BoxLang development, package management, embedded servers, and automation. Written in CFML on top of WireBox, Undertow, and Lucee.

• Java requirement: Java 11+ required (Java 21+ recommended for BoxLang runtime)
• Disk space: 250MB+ free
• RAM: 256MB+ for CLI (servers require additional memory)
• Home directory: ~/.CommandBox/ (or customized via commandbox_home)

---

Installation

macOS — Homebrew (Recommended)

# Stable release
brew install commandbox

# Bleeding edge
brew tap ortus-solutions/homebrew-boxtap
brew install --head ortus-solutions/homebrew-boxtap/commandbox

# Upgrade
brew upgrade commandbox

# Switch between versions
brew install [email protected]
brew unlink commandbox
brew link [email protected]

After install, run box to complete the one-time unpacking:

box

Linux — apt-get

# Debian/Ubuntu setup (libappindicator for tray icon)
sudo apt install libappindicator3-dev    # Ubuntu 18.04+
sudo apt install libappindicator-dev     # Older Ubuntu/Debian

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

# RPM / yum
curl -fsSl https://downloads.ortussolutions.com/KEYS | sudo rpm --import -
echo -e "[commandbox]\nname=CommandBox\nbaseurl=https://downloads.ortussolutions.com/rpms/noarch\nenabled=1\ngpgcheck=1\ngpgkey=https://downloads.ortussolutions.com/KEYS" | sudo tee /etc/yum.repos.d/commandbox.repo
sudo yum install commandbox

Windows

1. Download box.exe from downloads.ortussolutions.com
2. Place box.exe in a directory on your PATH
3. Run box.exe to complete first-time unpacking
4. On Windows 10+: If SmartScreen blocks, click "More info" → "Run anyway"

Manual Install (Any Platform)

# Download the appropriate binary, unzip and place in PATH
# macOS/Linux: /usr/local/bin/box
# Run to unpack
box

---

Custom Home Directory

By default, CommandBox unpacks into ~/.CommandBox. Override with:

Command-line flag:

box -commandbox_home=/custom/path

commandbox.properties file (place in same directory as the binary):

commandbox_home=/custom/path
# or relative path
commandbox_home=../boxHome

Note: On Homebrew installs, place commandbox.properties in /opt/homebrew/Cellar/commandbox/<version>/libexec/bin/

---

Light & Thin Binaries

CommandBox offers smaller binaries for environments where size matters:

Binary	Description
Standard	Full install with all core modules
Light	No server or forgebox modules bundled
Thin	No modules bundled — all downloaded on first run

# Light binary: download from releases page with "-light" suffix
# Thin binary: download with "-thin" suffix

---

Java Version Management

CommandBox embeds its own JRE or uses the system JRE:

# Check what Java CommandBox is using
box java version

# List available JDKs
box java list

# Install a specific JDK
box java install openjdk21

# Set a custom JRE path (place 'jre' folder next to the box binary)
# Or set JAVA_HOME env var before running box

For non-Oracle JREs (e.g., OpenJDK, Azul Zulu):

# Set JAVA_HOME to point to your JDK
export JAVA_HOME=/path/to/openjdk21
box

---

Upgrading CommandBox

# From within CommandBox shell
upgrade

# Or via Homebrew on macOS
brew upgrade commandbox

# Check current version
version

Warning: Homebrew upgrade erases the current Cellar folder. Back up commandbox.properties before upgrading.

---

First-Run Configuration

# Enter interactive shell
box

# Check version
version

# Update to latest
upgrade

# Set ForgeBox API key (for publishing packages)
config set endpoints.forgebox.APIToken=your-api-key

---

Verify Installation

# Check version
box version

# Run a quick command
box echo "CommandBox is working!"

# List installed modules
box list --system