CommandBox CLI & Server Management

What is CommandBox?

CommandBox is the package manager, CLI, and embedded server for the CFML ecosystem. Think of it as npm + node for ColdFusion — one tool that installs ForgeBox packages, manages Lucee/Adobe CF server instances, runs test suites, and provides a CFML REPL, all from the terminal.

CommandBox is package manager + embedded server + CLI in one tool — the npm + node of the CFML world.

In this lab environment, box is already on the PATH and a Lucee 7 server is running on port 8888 via a systemd service. You do not need to install or start anything — CommandBox is ready to use.

The box command

Everything in CommandBox goes through the box command. You can run single commands inline or drop into the interactive shell:

# Run a single command inline
box version
box server list

# Drop into the interactive CommandBox shell (exit with 'exit')
box

Server management

# Check the status of running servers
box server list

# Start a server (picks up server.json if present)
box server start

# Start with explicit options — engine, port, no browser
box server start cfengine=lucee@7.0.4.34 port=8888 openbrowser=false

# Stop a named server
box server stop name=hungry-minds-training

# Get detailed info about a running server
box server info

server.json — server configuration file

Persist server settings in a server.json file at the project root so any developer starts an identical server with just box server start:

{
  "name": "hungry-minds-training",
  "web": {
    "http": { "port": 8888 }
  },
  "app": {
    "cfengine": "lucee@7.0.4.34",
    "webroot": "/home/laborant/app"
  }
}

server.json pins the engine version and port — reproducible server config checked into source control.

box.json — project package descriptor

box.json is CommandBox's equivalent of package.json for Node or composer.json for PHP. It sits at the root of your project and answers three questions:

• What is this project? — name, version, author, description
• What does it depend on? — ForgeBox packages and their version constraints
• How is it built/tested? — custom scripts you can run with box run-script

One box.json per project — you have exactly one at the project root. If you have multiple CFML applications in subdirectories, each gets its own box.json.

{
  "name": "helpdesk-app",
  "version": "1.0.0",
  "author": "Hungry Minds Training",
  "description": "ColdFusion 2025 Help Desk application",
  "dependencies": {
    "cbvalidation": "^4.0.0",
    "hyper": "^4.0.0"
  },
  "devDependencies": {
    "testbox": "^5.0.0",
    "mockbox": "^3.0.0"
  },
  "scripts": {
    "test": "testbox run"
  }
}

dependencies vs devDependencies — just like npm:

The box install workflow:

# Install everything in box.json (first checkout or after pulling from git)
box install

# Add a package and save it to box.json dependencies
box install cbvalidation --save

# Add a dev-only package
box install testbox --saveDev

# Install production dependencies only
box install --production

All packages land in {webroot}/modules/ — never commit that folder to git, just like node_modules. Add modules/ to your .gitignore and let box install recreate it from box.json.

Version constraints follow semantic versioning:

Run box install to install all declared dependencies into {webroot}/modules/.

# Install latest version
box install testbox

# Install specific version
box install coldbox@6.9.0

# Install and save to box.json dependencies
box install cbvalidation --saveDev

# List installed packages
box list

Activity 1 — Verify CommandBox is installed and check the version

What you are doing: Confirm box is on the PATH and check its version. In the Terminal tab, run:

box version

You should see output like CommandBox CLI v6.x.x — the exact version installed in this environment.

export JAVA_HOME="/opt/coldfusion2025/jre" && export PATH="$JAVA_HOME/bin:$PATH"

box version confirms CommandBox is installed and operational.

Activity 2 — Confirm the Lucee server is running on port 8888

What you are doing: The Lucee 7 server is already running on port 8888 via a systemd service — it was started automatically when the playground launched, not by box server start. Confirm it is responding correctly with a direct HTTP check.

In the Terminal tab, run:

curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:8888/index.cfm

You should see HTTP 200. Then open the Lucee Dev Server browser tab to see the running application.

Once you can see the Lucee Dev Server page, click the Lucee Admin Console ↗ button on that page — it opens the Lucee Server Administrator in a new browser tab. The default password is training.

You can also navigate directly to:

http://localhost:8888/lucee/admin/server.cfm

systemctl status lucee-server.service

sudo journalctl -u lucee-server.service --no-pager -n 50
sudo systemctl restart lucee-server.service

systemctl status lucee-server.service

HTTP 200 on port 8888 confirms the Lucee server is up and serving requests.

Activity 3 — Initialise the project with box.json

What you are doing: Create a box.json file in the app directory to register it as a CommandBox project. This is the equivalent of npm init — it records the project name, version, and any dependencies.

File to create: /home/laborant/app/box.json

In the Terminal tab, run:

sudo tee /home/laborant/app/box.json << 'EOF'
{
  "name": "helpdesk-app",
  "version": "1.0.0",
  "author": "Hungry Minds Training",
  "description": "ColdFusion 2025 Foundations — Help Desk training application",
  "dependencies": {}
}
EOF

Verify the file was created:

cat /home/laborant/app/box.json

box.json initialised — the project is now a CommandBox-managed package with a name, version, and dependency manifest.

When all the checks above are green, this lesson is complete. Your progress is saved automatically — move straight on to the next lesson.