1 of 100

5.3.0 Introduction

CommandBox Manual - Version 5.3.1

Versioning

<major>.<minor>.<patch>.<buildID>

And constructed with the following guidelines:

Breaking backward compatibility bumps the major (and resets the minor and patch)
New additions without breaking backward compatibility bumps the minor (and resets the patch)
Bug fixes and misc changes bumps the patch

License

Copyright by Ortus Solutions, Corp
CommandBox is a registered trademark by Ortus Solutions, Corp

Info The CommandBox Websites, Documentation, logo and content have a separate license and they are a separate entity.

Discussion & Help

Reporting a Bug

Professional Open Source

Custom Development
Professional Support & Mentoring
Training
Server Tuning
Security Hardening
Code Reviews

Resources

HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, it's not for you.

"Therefore being justified by **faith**, we have peace with God through our Lord Jesus Christ: By whom also we have access by **faith** into this **grace** wherein we stand, and rejoice in hope of the glory of God." Romans 5:5

About This Book

The majority of code examples in this book are done in cfscript.

External Trademarks & Copyrights

Flash, Flex, ColdFusion, and Adobe are registered trademarks and copyrights of Adobe Systems, Inc. Railo is a trademark and copyright of Railo Technologies, GmbH. Lucee is a trademark and copyright of Lucee Association Switzerland.

Notice of Liability

The information in this book is distributed “as is”, without warranty. The author and Ortus Solutions, Corp shall not have any liability to any person or entity with respect to loss or damage caused or alleged to be caused directly or indirectly by the content of this training book, software and resources described in it.

Contributing

Charitable Proceeds

Shalom Children's Home

Shalom now cares for over 80 children in El Salvador, from newborns to 18 years old. They receive shelter, clothing, food, medical care, education and life skills training in a Christian environment. The home is supported by a child sponsorship program.

We have personally supported Shalom since 2006; it is a place of blessing for many children in El Salvador that either have no families or have been abandoned. This is good earth to seed and plant.

Authors

Luis Fernando Majano Lainez

Luis has a passion for Jesus, tennis, golf, volleyball and anything electronic. Random Author Facts:

He played volleyball in the Salvadorean National Team at the tender age of 17
The Lord of the Rings and The Hobbit is something he reads every 5 years. (Geek!)
His first ever computer was a Texas Instrument TI-86 that his parents gave him in 1986. After some time digesting his very first BASIC book, he had written his own tic-tac-toe game at the age of 9. (Extra geek!)
He has a geek love for circuits, microcontrollers and overall embedded systems.
He has of late (during old age) become a fan of running and bike riding with his family.

Keep Jesus number one in your life and in your heart. I did and it changed my life from desolation, defeat and failure to an abundant life full of love, thankfulness, joy and overwhelming peace. As this world breathes failure and fear upon any life, Jesus brings power, love and a sound mind to everybody!
“Trust in the LORD with all your heart, and do not lean on your own understanding.” – Proverbs 3:5

Brad Wood

Brad's CommandBox Snake high score is 141.

Contributors

Jorge Reyes - ColdBox Aficionado

Overview

CommandBox is a standalone, native Command Line Interface (CLI), Package Manager, Embedded CFML Server and Read Eval Print Loop (REPL) aimed to help ColdFusion (CFML) developers become more productive through automation, dependency management, command line-based tools, and ASCII snake games.

Features at a Glance

CommandBox is an amalgamation of many different tools and borrows concepts from NPM, Grunt/Gulp, Maven, Bower, and Node. Features include:

Command Line for ColdFusion (CFML)
Operating System integration for executing commands
Ability to create and execute commands built using ColdFusion (CFML)
ForgeBox integration for cloud package management and installations
ColdBox Platform, TestBox, and ContentBox CMS Integrations
Integrated servlet server with rewrite capabilities
Ability to create command recipes and execution
REPL (Read-Evaluate-Print-Loop) console for immediate ColdFusion
(CFML) interaction
Ability to interact with user via CLI and create workflows and
installers
Ability to execute workflows and tasks
Built-in Help system

Release History

In this section you will find the release notes for each version we release under this major version. If you are looking for the release notes of previous major versions use the version switcher at the top left of this documentation book. Here is a breakdown of our major version releases.

5.x Versions

In this section you will find the release notes for the 5.x version of CommandBox.

What's New in 5.3.1

Updated bundled Java libraries

JLine - 3.19.0
jGit - 5.11.0.202103091610-r
Launch4j - 3.14
JANSI - 2.3.2

Recursive jar scanning libDirs

When you configure libDirs for a server, CommandBox used to only load jar files found in the root. Now it will include sub directories which gives you more flexibility around how to install your jars.

New printTable Command

In the previous release, we introduced a new helper for printing ASCII Art tables in your custom commands and task runners. We've taken this a step further and wrapped the table printer utiilty in a new command so you can use it from the CLI directly. We've also expanded its functionality to accept ANY data in as JSON and it will marshall it into a query for you. This means it can be a query, an array of structs, an array or arrays, and more. You can now get quick and easy visualization of any data right from the CLI or in builds.

New sql command for on-the-fly manipulation of data

As if the previous command isn't cool enough, we've also added a new "sql" command which will also accept any sort of data as JSON, marshall it into a query object and allow you to alias, filter, order, and limit the rows on the fly using CFML's query of queries!

The sql command works very nicely with the new tablePrinter command, and truly makes JSON a first class citizen of the CommandBox CLI.

Small change to print.table() helper

We've made a small adjustment to the print.table() helper that was introduced in CommandBox 5.3.1 as follows. The old method signature is

And the new method signature is:

The parameters to the new printTable command matches the NEW method signature of the print.table() helper as well.

Format XML in REPL

When working with XML in the REPL, formatting is now applied when the XML is printed out to the console, making it easier to read (same as JSON)

Release Notes

Bug

Improvement

New Feature

What's New in 5.3.0

Override Config Settings via Env Vars

Every Config Setting can be overridden by convention by creating environment variables in the shell where you run box. This is ideal for CI builds where you want to easily set ForgeBox API keys, or tweak settings for your build.

Override Server Settings via Env Vars

Every server setting can be overridden by convention by creating environment variables in the shell where you run box. This is ideal for CI builds where you want to easily set ports, or tweak settings for your build.

HTTP/2 Support

CommandBox now has out-of-the-box support for the HTTP/2 protocol. It is always enabled by default and browsers will use it when you're serving over HTTPS.

JMES JSON filtering / jq Command

We've added a new jq command which behaves roughly like the bash counterpart. You can pipe in JSON, or read the JSON from a file and apply a JSON query against it which can be used to filter, massage, rewrite, map, or filter the JSON into a new JSON object.

We've also added the ability to specify powerful jq filters to the "package show", "server show", and "config show" commands directly. Just prefix your filter with the text "jq:" like so:

AJP Secret Support

For this to work, you must also configure your AJP proxy in your web server to send the same secret!

AsyncManager Available to Task Runners and Commands

We've updated the version of WireBox inside the CLI and now have access to the AsyncManager for sweet threading and scheduled task support.

CommandBox is using an AsyncManager scheduled task thread now to redraw interactive jobs and progress bars. Look out for some new eye candy hiding in your server starts and package installs!

New Table Printer

The print helper in commands and Task Runners has a new toy that will print ASCII representations of tabular data thanks to a pull request from Eric Peterson. You can see it in the output of the outdated command.

And you can use it in your Task Runners like so:

ColdBox Scaffolding for REST Handlers

When scaffolding ColdBox handlers, we have support for ColdBox 6.x REST Handlers now.

Experimental Server Features

You can enable extra Resource Manager Logging when troubleshooting file system issues:

You can force case sensitivity on a Windows server:

You can force case Insensitivity on a Linux server:

You can enable a cache of file system lookups of servlet paths. This is only for production and will eliminate repeated file system hits by your CF engine, such as checking for an Application.cfc file on every request, or testing where the servlet context root is. Standard Adobe ColdFusion installations have a similar cache of "real" paths from the servlet context that is tied to a setting in the administrator called "Cache Webserver paths" but that setting is not available and does not work on CommandBox servers for some reason. This setting would apply to any CF engine.

HTTPS Redirect/HSTS

When using a CommandBox web server in production, you may wish to force your users to visit your site over HTTPS for security (and for HTTP/2 to work). However, it is desirable to still have your web server listening on HTTP so a user just typing your address in his browser can still connect to HTTP and then redirect. CommandBox can be configured to redirect all HTTP traffic over to HTTPS with the following setting.

If you want to go one step further, you can add a Strict-Transport-Security header to your site. This instructs the browser to automatically use HTTPS every time the user visits your site again.

Force Colored Output in your Builds

CommandBox won't use ANSI color formatting when running inside of a non-interactive terminal. However, build servers such as Gitlab or Jenkins (via a plugin) support ANSI color sequences. You can force CommandBox to use colored text output with this new setting:

Loose Semantic Version Parsing

One of the common hangups for people dealing with Lucee Server and Adobe ColdFusion CF Engines versions, is that CommandBox follows the npm-flavor of the semantic version spec and expects

instead of

So we've loosened our sem ver library to treat the 4th number as a build ID if there is no plus sign in the version (instead of just discarding the 4th digit as the spec requires)

Support for "localhost subdomains"

Most modern browsers allow you to make up any subdomain you want before localhost such as mySite.localhost and will simply resolve them to localhost (127.0.0.1) even without a hosts file entry. CommandBox now supports using these domains and will bind your server's ports to localhost even without using the commandbox-hostupdater module.

Relative CommandBox home

You can customize where CommandBox lives by placing a commandbox.properties file next to the box binary. We have better support for relative paths now so you can have portable CommandBox installations such as a thumb drive.

Halt Server If Port In Use (Breaking Change)

The only known breaking change in this release is if you try to start two servers on the same HTTP port. Previously, CommandBox would just ignore the port on the second server and choose a random port. Due to the confusion that can cause, CommandBox will now throw an error. If you want to override an explicit port locally, set the port to an empty string or a 0 and CommandBox will choose a random port for you. For example, if you are using the commandbox-dotenv module, you can put this line in your project's .env file to override the port in your server.json

Relative Web Alias Behavior (regression)

If you have a server with the server.json outside of the web root and at least one relative web alias, the alias will not work on the first start of the server. The workaround is to change the web aliases to be relative to the folder that the server.json lives in.

Incompatibility with old DotEnv module

Some users receive the following error when starting CommandBox after updating:

If you see this, it means you have an older version of the commandbox-dotenv module installed that is not compatible with the new version of WireBox inside CommandBox. To fix, delete this folder out of your CommandBox home:

Now the CLI will start and you can install the latest version of dotenv.

Release notes

Here is the list of all tickets included in the 5.3.0 release.

Bug

Improvement

New Feature

What's New in 5.3.1

Updated bundled Java libraries

JLine - 3.19.0
jGit - 5.11.0.202103091610-r
Launch4j - 3.14
JANSI - 2.3.2

Recursive jar scanning libDirs

# Jar installs to lib/jline-3.0.0.M1/jline-3.0.0.M1.jar
install "jar:https://search.maven.org/remotecontent?filepath=jline/jline/3.0.0.M1/jline-3.0.0.M1.jar"

# Load up the jar when the server starts
server set app.libDirs=lib

New printTable Command

# array of structs
printTable [{a:1,b:2},{a:3,b:4},{a:5,b:6}]

╔═══╤═══╗
║ a │ b ║
╠═══╪═══╣
║ 1 │ 2 ║
╟───┼───╢
║ 3 │ 4 ║
╟───┼───╢
║ 5 │ 6 ║
╚═══╧═══╝

# array of arrays
printTable data=[[1,2],[3,4],[5,6]] headerNames=foo,bar

╔═════╤═════╗
║ foo │ bar ║
╠═════╪═════╣
║ 1   │ 2   ║
╟─────┼─────╢
║ 3   │ 4   ║
╟─────┼─────╢
║ 5   │ 6   ║
╚═════╧═════╝

# Query object
#extensionlist | printTable name,version

╔═════════════════════════════════════════╤═══════════════════╗
║ name                                    │ version           ║
╠═════════════════════════════════════════╪═══════════════════╣
║ MySQL                                   │ 8.0.19            ║
╟─────────────────────────────────────────┼───────────────────╢
║ Microsoft SQL Server (Vendor Microsoft) │ 6.5.4             ║
╟─────────────────────────────────────────┼───────────────────╢
║ PostgreSQL                              │ 9.4.1212          ║
╟─────────────────────────────────────────┼───────────────────╢
║ Ajax Extension                          │ 1.0.0.3           ║
╚═════════════════════════════════════════╧═══════════════════╝

# JSON list of all servers
server list --json | printTable name,host,port,status

╔══════════════════════════════╤═════════════════════════════╤═══════╤═════════╗
║ name                         │ host                        │ port  │ status  ║
╠══════════════════════════════╪═════════════════════════════╪═══════╪═════════╣
║ servicetest                  │ 127.0.0.1                   │ 54427 │ stopped ║
╟──────────────────────────────┼─────────────────────────────┼───────┼─────────╢
║ servicetest2                 │ 127.0.0.1                   │ 52919 │ stopped ║
╟──────────────────────────────┼─────────────────────────────┼───────┼─────────╢
║ FRDemos                      │ 127.0.0.1                   │ 50458 │ stopped ║
╚══════════════════════════════╧═════════════════════════════╧═══════╧═════════╝

New sql command for on-the-fly manipulation of data

# filter, sort, limit, and select extensions installed into the CLI (output as table)
#extensionlist  | sql select=id,name where="name like '%sql%'" orderby=name limit=3 | printTable

# order and select JSON data from a file (output as JSON)
cat myfile.json | sql select=col1,col2 orderby=col2

# limit JSON (output as table)
sql data=[{a:1,b:2},{a:3,b:4},{a:5,b:6}] where="a > 1" | printTable

The sql command works very nicely with the new tablePrinter command, and truly makes JSON a first class citizen of the CommandBox CLI.

Small change to print.table() helper

We've made a small adjustment to the print.table() helper that was introduced in CommandBox 5.3.1 as follows. The old method signature is

public string function print(
	required any headers,
	array data=[],
	string includeHeaders        
) {

And the new method signature is:

public string function print(
	required any data=[],
	any includedHeaders="",
	any headerNames="",
	boolean debug=false
) {

The parameters to the new printTable command matches the NEW method signature of the print.table() helper as well.

Format XML in REPL

When working with XML in the REPL, formatting is now applied when the XML is printed out to the console, making it easier to read (same as JSON)

❯ repl "XMLParse( '<root><brad>wood</brad></root>' )"

<?xml version="1.0" encoding="utf-8"?><root>
  <brad>wood</brad>
</root>

Release Notes

Bug

Server stop doesn't message user when it fails

Stop loading cfusion/lib in system class loader

5.3.0 errors with commandbox-dotenv 1.x versions due to WireBox change

When building Lucee war from local jars, seeded web.xml file is ignored

Table printer error with no rows

update '{slug}' fails as it is trying to print the package version and its dependencies.

Relative Web Alias Behavior (regression)

jq doesn't resolve file paths to current working directory

CFEngine adobe - Could not initialize class coldfusion.vfs.VFile when using s3 protocol

Improvement

Improve performance of piping large strings to "cfml" command

Format XML in REPL

Change default CLI JSON representation of query to array of structs

Allow upgrade command to pull stable versions when CLI is a prerelease version

Update bundled java libraries

app.libDirs does not load jars/classes recursively from sub folders

Allow for relative URLs when defining trayoption elements

Add Libraries To Runwar Necessary For URLRewrite Proxy

New Feature

New "printTable" command to add CLI usage of table printer

New "sql" command to filter tabular data with SQL

Add --verbose to 'server stop' to see raw output

Add printTable command that proxies to print.table() helper

What's New in 5.3.0

Override Config Settings via Env Vars

box_config_endpoints_forgebox_APIToken=my-token-here

# JSON which will be parsed
box_config_proxy={ "server" : "localhost", "port": 80 }

# dot-delimited keys (windows only)
box_config_endpoints.forgebox.APIToken=my-token-here

# array indexes too (windows only)
box_config_foo.bar[baz].bum[1]=test

More Info:

Override Server Settings via Env Vars

box_server_profile=production

box_server_web_http_port=8080

# JSON which will be parsed
box_server_web_ssl={ "enabled" : true, "port": 443 }

# dot-delimited keys (Windows only)
box_server_web.http.port=8080

# array indexes too (Windows only)
box_server_web_rules[1]=path-suffix(/box.json) -> set-error(404)
box_server_web_rules[2]=disallowed-methods(trace)

More Info:

HTTP/2 Support

CommandBox now has out-of-the-box support for the HTTP/2 protocol. It is always enabled by default and browsers will use it when you're serving over HTTPS.

server set web.http2.enable=true/false

More Info:

JMES JSON filtering / jq Command

Thanks to a massive effort from Scott Steinbeck, the CFML world has a new of the , which is what powers the popular . We've plugged this new library into CommandBox and exposed it in the following ways.

# Return array of dependency names
package show | jq keys(dependencies)

# Find dependencies with "cb" in their name
package show | jq key_contains(dependencies,'cb')

We've also added the ability to specify powerful jq filters to the "package show", "server show", and "config show" commands directly. Just prefix your filter with the text "jq:" like so:

config show jq:endpoints.forgebox.apiToken
# .. is the same as ...
config show endpoints.forgebox.apiToken

# or you can get fancy...
config show 'jq:keys(modules)'

# Impress your friends
package show "jq:[name,version]"

# Be the life of the party
package show "jq:contributors|split(@,' ')"

The jq command and JMES spec are very powerful and probably do ! Make sure you check out the docs for more ideas.

More Info:

AJP Secret Support

CommandBox's AJP listener (provided by Undertow) is already protected against the . However, if you would like to set up an AJP secret as well to ensure all requests coming into the AJP listener are from a trusted source, you can do this by setting the web.ajp.secret property.

server set web.AJP.secret=mySecret

For this to work, you must also configure your AJP proxy in your web server to send the same secret!

More info:

AsyncManager Available to Task Runners and Commands

We've updated the version of WireBox inside the CLI and now have access to the AsyncManager for sweet threading and scheduled task support.

// Parallel Executions
async().all(
    () => hyper.post( "/somewhere" ),
    () => hyper.post( "/somewhereElse" ),
    () => hyper.post( "/another" )
).then( (results)=> logResults( results ) );

CommandBox is using an AsyncManager scheduled task thread now to redraw interactive jobs and progress bars. Look out for some new eye candy hiding in your server starts and package installs!

More Info:

New Table Printer

And you can use it in your Task Runners like so:

print.table(
	[ 'First Name', 'Last Name' ],
	[
		[ 'Brad', 'Wood' ],
		[ 'Luis', 'Majano' ],
		[ 'Gavin', 'Pickin' ]
	]
);

ColdBox Scaffolding for REST Handlers

When scaffolding ColdBox handlers, we have support for ColdBox 6.x REST Handlers now.

coldbox create handler --rest

Experimental Server Features

You can enable extra Resource Manager Logging when troubleshooting file system issues:

server set runwar.args="--resource-manager-logging=true"

You can force case sensitivity on a Windows server:

server set runwar.args="--case-sensitive-web-server=true"

You can force case Insensitivity on a Linux server:

server set runwar.args="--case-sensitive-web-server=false"

server set runwar.args="--cache-servlet-paths=true"

More Info:

HTTPS Redirect/HSTS

server set web.SSL.forceSSLRediect=true

If you want to go one step further, you can add a Strict-Transport-Security header to your site. This instructs the browser to automatically use HTTPS every time the user visits your site again.

server set web.SSL.HSTS.enable=true
server set web.SSL.HSTS.maxAge=31536000
server set web.SSL.HSTS.includeSubDomains=true

More Info:

Force Colored Output in your Builds

config set colorInDumbTerminal=true

Loose Semantic Version Parsing

One of the common hangups for people dealing with Lucee Server and Adobe ColdFusion CF Engines versions, is that CommandBox follows the npm-flavor of the semantic version spec and expects

server start cfengine=lucee@5.3.7+48

instead of

server start cfengine=lucee@5.3.7.48

So we've loosened our sem ver library to treat the 4th number as a build ID if there is no plus sign in the version (instead of just discarding the 4th digit as the spec requires)

Support for "localhost subdomains"

server set web.host=mySite.localhost

More Info:

Relative CommandBox home

commandbox_home=../customHome

More Info:

Halt Server If Port In Use (Breaking Change)

box_server_web_http_port=0

Relative Web Alias Behavior (regression)

Incompatibility with old DotEnv module

Some users receive the following error when starting CommandBox after updating:

The parameter [name] to function [get] is required but was not passed in.

~/.CommandBox/cfml/modules/commandbox-dotenv

Now the CLI will start and you can install the latest version of dotenv.

install commandbox-dotenv

Release notes

Here is the list of all tickets included in the 5.3.0 release.

Bug

web server aliases in server.json should be relative to the folder of the server.json

${Setting: serverinfo.foo not found} expansions don't work in a folder that's not the web root

Re-using same server.json with two names doesn't work

Corrupted WireBox metadata cache file will prevent CommandBox from starting

HTTP2 Additional Port Handling and Flexibility

REPL & Command highlighters don't handle square brackets [] well

JVM arg ending in backslash doesn't work

Coldbox Watch-Reinit Watches Unwanted Folders

Package installation doesn't always optimize duplicate packages

Globber.count() bombs if run after .asQuery()

Starting lucee@1.2.3 will use light-light when using CommandBox Light

Loading class files in task runner doesn't work

variables scope doesn't persist between task dependencies

tokenreplace removes BOM from files

trayOptions.json not respecting serverHomeDirectory

Server status not always correct.

Improvement

Add singleServerHome option to not auto-deploy different versions of servers

Improve error message if version isn't found in ForgeBox

Loosen parsing of build ID in semver

Treat empty HTTP port the same as 0 (chooses random port)

Remove runwar hack that sets java vesrion

Runwar timesout when Lucee's new warmup flag is used

Add option for PID file

Allow generic override of server start settings via env vars or java sys props

Have parser ignore quotes inside a token

Cache "/" path lookup in Runwar's mapped resource manager

Add setters for run() arguments in CommandDSL

Default embedded server only needs to copy lucee.jar

Have outdated also show latest version of a package

Integrate AsyncManager into CommandBox

Upgrade to latest WireBox 6.x

Bundle testbox in testbox module to prevent auto download

Halt server start if asked for port is in use

the git bullet train car disappears while current working directory is not the root project folder

Support AJP secret in Undertow

Rethink the way the screen is redrawn upon extensive installs so it can be fluent on all screen sizes

Can't link package if no modules are installed

New first-class setting to enable HTTP2

Comment out the default environment vars in .env when createing a new coldbox app

New Feature

Allow server rules to be commented out with #

Allow servers to use random.localhost domains

Integrate JMES JSON filtering

Debug when lucee-extensions don't find Lucee server

Allow JSON service to create implicit arrays

Add config setting to enable ANSI colors in dumb terminals

Allow generic override of config settings via env vars or java sys props

Add --json flag to server list

Add HTTP redirect options

Add optional servlet path cache in Runwar

Allow caching of task runners

Support for generating ColdBox RESTHandlers

Support default module export as @moduleName,

Allow commandbox_home to be relative

What's New in 5.2.0

There are a number of pretty exciting new features and a pile of bug fixes. And as usual, input from the community via Pull Requests. Huge thanks to Pete Freitag, Kai Koenig, Matthew Clemente, Bobby Hartsfield, Scott Steinbeck, Daniel Mejia, and Miguel Mathus! Here's an overview of the new stuff in 5.2.0

Library Updates

We know library updates are boring, but they are important and we want you to know we take them seriously. Keeping up-to-date ensure you have the latest fixes and security updates from all the third-party libs we bundle in CommandBox.

Here's an overview of what we updated in CommandBox 5.2.0.

Upgraded Runwar from 4.1.2 to 4.3.8
Upgraded JBoss Undertow from 2.0.27.Final to 2.2.0
Upgraded UrlRewritesFilter to Ortus fork 5.0.1 with custom fixes
Upgraded jboss-logging from 3.2.1.Final to 3.4.1.Final
Upgraded jboss-logging-annotations from 2.1.0 to 2.2.1.Final
Upgraded JCabi Log from 0.18 to 0.18.1
Upgraded Apache HttpClient from 4.2.6 to 4.5.12
Upgraded Apache httpmime from 4.2.6 to 4.5.12
Removed unused JOpt Simple 5.0-beta-1
Removed unused Gson 1.2.3

The Undertow bump is a minor update, but a pretty big deal. Ortus sent three pull requests to the core Undertow project fixing bugs and adding predicate logging. All of our pulls were accepted and merged into the core Undertow project and released in the 2.2 release.

Server Security Profiles

This is a feature that we expect to grow in the future. We've started it out simple, yet powerful but left a lot of room to build on it. The two main goals here are

Make CommandBox secure-by-default so a server shoved in production comes nice and locked down
Makes it very easy for you to toggle off all the security stuff for development

CommandBox now has profiles you can assign to a server when you start it to configure the default settings. This is to provide easy secure-by-default setups for your production servers, and to make it easier to switch between a development mode and production mode.

There are 3 currently supported profiles. Custom profiles will be added as a future feature.

Production - Locked down for production hosting
Development - Lax security for local development
None - For backwards compat and custom setups. Doesn't apply any web server rules

In production mode, CommandBox will block access to your CF admin to all external traffic, will block all common config files such as box.json or .env and will block, the "TRACK" and "TRACE" HTTP verbs

You can set the profile for your server in your server.json

server set profile=production

Or you can specify it when starting the server like so:

server start profile=production

If a profile is not set, CommandBox looks for an environment variable called "environment" or it checks to see if the site is bound on localhost to try and guess the correct profile for you.

We've also added some new flags in your server.json to fully customize how your profile behaves.

server set web.blockCFAdmin=true
server set web.blockCFAdmin=false
server set web.blockCFAdmin=external

server set web.blockSensitivePaths=true
server set web.blockSensitivePaths=false

server set web.blockFlashRemoting=true
server set web.blockFlashRemoting=false

‌Read more about Server Profiles here:

Server Rules

This is huge-- probably the biggest chunk of work, and it's actually what makes the server profiles above even possible! It's always been possible to perform basic lock downs with a custom rewrite file, but we've exposed an amazing built-in functionality of Undertow called the Predicate language. It allows you to create ad-hoc rules that apply to your server to provide any of the following:

Security - Block paths, IPs, or users
URL rewrites - Rewrite incoming URLs to something different
Modifying HTTP requests on the fly - Set headers, cookies, or response codes

An example of a server rule using Undertow's predicate language to block access to any box.json files looks like this:

path-suffix(/box.json) -> set-error(404)

One of the best things about these rules, is they don't have to be in a single monolithic XML file. Instead they can come from

An array of ad-hoc definitions in your server.json file or config server defaults
one or more external JSON or text file specified in your server.json or config server defaults
Built in CommandBox server profiles (see above)
Custom 3rd party CommandBox modules that contribute rules on-the-fly (time to get creative!)

Here's some examples of what can be in your server.json

{
    "web" : {
        "rules" : [
            "path-suffix(/box.json) -> set-error(404)",
            "path-suffix(hidden.js) -> set-error(404)",
            "path-prefix(/admin/) -> ip-access-control(192.168.0.* allow)",
            "path(/sitemap.xml) -> rewrite(/sitemap.cfm)",
	    "disallowed-methods(trace)"
        ],
	"rulesFile" : "../secure-rules.json"
        // Or...
	"rulesFile" : ["../security.json","../rewrites.txt","../app-headers.json"]
        // Or...
	"rulesFile" : "../rules/*.json"
    }
}

CommandBox also registers some custom rules in Undertow you can use for your CF apps:

// Block all CF admin access
cf-admin() -> set-error( 404 ); 

// Shortcut for the previous rule
block-cf-admin() 

// Block external CF admin access
cf-admin() -> block-external()

There are lots of new docs on this. Read more about Server Rules here:

Task Runner Lifecyle events

The more we use Task Runners for builds, scheduled tasks, and utilities, we've seen the need to have lifecyle events in the same manner as the preHandler and postHandler sort of stuff in ColdBox MVC. Now if a task runner has methods of this name, they will be executed automatically.

preTask - Before any target in the task
postTask - After any target in the task
aroundTask - Wraps execution of any target in the task
pre- Before a specific target
post- After a specific target
around - Wraps execution of a specific target
onComplete - Fires regardless of exit status
onSuccess - Fires when task runs without failing exit code or exception
onFail - Fires if exit code is failing after the action is done (always fires along with onError, but does not receive an exception object). Use this to respond generally to failures of the job.
onError - fires only if an unhandled exception is thrown and receives exception object. Use this to respond to errors in the task. Does not fire for interrupted exceptions
onCancel - Fires when the task is interrupted with Ctrl-C

The lifecycle methods are very powerful and can be controlled via whitelist and blacklists to control what targets they execute for. "Around" events are very easy to use thanks to the use of closure. There's a lot more details in the docs.

Read more about Task Runner Lifecyle events here:

System Setting ${} Namespaces

The default namespace when using the $ {foo} system setting expansion syntax is box environment variable, Java system properties, and OS environment variables.

It is also possible to leverage built-in namespaces to allow expansions that reference:

server.json properties
box.json properties
arbitrary JSON file properties
Config settings (like the config show command)
Server info properties (like the server info property=name command)
Other properties in the same JSON file

This gives you a lot more power now to be able to create dynamic configuration in your JSON files and even from the command line. Here are some examples:

// Reference box.json file in this directory
$ {boxjson.slug}

// Reference server.json file in this directory
$ serverjson.web.http.port:80}

// Reference local server details 
$ {serverinfo.serverHomeDirectory}

// Reference arbitrary JSON file
$ {json.myProperty@file.json}

// Reference CLI's config settings
$ {configsetting.endpoints.forgebox.apitoken}

// Local reference to a JSON property in the same file
{
    "appFileGlobs" : "models/**/*.cfc,tests/specs/**/*.cfc",
    "scripts":{
        "format":"cfformat run $ {@appFileGlobs} --overwrite",
        "format:check":"cfformat check $ {@appFileGlobs} --verbose"
    }
}

And one of the coolest things is this implementation is driven by a new onSystemSettingExpansion interception point and completely extendable! That means you can write a module that powers something hypothetical like this:

$ {AWSSecretStore.mySecretKey}

Read more about System Setting namespaces here:

GZip Compression Control

CommandBox has had the ability to enable/disable GZip compression in Undertow for a while. Now you can fully control when it activates based on the type or size of file, etc. This feature utilizes the same Undertow predicate language that we introduced above.

server set web.gzipEnable=true
server set web.gzipPredicate="not path-prefix( admin ) and regex( '(.*).css' ) and request-larger-than(500)"

Read more about GZip Compression Control here:

Generic Watch Command

This is a fun one. There are some specific commands that make use of the Watcher library in CommandBox such as testbox watch and coldbox watch-reinit. However, there is also now a generic watch command that will run any arbitrary command of your choosing when a path matching your file globbing pattern is added/updated/deleted. Use this to build custom watchers on-the-fly without needing to touch any CFML code to write a Task Runner.

watch *.json "echo 'config file updated!'"

That command will echo out "config files updated!" every time a JSON file gets changed in the current directory. Here's a more complex one:

set command = "echo 'You added \$ {item}!'"
watch command="foreach '\$ {watcher_added}' \$ {command}" --verbose

That one will list every new file that's added in this directory and all sub directories.

Read more about the generic watch command here:

Control Default Browser

There are a handful of features in CommandBox that will open URLs for you in your default browser. We've had requests to allow the browser in use to be customized, so we've reworked all of that logic, consolidating it in some places and now you can control what browser CommandBox uses. To change the default browser for all URL opening functions use this:

// use Chrome
config set preferredBrowser=chrome

// use FireFox
config set preferredBrowser=frefox

// Just kidding, no one is going to use this!!
config set preferredBrowser=ie

Supported browsers are:

firefox
chrome
opera
edge (Windows and Mac only)
ie (Windows only)
safari (Mac only)
konqueror (Linux only)
epiphany (Linux only)

And you can even dial in a browser on demand for the browse and server open commands.

server open browser=opera

Read more about setting the default browser here:

Miscellaneous

Here are some honorable mentions.

.htaccess rewrite flags

The CommandBox Tuckey rewrites allow an .htaccess file that uses the mod_rewrite style syntax of rewrites. Previously, use of flags such as these didn't work:L

RewriteRule ^/login.cfm$ /condworks.html [R=301]

Server restart from tray icon

We've added a "restart" option to the tray icon that does exactly what you think it does.

Trick for "cd"ing up directories

There's a new trick supported in CommandBox's shell that we've borrowed that allows you to change directories and go "up" more than one directory with less typing:

// current directory
cd .   -> ./
// back 1 directory
cd ..  -> ../
// back 2 directories
cd ... -> cd ../../
// back 3 directories
cd .... -> cd ../../../

Pipe into standard input of native binaries

You can now pipe the output of a previous command in CommandBox directly to a native binary like so:

#createguid | !clip
or
#createguid | run clip

In this case, clip is a Windows binary that will read the standard input and place that text on the clipboard.

Breaking Changes

We work hard to make every CommandBox upgrade backwards compatible. There's a couple things that you may notice different in this release. They're both done to put security first and can be modified to get your original behavior back.

Since the CF Administrator is now blocked for traffic not coming from localhost when in production mode, you may need to explicitly open up the CF admin to make it accessible again if you needed it open to the public on a production server. Even with the profile set to production, you can activate just the CF admin like so:

server set web.blockCFAdmin=false

The web server built into CommandBox will now only serve static files if their extension is found in a whitelist of acceptable files. This is to prevent prying eyes from hitting files they shouldn't be able to access on your server. The current list of valid extensions is:

3gp,3gpp,7z,ai,aif,aiff,asf,asx,atom,au,avi,bin,bmp,btm,cco,crt,css,csv,deb,der,dmg,doc,docx,eot,eps,flv,font,gif,hqx,htc,htm,html,ico,img,ini,iso,jad,jng,jnlp,jpeg,jpg,js,json,kar,kml,kmz,m3u8,m4a,m4v,map,mid,midi,mml,mng,mov,mp3,mp4,mpeg,mpeg4,mpg,msi,msm,msp,ogg,otf,pdb,pdf,pem,pl,pm,png,ppt,pptx,prc,ps,psd,ra,rar,rpm,rss,rtf,run,sea,shtml,sit,svg,svgz,swf,tar,tcl,tif,tiff,tk,ts,ttf,txt,wav,wbmp,webm,webp,wmf,wml,wmlc,wmv,woff,woff2,xhtml,xls,xlsx,xml,xpi,xspf,zip,aifc,aac,apk,bak,bk,bz2,cdr,cmx,dat,dtd,eml,fla,gz,gzip,ipa,ia,indd,hey,lz,maf,markdown,md,mkv,mp1,mp2,mpe,odt,ott,odg,odf,ots,pps,pot,pmd,pub,raw,sdd,tsv,xcf,yml,yaml

If you have a common static file you need to serve, you can add your own custom extensions to the list like so:

server set web.allowedExt=jar,exe,dll

And if you think we've missed an obvious one that deserves to be added to the default list, please let us know.

Release Notes

Here's the full list of tickets in the 5.2.0-RC.1 release.

Bug

New Feature

Task

Improvement

Sub-task

What's New in 4.2.0

Random Fixes

In no particular order...

Fix background colors not showing up in Powershell and Windows cmd
System Setting expansions not always working in server.json
testbox run no longer blindly assumes you're returning JSON.
Piping commands into box was broken since 4.0.0
Starting server with --debug didn't output logs on error.

Random New Features

Sorted by createUUID() DESC...

Control how many levels deep package list displays
New versions of Lucee, JGit, JLine, and WireBox
More pack200 of the Lucee jar (and more improvements to come soon in the next version of Lucee)

Improvements to Native Binaries

The run command has been a pain over the last few versions as every "fix" has seemed to lead to another regression. We've made some more changes to try and get each use case working as expected with no annoying bash messages about "job control". Fingers crossed.

Single one-off command, streams output to console as it comes.

!ping google.com

Piping output of native binary into another Command (output captured all together and not streamed).

!pwd | #listLast /

Running interactive commands. No output at all really, standard input and output of CommandBox bound directly to native shell

!nano index.cfm

Better Exit Code handling

You can now control the exit code that CommandBox (or your recipe) exits with. Remember, zero is successful, any other number is failure.

exit 123

Access the Exit Code of the previous command via a System Setting expansion of**${exitCode}**.

echo ${exitCode}

Recipes now have better support for exit codes. If a command throws an error OR returns a non-zero exit code, the recipe will stop and the exit code of the last command will be returned as the exit code from the recipe command. And if it was a non-interactive shell, the exit code will flow all the way back to the operating system from the box binary. Also, running "exit" inside of a recipe will no longer exit the entire shell, but just that recipe execution. This give you a lot better control over your recipes.

Command Chaining

Let's take a moment to review an existing but little known feature of CommandBox that we borrowed from bash. This is not new, but you need to know this for the following section to make any sense. Similar to bash, CommandBox allows you to chain multiple commands together on the same line and make them conditional on whether the previous command was successful or not.

&&

You can use && to run the second command only if the previous one succeeded.

mkdir foo && cd foo

||

You can use || to run the second command only if the previous one failed.

mkdir foo || echo "I couldn't create the directory"

;

You can use a single semicolon (;) to separate commands and each command will run regardless of the success or failure of the previous command.

mkdir foo; echo "I always run"

New Assertion Commands

With the above building blocks, we can get clever to create simple conditionals to only run commands if a condition is met. Or these can simply be used to cause recipes to stop execution or to fail builds based on a condition. The following commands output nothing, but they return an appropriate exit code based on their inputs.

pathExists

Returns a passing (0) or failing (1) exit code whether the path exists.

# Only run the package show command if the box.json file exists
pathExists box.json && package show

You can specify if the path needs to be a file or a folder.

# output server.json only if it exists
pathExists --file server.json && server show

# Create the dir foo only if it doesn't already exist
pathExists --directory foo || mkdir foo

assertTrue

Returns a passing (0) or failing (1) exit code whether truthy parameter passed. Truthy values are "yes", "true" and positive integers. All other values are considered falsy

# If this package is private, then run a package script
assertTrue `package show private` && run-script foo

# If this env var is true, then run a command
assertTrue ${ENABLE_DOOM} && run-doom

# Use the boolean output of a native CFML function to control this echo
assertTrue `#fileExists foo.txt` && echo "it's there!"

assertEqual

Returns a passing (0) or failing (1) exit code whether both parameters match. Comparison is case insensitive.

# If the name of our package isn't a specific string, only then set it
assertEqual `package show name` "My Package" || package set name="My Package"

# If this env var is the string "production", then perform a production install of dependencies
assertEqual ${ENVIRONMENT} production && install --production

New S3 Endpoint for Installing Packages

Big thanks to John Berquist and Dominic Watson for helping add this new feature. You can now install packages directly from S3, Amazon S3, Digital Ocean Spaces and Google Disk.

install s3://my-private-bucket/myPackage.zip

There are several different authentications mechanisms available too:

Per bucket credentials in your CommandBox endpoint settings
Global credentials in your CommandBox endpoint settings
Environment variables
AWS credentials file
IAM role

The full docs are here:

Updated Server Tray Menus

We've added 17 pieces of flair to our server tray menus to show you more information such as PID, webroot, and port as well as a new option to open up the web root in your file system explorer.

Release Notes

Here's the full list of everything that changed in CommandBox 4.2.0.

Bug

New Feature

Improvement

What's New in 3.9.0

UNC Network path support

This has been pretty big for Windows users who access files on their servers over a UNC network path like \server-name\foo\bar. You can now cd into paths starting with \, perform file operations like cat against those paths, etc. Note backslashes need escaped in the CommandBox shell.

CommandBox> cd \\\\server-name/share
CommandBox> cd \\\\192.168.123.105/share

This was pretty straightforward since Java already supports this, but I had to change a lot of core path handling to make sure the correct slashes were preserved. This needs a fair amount of testing to make sure we nailed it down for good. If your network share requires permissions, you'll need to have saved those in Windows Explorer already or execute a "net use" OS command from the shell.

Task Runner Improvements

When running a task from the CLI, the user will be automatically prompted if they don't supply all the required args. This is just like commands work now.

CommandBox> task run myTask
Please enter required field "Foo": _

We also fixed several bugs with passing positional parameters and flag to task runners.

# positional
CommandBox> task run taskFileName targetName value1 value2 true
# named
CommandBox> task run taskFile=taskFileName target=targetName :param1=value1 :param2=value2 :param3=true
# Use a Flag
CommandBox> task run taskFileName targetName value1 value2 --:param3
CommandBox> task run taskFile=taskFileName target=targetName :param1=value1 :param2=value2 --:param3

"package link" and "package unlink" for module development

This has been a long time coming, but if you want to work on a CommandBox module now, you don't have to keep copying files over to your CommandBox installation just to test. Instead, just run this from the root of your module's repo:

CommandBox> package link

This will symlink (works on Windows and *nix) your module into the core CLI's modules folder and reload the shell so you can immediately start testing. When you're done, just run package unlink. If you'd like to use this same feature, but to link a ColdBox module's repo over to a test application so you can test it without making a copy, you can pass in the path to the remote modules folder you'd like to link to.

CommandBox> package link /path/to/test/app/modules

This is a little easier than using your OS's native symlink commands and can be used in recipes that will work across operating systems!

Everything Else (mostly)

box install returns failing exit code if a package install fails. This helps builds fail correctly if things go wrong
When prompted to type in something like a missing parameter, your answer is no longer added to the command history
The --debug flag works correctly when starting a server from your OS shell like $> box server start --debug
box.json dependencies are stored with forward slashes so Mac and Windows devs stop fighting over which file to commit
config set no longer prints out the value to avoid leaking secrets in build script output.
Updating a package now uninstalls the previous version first to ensure a fresh start since the new version may have removed files.
If you're setting CommandBox behind an AJP proxy, we exposed the flag and ports for that as first class citizens of server.json.
Visual markers for private packages in the forgebox search command.
The package init command creates a valid slug for private packages in the @user/slug format.
New --local flag to server list to show all servers that have been started in the current working directory
If for some reason you want to supply some ad-hoc JVM args to the actual CLI process, you can create a new environment var called BOX_JAVA_PROPS="foo=bar;brad=wood"
You can now touch files in a non-existent directory and it will create the directory instead of erroring.
Viewing a ForgeBox package via package show with a markdown based description, now has basic formatting in the CLI
The default URL rewrite file doesn't try to rewrite requests to /favicon.ico even when it doesn't exist.
At John Farrar's request, several URLs in output messages have had space put before and after them so capable shells will auto-link them correctly.
Improved the Java networking error messages on server start if the host name wasn't correct in your host file and you were letting CommandBox pick a random port for you.
Prevented unnecessary saves to box.json when installing to keep file updated dates from being touched.
Added friendly check for Java 9 since it's not supported yet and the error that displayed made zero sense.
Commands like forgebox show and forgebox list now can provide their data in JSON format. ex: forgebox show coldbox --json

****

Bug

New Feature

Improvement

What's New in 4.0.0

Major Areas of Development

Major rewrite of CLI engine loader
- Lucee 5 now powers the CLI
- Using JSR-223 to dynamically load Lucee 5
All 3rd Party libs updated
- JGit
- Launch4J
- Runwar
- JLine3
Improved Task Runner support
- Task scaffolding with “task create”
- Task DSL to call other tasks
- Ortus Builds are now being converted to Task Runners. No Ant! No XML!
Support for Private package
Revamped Server Logs (access, rewrite, console)
ColdBox 5 updates
Tons of bug fixes and improvements

Featured Enhancements

256 Color support

system-colors

CLI Improvements

Along with the newest version of JLine, there's a ton of nice little things now available in CommandBox 4. The first is a totally revamped tab completion interface. Pressing Tab is now prettier, colored, and more organized. Help is integrated right into the interface, and pressing tab repeatedly will cycle through the available options instead of redrawing the screen over and over.

Next is color coding when you type commands in the shell. This make it much easier to tell when you've typed the name of a command correct and makes the difference between the command and parameters easier on your eyes.

Finally is tab complete and syntax highlighting in the REPL. You can tab complete any CFML function as well as previous variable names you've typed. Common CFML keywords are highlighted, as well as CFML functions and there's even color coded matching of braces, parens, and quotes as you type.

Shell History

There are two new features in the shell's history. Pressing "up" will still show the previous items in your history. But typing a partial command like "cd" and THEN hitting up will jump to the most recent histories that start with that word. Very handy to find that one "coldbox create..." command you ran two days ago.

The second new history feature is known in the bash world as i-search. Press Ctrl-Shift-R to open a search from the console where you can search your entire command history by keyword. Keep pressing Ctrl-Shift-R to cycle backwards through the results. Press Ctrl-Shift-S to cycle forwards through the results. Press enter to run the matched search select, or edit it inline before running it.

CommandBox Bullet Train

There's a new CommandBox module available called "commandbox-bullet-train" which makes the CLI look super sleek and sexy. You can add it very easily with:

install commandbox-bullet-train

You'll want to install a powerline-patched font as well. Check out the instructions under the "Fonts" section in the readme.

And is that some sweet new ASCII art taking advantage of 256 colors as well as a randomized quote/tip on every shell start? Why yes, yes it is!

Interactive Inputs

Interactive Jobs

Some of the more wordy tasks you perform like installing packages and starting servers have gotten a big makeover in how they reveal their output to you. If an installation fails, you want to know about it, but so long as everything worked, you usually don't care. These actions will now scroll the last few active log entries past in a controlled format, but hide them at the end so the shell stays much cleaner, even when installing dozens of packages at once.

As an example, installing CFConfig actually installs 9 separate packages. This used to output around 100 lines of console logging which no one in their right mind ever read. All the same logging is still there, but now by the time it's done, this is all you see:

> install commandbox-cfconfig --force
 ✓ | Installing package [forgebox:commandbox-cfconfig]
   | ✓ | Uninstalling package: commandbox-cfconfig
   | ✓ | Installing package [forgebox:cfconfig-services@be]
   |   | ✓ | Installing package [forgebox:lucee-password-util@^1.0.0]
   |   | ✓ | Installing package [forgebox:adobe-password-util@^1.0.0]
   |   |   | ✓ | Installing package [forgebox:propertyFile@^1.0.0]
   |   | ✓ | Installing package [forgebox:propertyFile@^1.0.7]
   |   | ✓ | Installing package [forgebox:semver@^1.0.0]
   |   | ✓ | Installing package [forgebox:JSONPrettyPrint@^1.2.6]

If you want to troubleshoot, or you are running this install as part of a build and you want to see all this output later, just use the --verbose flag. For server starts, using the --debug flag will preserve all your precious log output on the screen after the server starts.

Even cooler, the Interactive Job interface is fully documented and available for you to use in your Task Runners or Custom Commands.

Docs:

Example:

job.start( 'Starting server' );
  job.addLog( 'This is the server name' );
  job.addWarnLog( 'Hey, don''t touch that dial' );

    job.start( 'Installing CF Engine first' );
      job.addLog( 'This was the version used' );
      job.addLog( 'Yeah, we''re done' );
    job.complete();

  job.addLog( 'Aaand, we''re back!.' );
  job.addErrorLog( 'I think we''re going to crash' );

job.error( 'Didn''t see that coming' );

Which looks like this when it's done:

Server Logs

We did a lot of work to make dealing with servers easier-- especially when it comes to your log files. Console starts and tailing server logs are now color coded so it's easier to find errors and warnings.

We've also fine tuned what information shows up when you do --console starts as well as --debug starts to reduce the noise and enhance the useful information. For instance, when you do:

server start --rewritesEnable --console --debug

You'll see a line of debug logging that shows if the URL rewrites kicked in and what the URL was rewritten to. How useful is that?!

Remember you can view and tail the server "out" logs like so:

server log
server log --follow

Access Logs

The built in Undertow web server that CommandBox uses just got more powerful. You can turn on access logs that show you every incoming HTTP request in the same "common format" as Apache web server.

server set web.accessLogEnable=true

You can view and tail this log file like so:

server log --access
server log --access --follow

URL Rewrite Logs

But wait, there's more logging goodness. Troubleshooting rewrite rules can be really tricky. That's why we broke out a new separate log file just for Tuckey Rewrites to dump into. You can dial in how much information you get with --debug and --trace server starts.

server set web.rewrites.logEnable=true

You can view and tail this log file like so:

server log --rewrites
server log --rewrites --follow

Automatic Log Rotation

CommandBox web servers are truly ready for prime time. All the Undertow log files above automatically rotate which means you'll never fill up a hard drive on accident due to out of control log files.

Version Checks on Startup

Another optional module you can install is the CommandBox update check module. It will check every 24 hours (when starting the shell) and let you know if your CLI or any of your system modules are out of date.

install commandbox-update-check

Pipe output of native OS binaries

This used to work back in the day, but was a regression back when I added the ability to interact with native binaries. Now you have the best of both worlds.

!java -ver | #ucase

Task DSL

Running other tasks from inside of Task Runners is now easier. Docs:

Example:

task( 'build' )
    .run();

(Same as running "task run build" from the CLI)

Actual Proper Non-Sucking Ctrl-C and Ctrl-D support

You can now cancel long running commands, tasks, and even HTTP downloads by pressing Ctrl-C. Yay! Pressing Ctrl-C from the prompt does nothing, which is consistent with other shells. Pressing Ctrl-D from the shell will now exit CommandBox entirely which is also consistent with other shells. In case you're wondering, Ctrl-C fires the interrupt terminal signal, and Ctrl-D sends the EOF (end of file) signal.

Docs:

Load ad-hoc jars for Task Runners

You can now load ad-hoc jars right from Task Runners which is sometimes necessary for working with Java libs. Docs:

Examples:

classLoad( 'D:/amqp-client-5.1.2.jar' );
classLoad( 'C:/myLibs,C:/otherLibs' );
classLoad( [ 'C:/myLibs', 'C:/otherLibs' ] );
classLoad( 'C:/myLibs/myLib.jar,C:/otherLibs/other.class' );
classLoad( [ 'C:/myLibs/myLib.jar', 'C:/otherLibs/other.class' ] );

Task Scaffolding

Wanted to play with Task Runners but not sure where you start? Drop everything, grab the closest CommandBox 4 CLI, and run these two commands:

task create --open
task run

You just created a new task and ran it. Go on, look around!

Updated Directory Listing

Directory listings have gotten a makeover. The columns actually align, the file sizes are human-readable, and the file types are color coded. Be careful, you might actually be able to find stuff now!

ASCII Art Stereograms

If you remember the "Magic Eye" books from your childhood, you'll be pleased to know CommandBox has an ASCII Art Stereogram for every day of the month. You'll find it hiding inside the info command. The "image" will change every day at midnight.

    _( )          _( )         _( )          _( )        _( )
  _( )  )_      _( )  )_     _( )  )_      _( )  )_    _( )  )_
 (____(___)    (____(___)   (____(___)    (____(___)  (____(___)


   /\          /\           /\          /\         /\
  /  \  /\    /  \  /\     /  \  /\    /  \  /\   /  \  /\
 /    \/  \  /    \/  \   /    \/  \  /    \/  \ /    \/  \
           \/          \ /          \/          /          \/
   ..        ..        ..         ..        ..         ..
"        "         "        "         "         "        "
    *       *        *       *        *       *       *       *
  @     @      @     @      @      @     @      @     @     @
 \|/   \|/    \|/   \|/    \|/    \|/   \|/    \|/   \|/   \|/

If you keep looking like that, your face will freeze that way!

Known Breaking Changes

We tried very hard to keep CommandBox 4 compatible but there are a few things that might surprise you.

The REPL and Task Runners run against Lucee 5.2.7 instead of 4.5.5. That might affect valid CFML syntax as well as datasource definitions
The default server you get when you type "server start" is also Lucee 5.2.7, not Luce 4.5.5.
Java 7 support removed. This affects both the core CLI as well as any servers. For CF9 users, you can still run CF9 servers but you'll need to use an older version of Java 8 such as 1.8.0_92. (Note: Java 9 and 10 don't work yet!)
Native CFML execution via box foo.cfm now routes through the "execute" command which means no Application.cfc will get run. You can refactor your cfm scripts or use the undocumented _internalRequest() function in Lucee 5.
CommandBox 4 is prettier, more productive, and cooler than CommandBox 3. This may cause CLI envy with your Node coworkers. Don't worry, this is normal.

Bug

Story

New Feature

Improvement

What's New in 3.3.0

Server Enhancements

The embedded CommandBox server have seen a number of nice enhancements to make it easier for you to use CommandBox for super easy local development.

Fusion Reactor Module

install commandbox-fusionreactor
fr register "your FR license key"
server start
fr open

Web Aliases

CommandBox allows you to create web aliases for the web server that are similar to virtual directories. The alias path is relative to the web root, but can point to any folder on the hard drive. Aliases can be used for static or CFM files. To configure aliases for your server, create an object under web called alises. The keys are the web-accessible virtual paths and the corresponding values are the relative or absolute path to the folder the alias points to.

Here's what your server.json might look like.

{
  "web" : {
    "aliases" : {
      "/foo" : "../bar",
      "/js" : "C:\static\shared\javascript"
    }
  }
}

Here's how to create aliases from the server set command:

server set web.aliases./foo = bar

Custom Error Pages

You can customize the error page that CommandBox servers return. You can have a setting for each status code including a default error page to be used if no other setting applies. Create an errorPages object inside the web object in your server.json where each key is the status code integer or the word default and the value is a relative (to the web root) path to be loaded for that status code. This is what you server.json might look like:

{
  "web" : {
    "errorPages" : {
      "404" : "/path/to/404.html",
      "500" : "/path/to/500.html",
      "default" : "/path/to/default.html"
    }
  }
}

You can set error pages via the server set command like this:

server set web.aliases.404=/missing.htm

You can customize these tray menus and add your own option for your convenience. To add a menu contribution to an individual server, add the following to your server.json:

{
  "trayOptions":[
    {
      "label":"Foo",
      "action":"openbrowser",
      "url":"http://${Setting: runwar.host not found}:${Setting: runwar.port not found}/foobar.cfm",
      "disabled":false,
      "image":"/path/to/image.png"
    }
  ]
}

We've updated to a new library that creates the tray icon for your running servers and the menu that appears when you right click. In addition to better support for some Linux distros, we've added some nice new icons to the menus.

Pre/Post package scripts

Before any package script is run, CommandBox will look for another package script with the same name, but prefixed with pre. After any package script is run, CommandBox will look for another package script with the same name, but prefixed with Post. So if you have a package that contains 3 package scripts: foo, preFoo, and postFoo, they will run in this order.

preFoo
foo
postFoo

This works for built-in package script names as well as as doc package scripts. It also works on any level. In the example above, if you created a 4th package script called prePreFoo, it would run prior to preFoo.

If you use more than one ForgeBox login, perhaps a personal one and a company one, it can be a pain to keep logging in. It's also hard to remember the last user you logged in with. We've introduced two new commands to help with this. Run this to tell you who you are logged in as:

forgebox whoami

Run this to switch between users that you've previously logged in with:

forgebox use myUser

onRelease interceptor/package script

We've added a new "onRelease" interceptor and package script to help with the workflow of publishing packages. Here's a run down of the three key points when bumping a package version.

preVersion - Announced before the new version is set using the bump command
postVersion - Announced after the new version using the bump command but before the Git repo is tagged.
onRelease - Announced after a new version is set using the bump command and after the Git repo is tagged.

Here is a typical package script work flow for working with a package that's hosted on GitHub and published to ForgeBox:

"scripts":{
  "preVersion":"testbox run",
  "postVersion":"package set location='gituser/repov#`package version`'",
  "postPublish":"!git push --follow-tags"
}

Then when you want to publish a new version of your package, commit your changes to Git and run the following commands:

bump --minor
publish

Those two commands, in combination with your package scripts, would accomplish the following:

Run the package's test suite (a failure will abort the process)
Increase the minor version of the page
Tag the Git repo
Change the package's location property in box.json to point to the new tag
Commit the tag and new box.json
Publish the package to ForgeBox
Push the new box.json and Git tag

onInstall interceptor/package script

Announced while a package is being installed, after the package endpoint and installation directory has been resolved but before the actual installation occurs. This allows you to override things like the installation directory based on package type. Any values updated in the interceptData struct will override what the install command uses.

CLI Engine Update

The Lucee version that the CLI runs on has been updated to be 4.5.3.020 which is also now the default engine to be used when you use the "server start" command and don't specify a cfengine. If you still want to start a web server on Lucee 4.5.2.018, then simply to this:

start cfengine=lucee@4.5.2+018

Release Notes

There are tons of little bug fixes in this version that you can view in our release notes.

Bug

New Feature

Improvement

What's New in 3.5.0

CLI Shell

We upgraded to a new version of the underlying library that handles the CLI interactions which brought a number of nice things.

The cls command now clears background colors that used to be left on the screen
Tab completion works better when two folders with different case were in the same directory
When developing commands, default text can be placed in the buffer when asking the user for input.
Fixed some instances where undesired spaces would get added when hitting tab completion

We also made the following improvements to the CLI shell environment

You don't need to escape an equals sign that's part of a quoted parameter value
Removed extra line break when piping the output of the "run" command
Fixed some regressions when piping text to the box binary
Added better BOM detection when tailing files
cp command will create destination directories
Windows paths that start with \ or / will be treated as absolute (like DOS works)
All OS's will expand ~ to the current user's home directory

Tail Command

The tail command used to only take a file as input, but now you can pipe raw text in as well.

CommandBox> forgebox search | tail lines=50

When tailing a file, you can specify the --follow flag and any new text added to the file will live stream to your console until you press Ctrl-C to stop. This is perfect for tailing application logs while your code is running to see new entries.

CommandBox> tail myFile.log --follow
CommandBox> system-log | tail --follow

The server log command also has a new --follow flag added to it which will live stream a running server's console log to the shell until you press Ctrl-C to stop it.

CommandBox> server log --follow

Package Management

The artifact storage location is now customizable thanks to Chris Schmitz, allowing you to store your artifacts on another drive, or even a network share so your coworkers can all use the same "local" copies.

CommandBox> config set artifactsDirectory=/path/to/artifacts

CommandBox will always re-download snapshot versions of packages to make sure you get a fresh version.

CommandBox> install myPackage@1.2.3-snapshot

When you try to install a package and CommandBox is offline, instead of giving up, we'll now look in your local artifacts cache for a satisfying version. If we find a package that works in your artifacts, we'll install it instead.

Server Starting

We added a few new ways to start up a server. You can use the --debug flag when starting a server to see additional information and the foreground process also waits for the server to start before finishing. Now when starting in debug mode this output will stream to the console as it becomes available instead of showing up all at the end. This is great to troubleshoot errors that are happening on server start as well as finding the slow parts of the startup sequence.

CommandBox> server start --debug

By default, your servers fire up in a new process that runs independently from the CLI. There is now a new flag called --console that will start the server up in the foreground and stream the console output to the CLI for you to watch. The start command will not end and will keep streaming the console output until you press Ctrl-C to stop it. You can also use --debug alongside the console flag for even more information.

CommandBox> server start --console
CommandBox> server start --console --debug

Server Welcome Files

If you have an app that uses a default welcome file other than index.cfm, you can control that now.

CommandBox> server set web.welcomeFiles="go.cfm,main.cfm,index.cfm,index.html"

Better SES URLs

This is one that you take for granted if you've always used Adobe ColdFusion, but for any CF server not running on Adobe's custom version of Tomcat, you can't use SES URLs in a subfolder like this without adding custom mappings to your web.xml:

site.com/myFolder/index.cfm/home/login

Server Configuration

All server engines and versions have been standardized to install into the same reliable directory structure to make it easier for you to script config file replacements.

For Adobe CF WARs, the xml config files are located in the WAR here: /WEB-INF/cfusion/lib/neo.*.xml
For the Lucee server context, the xml config file is located in the WAR here: /WEB-INF/lucee-server/context/lucee-server.xml
For the Lucee web context, the xml config file is located in the WAR here: /WEB-INF/lucee-web/lucee-web.xml.cfm

To find the folder where your WEB-INF lives (as well as lots of other information about your server) you can use the server info command to get useful properties about a starting or started server.

# Find the "home" directory for a server (where the WEB-INF lives)
CommandBox> server info property=serverHomeDirectory

# Find the out log file
CommandBox> server info property=consoleLogPath

# Get all possible values as JSON
CommandBox> server info --JSON

CommandBox> cp neo-datasource.xml '`server info property=serverHomeDirectory`/WEB-INF/cfusion/lib/neo-datasource.xml'

Custom Server Home

Customize Lucee's server context folder with the serverConfigDir setting
Customize Lucee's web context folder with the webConfigDir setting
Customize where the entire WAR explodes to for any server with the serverHomeDirectory setting

This is very powerful since it gives you full control over the server deployment. Server installs have also been changed to NOT overwrite existing files when they unzip, so any config files you place in the server home prior to starting the server will be left in place and used by the server when it starts up. This means you can have datasources, mappings, and more start out-of-the-box for your site on a fresh install.

A Few Changes

There were a few small changes in the "undocumented" core of CommandBox that got rearranged to make more sense. There's a small chance you may have been relying on one of them, so take note:

The serverHome property that comes back from server info has been renamed to serverHomeDirectory.
The webConfigDir property used to point to the server home, but this was incorrect. The property will now be blank unless specified. Use serverHomeDirectory instead.
The default Lucee server used to have a non-standard folder structure, but now matches the WAR folders of all other servers
The web context in Lucee servers used to be in a folder named after a random hash which was kind of silly (and impossible to find). It's now always under /WEB-INF/lucee-web
All "internal" Lucee servers used to share a single server context (and settings). All servers are now separate. Use the serverConfigDir setting to point more than one server at a single server context or use one of the new options for copying configs.
The core CLI server context now has a default password of "commandbox" set. This would apply if you wanted to use the tag from .cfm files executed via the shell or a custom command.
Several new properties were added to the server info data for your convenience. Check them out by starting a server and running server info --JSON.

Release Notes

Bug

New Feature

Improvement

What's New in 3.0.0

Config Settings

CommandBox now has a JSON file of settings that can be used to configure any kind of behavior we want. We're still working on implementing features that actually use the settings, but the first will be the ability to set up a proxy server for your corporate network. Config settings give us a place to store ad-hoc settings like this as well as an API for retrieving them. What's great is the settings JSON file can store ANY information, including complex structs and arrays so feel free to use it for your own purposes as well. You can interact with config settings like so:

Modules

Not only can modules have settings, but you can also override a module's default settings easily with config settings that follow a simple convention. For example, if a module named "foo" has a setting named "bar", you don't need to edit the module's code to change the setting. Simply run this command:

Interceptors

Here's some of the core interception points:

onCLIStart
onCLIExit
preCommand
postCommand
onServerStart
onServerStop
onException
preInstall
postInstall

Now you can write modules that check for upgrades on CommandBox startup, manipulate the output of commands, log exceptions, customize server startup, or audit what package you install the most!

Standardized Command Packaging

We've had the ability for custom commands for a while, but they were limited and didn't easily allow you to include additional CFC files with your commands. Now with the addition of modules, your custom commands can be package in a module right alongside settings, interceptors, or services. We also simplified the creation of custom commands so things like extending our BaseCommand class is optional thanks to WireBox's virtual inheritance. We hate boilerplate as much as you do!

Server.json

This feature has been a long-time coming. There are a lot of options you can set when starting a server, and portability has been hard for people wanting to distribute an app that needs to start with custom JVM args, rewrites, or a specific port. Now all server startup options can be set in your web root in a server.json file which will be used automatically the next time you run "start". You interact with these settings the same as package or config settings.

Shortcut for Native OS Binaries

We've had the "run" command for a while now that allows you to run native binaries from the interactive shell, or from a CommandBox recipe. The output is returned which allows you to create mashups that pipe the output of OS commands directly into CommandBox commands. We took this a step further and borrowed from other CLIs out there so now the parser allows you to call native OS binaries by simply prefixing an exclamation mark (!) in front of the binary name. Now only are OS commands run in the current working directory, they are also executed via the shell for that machine which makes non-binaries and aliases like "ll" function.

Shortcut for CFML Functions via REPL

This is a really neat feature that allows you to actually run CFML functions straight from the CommandBox CLI as commands. Just prefix the function name with a hash sign (#) and then type the function name with no parenthesis. Any parameters to the function can be passed (or piped) into the command like normal named or positional CLI command parameters.

This really gets cool when you start piping the output of commands together to string together mixtures of CommandBox commands and CFML functions for fancy one-liners. Here's some string manipulation. The first one does some list manipulation. The second one outputs the lowercase package name.

But wait, there's more! You can even use struct and array functions. Their output is returned as JSON and automatically deserialized as input to the next command. Keep in mind that piped data gets passed in as the FIRST parameter to the next command. This outputs a nice list of all the top-level dependencies in your package.

Expressions in Command Parameters

Parameter values passed into a CommandBox command don't have to be static. Any part of the parameter which is enclosed in backticks (`) will be evaluated as a CommandBox expression. That means that the enclosed text will be first executed as though it were a separate command and the output will be substituted in its place.

You can really go crazy with these mashups by combining CFML functions too. This example sets a property in a package's box.json that's equal to a nicely formatted date:

Command DSL

We've really focused on doing CommandBox development now with the possibilities opened up with the addition of modules. One pain point of extending CommandBox was calling other commands since parameters needed to be escaped. We created a nice method-chaining DSL to help execute any other command from inside of your custom commands.

You can even nest the DSL to pipe output between commands:

New WireBox Injection DSLs

In line with the previous item, we've made it yet easier to write custom modules that extend the functionality of CommandBox by adding new WireBox injection DSLs. Everything inside of CommandBox is created and autowired by WireBox. You can now ask WireBox to inject core services, module settings, or config settings.

Release Notes

Bug

New Feature

Task

Improvement

What's in 1.0.0

CommandBox

CommandBox is a standalone, native tool for Windows, Mac, and Linux. It provides a Command Line Interface (CLI) for developer productivity, tool interaction, package management, embedded CFML server, application scaffolding, and some sweet ASCII art. It includes a plethora of commands to interact with your Operating System, TestBox, ForgeBox, ContentBox, CacheBox, etc. Built-in help is completely integrated for every command. You can pop open a CommandBox shell in your terminal window and manually type commands, or even automate things externally via the CommandBox binary with your OS's native shell.

Package Management

So one of the biggest things we think the CFML community was missing, was a true package management platform. With this in mind, CommandBox + ForgeBox now includes full package management control for ANY ColdFusion (CFML) application. We have created a spec for a box.json file which will go in the root of CFML packages to describe metadata about the package, how it should be installed, and dependencies that the package requires to run. CommandBox is getting a tight integration with the ForgeBox REST API to search, view, and install packages/modules directly into your app from the command line.

REPL: Read-Evaluate-Print-Loop

The CommandBox CLI also leverages a REPL console for executing a-la-carte CFML commands. You can use it in script or even tag mode with full command history as well. Each REPL instance also has included memory, which means you can declare functions, datasources, etc and leverage them within the same command executions. We even support multi-line statements.

Application Scaffolding

CommandBox has tons of commands for quickly building out applications. Create a new ColdBox app with coldbox create app, add a handler with coldbox create handler. You can even get actions added to it, views created, and BDD integration tests stubbed out at the same time. This can bring new productivity for people who like to live on the command line and especially for those who want to be able to automate stuff they do a lot of.

Extensible

Automation

Embedded Server

One of the cool things CommandBox brings to the table is the ability to spin up an ad hoc, lightweight, CFML server in any directory from the command line. Simply change your working directory to the root of your app, type server start and a super fast CFML server spins up on a new port running your code. When you're done type server stop from that directory or use the little icon that's showed up in your system tray.In our final release we even included SSL and full URL rewrite support as well.

Auto Updates

We have spent considerable time in our auto-update capabilities so users can transition to patches and updates with ease. We have even created two channels for updates:

Stable : Stable releases
Bleeding Edge : Bleeding edge releases

So from you console you can type: box upgrade --latest for bleeding edge releases or box upgrade for stable releases.

Future RoadMap

In the next coming months, ForgeBox 2.0 will be released with many more features to help developers manage their contributions, multiple version control, CommandBox integration, private repositories and much more. We will also be using the URL forgebox.io instead of embedding it in the ColdBox site; time for separation. We also have tons of features planned for CommandBox, here are a few teasers:

Adobe CF embedded server
Task Runner
NodeJS bridges
Lucee Support
Multiple installation providers
ForgeBox Enterprise (For private enterprise installations)
ForgeBox Cloud Private Entries
RCE (Let's see if you can figure out the acronym)
Multiple version and fuzzy version package management
WAR packager
Package signing
Much More

Getting Started Guide

Congratulations on your choice of CommandBox, the next generation of CFML productivity tooling! We're pleased you've chosen this product and we can't wait to help you get started with it. Setup is easy and painless. We'll walk you through the steps you need to become the jealous rage of your peers with the class of a Java guru, the hipster appeal of a Rubyist, and the ASCII art fetish of a Node.js developer.

Your CommandBox download was quality checked and shipped from our integration server with the following items. You'll want to check the contents of the package to ensure you received everthing.

CLI
Package Manager
Embedded CFML Server
REPL
Built-in Help
ASCII Art

1. Download

If you don't already have CommandBox in hand, download it from the product page on the Ortus Solutions site:

If you already have Java 1.8 or higher installed on your PC, choose the No JRE Included download for your operating system. Otherwise, you can grab the With JRE Included for a single-download solution.

You're well on your way now. While you wait for arrival you might want to secure any loose hair or shirt sleeves and clear a clean space to work on your desktop. Safety first!

2. Unzip & First Run

Your CommandBox is sent to you via a zip archive. Decompress the archive to a location of your choice. The No JRE Included download will only have one file in it named box. For Windows users, this will be an exe file. For unix-based users, it will be an executable binary. The With JRE Included version will have a jre folder. You can move box.exe, but keep the jre folder in the same relative location as the executable so it can be found.

Now just double click the file from your GUI, or execute it via a console window. This will start a short, quick, one-time process of unpacking CommandBox into your user's home directory. Congratulations, CommandBox is now installed! You'll still run the same executable binary every time you want to use the CLI, but the extraction process won't need to happen again.

The green CommandBox> prompt is what we call the interactive shell. Type exit to close the window or be returned to your OS's native shell.

3. Setup & Usage

To open up the interactive shell at any time, just double click on the box executable. If you prefer to stay in your OS's native shell, then just place the box file in your system path and add it before any CommandBox commands like so:

C:\ > box version
CommandBox 1.2.3.00000
C:\ > _

The rest of this guide, however, will assume you're sitting at the interactive shell, where you can enjoy cross-platform command consistency, custom history, and tab completion.

The first command you'll want to try out is help. Type it after a command, or even a partial command to get context-specific assistance. Check out the help for the version command and then run it to see what you get.

CommandBox> version help

Now, let's see if your installation is up to date with the upgrade command:

CommandBox> upgrade

Looking good. Let's try a bit of CFML code from the REPL, shall we? Type the repl command to be dropped into the REPL prompt.

CommandBox> repl
Enter any valid CFML code in the following prompt in order to evaluate it and print out any results (if any)
Type 'quit' or 'q' to exit!
CFSCRIPT-REPL: _

Type these lines one at a time and press enter to see what you get.

fruits = [ 'apples', 'oranges' ]
fruits.append( 'bananas' )

( fruits.len() ? 'Start eating!' : 'Time to run to the store' )

for( fruit in fruits ) {
  echo( fruit & chr(10) )
}

When you're done, just type quit to exit the REPL. How does it feel to master CFML from the command line?

Package Manager

It's about time we did something useful. CommandBox allows you to install stuff and it makes it really easy. You now have ForgeBox on speed dial. Let's create a little playground to experiment in. Adjust these paths accordingly for Unix-based OS's.

CommandBox> mkdir C:\playground
CommandBox> cd C:\playground

I wonder how many projects Luis Majano has posted on ForgeBox. We can look with the forgebox search command: Hint, try pressing tab while typing a command for auto-completion.

CommandBox> forgebox search Luis

Wow, that Luis guy is busy! Let's install the the ColdBox MVC Platform. Don't worry, this won't hurt a bit.

CommandBox> install coldbox

We can create a skeleton ColdBox app really easy with the ColdBox generator commands. Let's give them a try:

CommandBox> coldbox create app MyApp

Embedded Server

Now that we have a nifty little test app, let's give it a spin. Wait, you don't need to install a CF server, CommandBox has one built in! You can start up an ad-hoc server in any folder on your hard drive simply by typing start. It really couldn't be any simpler.

CommandBox> start

In a few seconds, a browser window will appear with your running application. This is a full server with access to the web administrator where you can add data sources, mappings, or adjust the server settings. Notice the handy icon added to your system tray as well. You can even edit the files in your new site from the command line:

CommandBox> edit views/main/index.cfm

When you're done playing, just shutdown your server with the stop command. It will save all of its settings for the next time you start it. Feel free to delete the playground directory at any time. It won't break a thing.

CommandBox> stop
CommandBox> cd ../
CommandBox> rm playground --recurse --force

Next Steps

Non-Oracle JREs

In the past, 99% of people used the Oracle (previously SUN) version of Java for all their Java needs. As of January 2019, the license is changing on Oracle Java which makes it no longer free for commercial use as well as the end of updates for Java 8. This has led to many people looking at alternatives to Oracle. Java itself is open source, so it will always be free and there are several other organizations offering their own builds of Java. If you want support, it matters which provider you get Java from.

This page is a work in progress to track the non-Oracle JREs and how to use them. Please send pull requests to this page with any additional information you have as this is a changing landscape right now.

You can read more about Oracle's changes in this post:

Amazon Corretto

Corretto is a build of OpenJDK maintained by Amazon. It is free and will have long term support. Initial tests show that Corretto 1.8 works with CommandBox and ACF 11.

OpenJDK

OpenJDK is Oracle's free version of Java. it comes with a 6 month support window. CommandBox has received a fair amount of testing on OpenJDK and everything seems to work.

Azul Zulu

Zulu is free and offers long term support. Zulu provides supported builds of OpenJDK. Initial tests show that Corretto 1.8 works with CommandBox and ACF 11.

Installing on Windows

When running box.exe on Windows, the registry is used to determine the current versions of java that are installed. If you install a some non-Oracle JRE such as Corretto, you will not currently have the necessary registry entries created for box to find Java.

Oracle - No manual action needed
Azul - No manual action needed
OpenJDK - Manual creation of registry keys required
Corretto - Manual creation of registry keys required

You can manually create the needed keys by modifying and running the following registry entries. (Contributed by Jim Pickering)

JavaSoft-Registry-Keys.reg

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft]

[HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Development Kit]
"CurrentVersion"="8.0.192"

[HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Development Kit\8.0.192]
"JavaHome"="C:\\Program Files\\Amazon Corretto\\jre8"
"RuntimeLib"="C:\\Program Files\\Amazon Corretto\\jre8\\bin\\server\\jvm.dll"

Installing on *nix

The box binary on *nix uses your OS environment variables to locate Java. In the absense of an env var called JAVA_HOME, box will look for java in the default system path.

Oracle - No manual action needed
Azul - No manual action needed
OpenJDK - Manual creation of JAVA_HOME required
Corretto - Manual creation of JAVA_HOME required

To manually configure the JAVA_HOME env var on a *nix system, edit your /etc/profile file to have these lines. Adjust the path as necessary based on your installation.

export JAVA_HOME=/opt/ibm/java-x86_64-60/
export PATH=$JAVA_HOME/bin:$PATH

The JRE Folder

And as always, on any operating system and with any JRE provider, you can override what version of java is used by creating a folder called JRE in the same directory as the box or box.exe binary that contains the JRE you wish CommandBox to use. This will bypass all registry and env var checks above.

If you want to debug what JRE is being used by the CommandBox CLI, use the -clidebug flag when starting CommandBox and the first few lines will tell you what version of Java is being used, and where on disk it lives.

Execution

There are two ways to run commands via CommandBox: inside the CommandBox interactive shell, or one-at-a-time commands from your native shell.

Multiple Commands

C:\>box.exe

   _____                                          _ ____            
  / ____|                                        | |  _ \           
 | |     ___  _ __ ___  _ __ ___   __ _ _ __   __| | |_) | _____  __
 | |    / _ \| '_ ` _ \| '_ ` _ \ / _` | '_ \ / _` |  _ < / _ \ \/ /
 | |___| (_) | | | | | | | | | | | (_| | | | | (_| | |_) | (_) >  < 
  \_____\___/|_| |_| |_|_| |_| |_|\__,_|_| |_|\__,_|____/ \___/_/\_\  v1.2.3.00000

Welcome to CommandBox!
Type "help" for help, or "help [command]" to be more specific.
CommandBox> version
CommandBox 1.2.3.00000
CommandBox> pwd
C:\
CommandBox> echo "Hello World!"
Hello World!
CommandBox> exit

C:\>

One-Off Commands

You can also spin up CommandBox from your native shell to execute a single command inline. You can do this if you only have one command to run, or you want to automate a command from a Unix shell script or Windows batch file. This mode will not show the ASCII splash screen, but keep in mind it still loads CommandBox up and unloads it in the background. Any output from the command will be left on your screen, and you will be returned to your native OS prompt.

Here is an example of running the version command from a Windows DOS screen. Note, you'll need to either do this from the directory that holds the box executable, or add the executable to your default command path so it is found.

C:\>box version
CommandBox 1.2.3.00000

C:\>

The box text is calling the CommandBox binary, and the version bit is passed along to the CommandBox shell to execute once it loads.

Debug Mode

You can also activate CommandBox in debug mode by passing the -clidebug flag in the command line. This will give you much more verbose information about the running CommandBox environment. This only one-off commands

box -clidebug

Output

Output from commands will be ANSI-formatted text which, by default, streams directly to the console. When in the interactive shell, you can capture the output of commands and manipulate it, search it, or write it to a file. Use a pipe (|) to pass the output of one command into another command as its first input. Output can be piped between more than one command. Use a right bracket (>) and double right bracket (>>) to redirect output to the file system.

Search

cat myLogFile.txt | grep "variable .* undefined"

Pagination

forgebox show | more

Redirection

Redirect output into a file, overwriting if it exits like so:

dir > fileList.txt

Use the double arrows to append to an existing file.

echo "Step 3 complete" >> log.txt

Tail files

You can pipe a large amount of text or a file name into the tail command to only output the few lines of the text/file. Adding the --follow flag when tailing a file will live-stream changes to the file to your console until you press Ctrl-C to stop.

forgebox search luis | tail
system-log | tail lines=50
tail myLogFile.txt --follow

Ad-hoc Java properties for the CLI

If you want to add ad-hoc Java Properties to the actual CLI process, you can set an environment variable in your OS called BOX_JAVA_PROPS in this format:

BOX_JAVA_PROPS="foo=bar;brad=wood"

That would create a property called foo and a property called brad with the values bar and wood respectively. This environment variable works the same on all operating systems.

Ad-hoc JVM args for the CLI

Similar to above, you may want to add ad-hoc JVM args to the java process that powers the CLI. The steps differ per operating system. For *nix (Linux, Mac), set an environment variable called BOX_JAVA_ARGS in the environment that box will run in.

BOX_JAVA_ARGS="-Xms1024m -Xmx2048m -Dfoo=bar"
box

For Windows, create a file called box.l4j.ini in the same directory as the box.exe file and place a JVM arg on each line. Escape any backslashes with an additional backslash like a properties file format.

box.l4j.ini

-Xms1024m
-Xmx2048m
-Dfoo=bar

Both of those examples would set the min/max heap size of the CLI process and also set a Java System Property called "foo" equal to "bar". There is no effective difference between setting system properties this way as opposed to using BOX_JAVA_PROPS as shown in the previous section, but actual JVM -X settings must be set as described in this section.

Noninteractive Mode

If you are using CommandBox in a continuous integration server such as Jenkins or Travis-CI, you may find that features like the progress bar which redraw the screen many times create hundreds of lines of output in the console log for your builds. You can enable a non interactive mode that will bypass the output from interactive jobs and the download progress bar.

config set nonInteractiveShell=true

If there is no nonInteractiveShell setting, CommandBox will automatically default it to true if there is an environment variable named CI present, which is standard for many build servers such as Travis-CI.

Custom working directory

CommandBox will start its current working directory in the same folder that you started the box process from. Once you are in the interactive shell, you can always change the current working directory with the cd command. If you want to change the default working directory or just want to run a one-off command in another folder, you can use the -cliworkingdir flag to the box binary when you start it.

box -cliworkingdir=C:/my/path/here/
# This works too
box -cliworkingdir C:/my/path/here/
# And can be coupled with a command to run
box -cliworkingdir C:/my/path/here/ install

Installation

Regardless of where you place the box binary, the first time you execute it, a .CommandBox folder will be created in your user's home directory and CommandBox will be extracted into that location. If you delete this directory, it will be replaced the next time the CommandBox executable is run.

You can specify a different install location by adding -commandbox_home=E:\CommandBox when you run the box binary.

To avoid specifying the commandbox_home variable every time you can create a file called commandbox.properties (case sensitive) in the same directory as the binary, and fill it with this line:

commandbox_home=E:\\CommandBox

The CommandBox home can also be a path relative to the location of the commandbox.properties file.

commandbox_home=../boxHome

Windows

Unzip the executable box.exe and just double click on it to open the shell. When you are finished running commands, you can just close the window, or type exit.

Mac/ *Unix

Homebrew (Mac)

brew install commandbox

To stay with current bleeding edge releases use the following:

brew tap ortus-solutions/homebrew-boxtap
brew install --head ortus-solutions/homebrew-boxtap/commandbox

Then run the box binary to begin the one-time unpacking process.

Versions will be installed in /usr/local/Cellar/commandbox. To switch between versions, simply use brew switch commandbox [version number]

If you want to use a commandbox.properties file as mentioned above, your box binary file will be in the /usr/local/Cellar/commandbox/<version>/libexec/bin/ directory where you should place your commandbox.properties file. There will also be a box binary in the /usr/local/Cellar/commandbox/<version>/bin/ directory where you should place the jre if you want CommandBox to use a version of Java that is different from your default version reported by java -version.

When using Homebrew to install CommandBox you must use Homebrew for any upgrade, minor or major. To upgrade CommandBox with Homebrew:

brew upgrade commandbox

NOTE: If you use Homebrew to upgrade your version of CommandBox it will erase your /usr/local/Cellar/commandbox/<current_version>/ folder. So before upgrading, take a copy of your /usr/local/Cellar/commandbox/<current_version>/libexec/bin/commandbox.properties file to drop back into /usr/local/Cellar/commandbox/<new_version>/libexec/bin/ before running box for the first time after upgrading.

Manual Installation

Unzip the binary box and just double click on it to open the shell terminal. When you are finished running commands, you can just close the window, or type exit.

Hint You can place the binary in your /usr/bin directory so it can be available system-wide via the box command in any terminal window.

Linux apt-get

Please note that if you are running Ubuntu 18.04 or greater, or Debian 8 (Jessie) or greater, it's necesarry to have the libappindicator-dev package in order to have the tray icon working correctly.

sudo apt install libappindicator-dev

Run the following series of commands to add the Ortus signing key, register our Debian repo, and install CommandBox.

Stable

( This first install routine also works for the Raspberry Pi. )

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

If you do not have Java installed you can install it with the following command.

sudo apt install openjdk-11-jdk

Then run the box binary to begin the one-time unpacking process.

Linux yum

Stable

Add the following to: /etc/yum.repos.d/commandbox.repo

[CommandBox]
name=CommandBox $releasever - $basearch
failovermethod=priority
baseurl=http://downloads.ortussolutions.com/RPMS/noarch
enabled=1
metadata_expire=7d
gpgcheck=0

Then run:

sudo yum update && yum install commandbox

Debian Linux manual install

After you have downloaded the commandbox.deb file, install it using the dpkg command.

sudo dpkg -i commandbox-debian-1.2.3.deb

Run the box binary to begin the one-time unpacking process.

Redhat Linux manual install

After you have downloaded the commandbox.rpm file, install it using the rpm command.

rpm –ivh commandbox-rpm-1.2.3.rpm

Recipes

Ingredients

Think of a recipe as a simple batch file for Windows or a shell script for Unix. It's just a text file where you place one command on each line and they are executed in order. Enter the commands exactly as you would from the interactive shell.

buildSite.boxr

Get Cooking

Execute your recipe with the recipe command, giving it the path to the recipe file.

If any commands in the recipe stop and ask for input, the recipe will pause until you supply that input. All commands that have confirmations, etc should have a --force flag for this purpose so you can run them headlessly without requiring your input. See the rm command above for an example.

Spice It Up

You can also bind the recipe with arguments that will be replaced inside of your recipe at run time. Pass any arguments as additional parameters to the recipe command and they will be passed along to the commands in your recipe.

Named arguments

If you use named arguments to the recipe command, they will be accessible via environment variables inside the recipe as ${arg1Name}, ${arg2Name}, etc.

Consider the following recipe:

notifyWinner.boxr

You would call it like so:

Output:

Note, all parameters to the recipe command needed to be named, including the recipeFile.

Positional Parameters

Now let's look at the same recipe set up to receive positional parameters.

You would call it like so:

Output:

Missing Args

If an argument is not passed, you can use the default value mechanism:

Is there an echo in here?

You can use echo on and echo off in recipes to control whether the commands output to the console as they are executed. This can be useful for debugging or confirming the success of commands with no output. Echo is on by default.

Note, echo off doesn't suppress the output of the commands, just the printing of the command and its arguments prior to execution. This does not use the actual echo command and is a feature that only applies during the execution of recipes.

Output:

Exiting a recipe

You can use the exit command in a recipe and instead of leaving the entire shell, the recipe will simply stop execution right there. If an exit code is passed, it will because the exit code of the recipe command as well as the entire shell.

Any command that errors or returns a non-0 exit code will end the recipe immediately and the recipe command will inherit that exit code. This line in a recipe will stop the recipe if there is not a foobar property in your box.json, but not before outputting a message.

On The Fly Commands

In addition to passing a file path to the recipe command for execution, you can also pipe the contents of a file directly into the command. if the input does not match a file path, it is assumed to be executable commands.

This can also give you some interesting ability to do dynamic evaluation of command strings.

OS Binaries

Hint This behavior is dependent on your operating system.

Using `run binary`

Execute an operation system level command using the native shell. For Windows users, cmd.exe is used. For Unix, /bin/bash is used. Command will wait for the OS command to finish.

The binary must be in the PATH, or you can specify the full path to it. Your keyboard will pass through to the standard input stream of the process if it blocks for input and the standard output and error streams of the process will be bound to your terminal so you see output as soon as it is flushed by the process.

Using `!binary`

A shortcut for running OS binaries is to prefix the binary with !. In this mode, any other params need to be positional. There is no CommandBox parsing applied to the command's arguments. They are passed straight to the native shell. As such, you don't need to escape any of the parameters for CommandBox when using this syntax.

Current Working Directory Aware

OS Commands you run are executed in the same working directory as CommandBox. This means you can seamlessly invoke other CLIs without ever leaving the interactive shell.

Building On

Parsing Rules

When passing a command string for native execution, ALL REMAINING TEXT in the line will be "eaten" by the native execution and passed to the OS for processing. This is so the CommandBox parser doesn't "'screw up" any special syntax that your OS command processor is expecting. That means any use of piping or && will get passed straight to the OS. On Windows, the following string will run the ver command twice in Windows.

In the event you want to pipe the result of an OS binary to another CommandBox command or chain another CommandBox command on the end, you can workaround this by echoing out the string and then piping that to the run command. This example will run the Windows ver command followed by the CommandBox ver command.

Instead, you can pass the command text through echo to have CommandBox process the backtick expansions first before sending it off to the OS for processing.

In the above example, written for Windows, the output of the echo command has the package show name expression expanded into the string and then the ENTIRE string is piped to run where the pipe and the find command are processed by Windows. Note, there is no need for preceding the command with ! when passing to run since ! is just an alias for run.

When you prepare the native binary ahead of time and then pipe it into the run command, you are allowed to pipe the result back into another CommandBox command in that specific case. This is only possible when run appears with nothing after it.

Piping to the native binary's standard input

You can pipe the output of a previous command in CommandBox directly to a native binary like so:

In this case, clip is a Windows binary that will read the standard input and place that text on the clipboard. When the run command receives two inputs, it will assume the first input is the piped input and the second input is the actual command to run.

You can even pipe commands to an interpreter that normally reads from a keyboard on the standard input, but be aware that some binaries such as Windows cmd require line breaks after the input or it won't process. In the specific case of Windows cmd it seems to require at least two line breaks for some reason (this is also true outside of CommandBox)

In the previous example we use a backtick expansion to grab a line feed from the CFML chr() function.

Limitations of piping

There are limitations. When you pipe into the run command, the command will not also be able to read from your keyboard (this is true of any shell) and it will execute in a non-interactive manner, which means the ping's output above would appear all at once as opposed to flowing in one line at a time.

When piping into the run command you cannot also pipe the output of the run command like so:

As soon as any text appears after run or !, then the rest of the line is "eaten" and passed to the native shell.

Also you cannot build up a command like so and also pipe input into the native binary at the same time:

This is because only one parameter can be piped into a command at a time.

Debugging

If you're having issues getting a native binary to run, you can turn on a config setting that will echo out the exact native command being run including the call to your OS's command interpreter.

Setting the Native Shell

You can override the default native shell from /bin/bash to any shell of your choosing, like zsh. This will let you use shell specific aliases. You can set your native shell property using the config set command (i.e., config set nativeShell=/bin/zsh)

Exit Codes

If the native binary errors, the exit code returned will become the exit code of the run command itself and will be available via the usual mechanisms such as ${exitCode}.

CLI Environment Variables

Any environment variables you set in the CommandBox shell will be available to the native process that your OS binary runs in. Here's a Windows and *nix example of setting an env var in CommandBox and then using it from the native shell.

Expressions

Any valid command can be used as an expression, including calls to native OS binaries, CFML functions, or REPL one-liners. Note that any text that a command immediately flushes to the console during its execution (like a download progress bar) will not be returned by the expression, though it will display on the console.

Entire Parameter

Take for instance, this simple command that prints out the contents of a file:

cat defaultServer.txt

It can be used as a dynamic parameter like so:

server start name=`cat defaultServer.txt`

In the example above, the contents of the defaultServer.txt file will be passed in as the value of the "name" parameter to the "server start" command. If the contents of the file was the text myServer, the equivalent final command would be:

server start name=myServer

Inside Parameters

There can be more than one expression in a single parameter value. Expressions can also be combined with static text and they will all be evaluated in the order they appear:

echo "Your CommandBox version is `ver` and this app is called '`package show name`'!!"

That would output something similar to:

Your CommandBox version is 3.0.0 and this app is called 'Brad's cool app'!

If you need to use an actual backtick in a parameter value, escape it with a backslash.

echo "Nothing to \`see\` here"

Which outputs

Nothing to `see` here

Express Yourself

This unlocks a new world of scripting potential when combined with other abilities like native OS binary execution and CFML functions from the CLI. Here's some examples to get your gears turning:

Set a package property in box.json equal to the current date passed through a CFML date mask

package set createdDate="'`#now | #dateformat mm/dd/yyyy`'"
Set createdDate = 1/1/2016

Set properties based on manipulations of previous values:

package set name=brad
Set name = brad
package set name="`package show name` wood"
Set name = brad wood

Perform CFML operations on local files:

Commandbox> #hash `cat pass.txt`

Execute environment-aware install scripts based on local files. (isProduction.txt would contain the text true or false in this ex.)

install id=coldbox production=`cat /home/user/isProduction.txt`

System Settings

Now that we're starting to use CommandBox in a lot of cloud scenarios like Docker, we're looking for more and more ways to have dynamic configuration. The most common way to do this is via Java system properties and environment variables. We've wrapped up those two into a new concept called System Settings. Now any time you use ${mySetting} in a command parameter, a box.json property, server.json property, or a Config Setting, that place holder will be replaced with a matching JVM property or env var (in that order) at runtime. This is great for setting things like ports, default directories, or passwords and other secrets as an env variable so it can be different per server and not part of your code.

Using system settings from the CLI

You can test it out easily by outputting your system path like so:

echo ${PATH}

Default values

If a system setting can't be found in a Java property or an environment variable, an empty string will be returned. You can provide a default value like so.

server start port=${SERVER_PORT:8080}

This does assume that your default value will never contain a colon!

Lookup Order

System settings are looked up in the following order. If the same variable exists in more than one place, the first one found will be used:

Environment variables for the currently executing command
Environment variables for the parent (calling) command (if applicable)
Global shell environment variables
JVM System Properties in the CLI process
Environment Variables from your actual operating system

For example, if you run the following it will output the contents of your OS's PATH environment variable.

echo ${path}

However, if you set a shell environment variable from inside CommandBox called path and then output it, you will see the contents of your variable since it overrides.

set path=donuts
echo ${path}

Using system settings in JSON files

When box.json or server.json files are read, they automatically have all system setting setting placeholders swapped out. For instance, you can specify the port for your server in your server.json like so:

 server set web.http.port=\${WEB_PORT:8080}

Note, we escaped the system setting by putting a backslash (\) in front of it. That's because we wanted to insert the actual text into the file and not the value of it! The resultant server.json is this. Note the system setting needs to be encased in quotes so it's just a string for the JSON.

{
    "web":{
        "http":{
            "port":"${WEB_PORT:8080}"
        }
    }
}

Now, if your server has an environment variable called WEB_PORT, it will be used as the port for your server.

System settings can also be used in object key names as well in your JSON files. Here is an example of a .cfconfig.json file with a dynamic datasource name.

{
  "datasources":{
    "myDSN-${environment}":{
      "database":"test",
      "dbdriver":"MSSQL",
      "dsn":"jdbc:sqlserver://{host}:{port}",
      "host":"localhost",
      "password":"password",
      "username":"user"
    }
  }
}

Note if there are duplicate key names after the system settings are expanded, the last one expanded will win.

In the REPL

You can use system settings and environment variables in the REPL using the same syntax as the CLI

CommandBox> set foo=bar
CommandBox> REPL

CFSCRIPT-REPL: echo( '${foo}' )
bar

Manual system setting replacements

If you're writing a custom command or task runner that reads a JSON file of your own making, you can do easy system setting replacements on the file.

In a complex data structure

component {
    property name='systemSettings' inject='SystemSettings';

     function run() {
        var mySettings = deserializeJSON( fileRead( 'mySpecialConfigFile.json' ) );
        systemSettings.expandDeepSystemSettings( mySettings );
     }

}

In a string

The expandDeepSystemSettings() method will recursively crawl the struct and find any strings with system setting placeholders inside them. Be careful not to write back out the same struct after you've done replacements on it. Otherwise, you'll overwrite the placeholders with the current values!

You can also manually replace system setting placeholders in a single string like so:

var myValue = 'User home is in ${user.home}';
myValue = systemSettings.expandSystemSettings( myValue );

Programmatic access

The SystemSettings service also gives you programmatic access to individual system settings in your custom commands and task runners.

var mySetting = systemSettings.getSystemSetting( 'settingName' );
or
var mySetting = systemSettings.getSystemSetting( 'settingName', 'defaultValue' );

Environment Variables

CommandBox allows you to access Java System Properties from the CLI and environment variables from your operating system via the ${name_here} mechanism. But CommandBox also gives you the ability to create variables of your own directly in the shell. The scope (life) of these environment variables depends on how and where they are declared.

Shell Environment Variables (Global)

Every shell instance has its own set of environment variables you can set and read. These live for the duration of the shell and have the same lifespan as Java system properties in the CLI. There is an env namespace of commands for dealing with environment variables.

To set a new variable, you can run this:

env set foo=bar

# or just
set foo=bar

You can view the contents of that variable from anywhere in the same shell session like so:

env show foo

# or provide a default value
env show foo myDefault

# Or via System Setting expansions
echo ${foo:myDefault}

Clear out an environment variable like so:

env clear foo

Per-Command Environment Variables

In addition to the global shell environment, each executing command receives its own set of environment variables that go away when the command finishes executing. Unlike Bash, the parent variables are not copied into each command, but a hierarchy is maintained and when a variable is not found, the parent command is checked and so on until the global shell variables. After that, the Java system properties and then OS's actual environment is checked.

Here is a contrived example of an echo command that run a sub command as part of a command expression (backtick expansion). The sub command sets an environment variable and then outputs it.

echo `set myVar=cheese && echo \${myVar}`
env show myVar myDefault

The first line will output the text "Cheese" but the second line will output the default value of "myDefaul" since the variable only existed in the inner context of the expression and isn't visible to the outer shell.

Recipes

Recipes behave like a subshell and any variables set in a recipe will live for the duration of that recipe but will be gone once the recipe exits.

Viewing Variables

To view the environment variable for the current command context, run:

> env set color=red
> env set number=2
> env show
{
    "number":"2",
    "color":"red"
}

The output is a JSON serialized struct, which makes it suitable for programmatically accessing.

> env show | foreach "echo 'The var \${item} is set to \${value}'"
The var number is set to 2
The var color is set to red

There is a command to help you debug what variables are set in each command context as well as the global shell. Here we pipe some commands into a recipe for execution. The context for the env debug command has no variables, the recipe command has a variable called inRecipe and the global shell as the 2 variables from the example above.

> echo "set inrecipe=true; env debug" | recipe
[
    {
        "environment":{},
        "context":"env debug"
    },
    {
        "environment":{
            "inRecipe":"true"
        },
        "context":"recipe"
    },
    {
        "environment":{
            "number":"2",
            "color":"red"
        },
        "context":"Global Shell"
    }
]

Native Binaries

set name=brad
!echo %name%

set name=brad
!echo $name

Passing Environment Variables to Servers

Any ComandBox environment variables present in the shell will automatically be passed to the environment of the server process. This means, given an example like this:

set foo=bar
server start

The CFML code running that server process will be able to "see" the foo environment variable.

System Setting Expansion Namespaces

The default namespace when using the ${foo} system setting expansion syntax is box environment variable, Java system properties, and OS environment variables.

It is also possible to leverage built-in namespaces to allow expansions that reference:

server.json properties
box.json properties
arbitrary JSON file properties
Config settings (like the config show command)
Server info properties (like the server info property=name command)
Other properties in the same JSON file

`server.json` properties

If the current working directory of the shell contains a server.json file, you can reference any property in it with the serverjson. namespace.:

${serverjson.name}
${serverjson.app.cfengine}
${serverjson.web.http.port}
${serverjson.trayEnable:defaultValue}

if you have a server json file with a non-default name such as server-custom.json then you can access it with the serverjson. namespace.:

${serverjson.name@server-custom.json}
${serverjson.app.cfengine@server-custom.json}
${serverjson.web.http.port@server-custom.json}
${serverjson.trayEnable@server-custom.json:defaultValue}

`box.json` properties

If the current working directory of the shell contains a box.json file, you can reference any property in it with the boxjson. namespace.:

${boxjson.name}
${boxjson.slug}
${boxjson.testbox.runner}
${boxjson.description:defaultValue}

Arbitrary JSON file properties

You can can reference properties from any JSON file with either a relative path (to the current working directory) or an absolute path with the json. namespace..

${json.myProperty.name@myFile.json}
${json.myProperty.name@/path/to/myFile.json:defaultValue}

Config settings

You can expand any valid config setting with the configsetting. namespace. So getting the same value you get when you run the command

config show endpoints.forgebox.apitoken

can be expanded like this:

${configsetting.endpoints.forgebox.apitoken}
${configsetting.endpoints.forgebox.apitoken:defaultValue}

Server info properties

You can expand any valid server info property with the serverinfo. namespace. So getting the same value you get when you run the command

server info property=serverHomeDirectory

can be expanded like this:

${serverinfo.serverHomeDirectory}
${serverinfo.serverHomeDirectory:defaultValue}

By default, the expansion looks at the default server in the current working directory. To grab a server property by server name, use this syntax:

${serverinfo.serverHomeDirectory@serverName}
${serverinfo.serverHomeDirectory@serverName:defaultValue}

Other properties in the same JSON file

You can self-reference other properties in the same JSON file using the @ namespace. So given the following JSON file:

{
    "appFileGlobs" : "models/**/*.cfc,tests/specs/**/*.cfc",
    "scripts":{
        "format":"cfformat run ${@appFileGlobs} --overwrite",
        "format:check":"cfformat check ${@appFileGlobs} --verbose"
    }
}

The expansion of ${@appFileGlobs} self-references the appFileGlobs property inside the same file, allowing for easy re-use of that value.

Custom namespaces

Modules can register an onSystemSettingExpansion interceptor to contribute custom system setting namespace expansions. The interceptor gets the following data in interceptData

setting - The name of the setting to be expanded (with ${} and :defaultValue removed)
defaultValue - The default value, or empty string if none specified
resolved - A boolean that should be set true if the interceptor was able to resolve the setting
context - A struct of the original JSON being expanded or the parameters from the command line where the expansion was used.

A hypothetical example would be:

function onSystemSettingExpansion( struct interceptData ) {	
  // ${luceeInfo.property}
  if( interceptData.setting.lcase().startsWith( 'luceeinfo.' ) ) {
		
    var settingName = interceptData.setting.replaceNoCase( 'luceeInfo.', '', 'one' );
				
    interceptData.setting = server.lucee[ settingName ] ?: interceptData.defaultValue;
		
    // Stop processing expansions on this setting
    interceptData.resolved=true;
    return true;
  }	
}

And then we would use our hypothetical namespace to reference any Lucee information like so

echo ${luceeinfo.version}

It's important if you implement your own onSystemSettingExpansion interceptor that you check the incoming setting to see if it applies to you. If you process the system setting, you must place the final expanded value back in the interceptData.setting struct key, set interceptData.resolved to true and return true from the interception method so the chain stops processing.

REPL

CommandBox contains a REPL command which is a powerful tool to execute ad-hoc CFML code from the command line. A REPL reads user input, evaluates it, prints the result, and then repeats the process. The CommandBox REPL supports the inline execution of both CF script or tags.

CFSCRIPT-REPL: 5+5
=> 10

Script REPL

The default mode of the REPL command is to accept script. You can enter most any CF Script into the prompt for execution. If the script is an expression that returns a value, or sets a variable, that value/variable will be output. Variables that you set will be available to you until you exit the REPL command.

CFSCRIPT-REPL: breakfast = ['bacon','eggs']
=> [
    "bacon",
    "eggs"
]
CFSCRIPT-REPL: breakfast.len()
=> 2
CFSCRIPT-REPL: breakfast.append( 'orange juice' )
=> [
    "bacon",
    "eggs",
    "orange juice"
]

Multi-line

Multi-line statements are also allowed. If you have typed a starting { without an ending }, the REPL will keep accepting lines until it has determined the statement to be finished. The prompt changes to ... until the statement is finished.

CFSCRIPT-REPL: for( item in breakfast ) {
...echo( item & chr(10) )
...}
=> bacon
eggs
orange juice

If you would like to abort a multi-line statement, simply type exit at the prompt.

Tag REPL

You can also enter tags at the REPL. Switch to this mode by setting the script flag to false.

REPL --!script

Any output from the tags will be returned to the console.

CFML-REPL: plain text
=> plain text
CFML-REPL: <cfset name = "Brad Wood">
=>
CFML-REPL: <cfoutput>#reverse( name )#</cfoutput>
=> dooW darB
CFML-REPL: <cfif 1 eq 2>yes<cfelse>no</cfif>
=> no

Multi-line statements are not currently supported in the tag REPL.

History

The script and tag REPL have their only history. Use the up and down arrows to access previous things you typed. Your REPL history can be viewed and managed by the history command (once you exit the REPL).

history type=scriptrepl
history type=tagrepl --clear

Tab completion is currently not supported in either of the REPLs.

Environment Variable Expansions

You can use environment variable expansions in the REPL with the same syntax that works in the CLI and JSON files. Consider this example which sets an environment variable in the shell and then enters the REPL command and references the variable. Note, the variable is expanded in-place, so you still need to wrap it in quotes so the resulting CFML code is valid.

CommandBox> set foo=bar
CommandBox> REPL

CFSCRIPT-REPL: echo( '${foo}' )
bar

Escapes work the same way in the REPL

CFSCRIPT-REPL: echo( '\${foo}' )
${foo}

forEach Command

The foreach command will execute another command against every item in an incoming list. The list can be passed directly or piped into this command. The default delimiter is a new line so this works great piping the output of file listings directly in, which have a file name per line.

This powerful construct allows you to perform basic loops from the CLI over arbitrary input. Most of the examples show file listings, but any input can be used that you want to iterate over.

This example will use the echo command to output each filename returned by ls. The echo is called once for every line of output being piped in.

ls --simple | forEach

The default command is "echo" but you can perform an action against the incoming list of items. This example will use "cat" to output the contents of each file in the incoming list.

ls *.json --simple | forEach cat

You can customize the delimiter. This example passes a hard-coded input and spits it on commas. So here, the install command is run three times, once for each package. A contrived, but effective example.

forEach input="coldbox,testbox,cborm" delimiter="," command=install

If you want a more complex command, you can choose exactly where you wish to use the incoming item by referencing the default system setting expansion of ${item}. Remember to escape the expansion in your command so it's resolution is deferred until the forEach runs it internally. Here we echo each file name followed by the contents of the file.

ls *.json --simple | foreach "echo \${item} && cat \${item}"

You may also choose a custom placeholder name for readability.

ll *.json --simple | foreach "echo \${filename} && cat \${filename}" filename

Iterating over JSON

The forEach can also iterate over JSON representations of objects or arrays. This means you can pipe in JSON from a file, a command such as package show or any REPL operation that returns complex data. The delimiter parameter is ignored for JSON input.

package show dependencies | foreach

If iterating over an array, each item in the array will be available as ${item}. If iterating over a object, the object keys will be in ${item} and the values will be in ${value}.

package show dependencies | foreach "echo 'You have \${item} version \${value} installed'"

You can customize the system setting name for value with the valueName parameter to forEach.

package show dependencies | foreach command="echo 'You have \${package} version \${version} installed'" itemName=package valueName=version

printTable Command

CommandBox has a helper for printing ASCII Art tables in your custom commands and task runners called print.table(). We've taken this a step further and wrapped the table printer utility in a new command so you can use it from the CLI directly. The printTable command will accept ANY data in as JSON and it will marshal it into a query for you. This means it can be a query, an array of structs, an array or arrays, and more. You can now get quick and easy visualization of any data right from the CLI or in builds.

Parameters

data - JSON serialized query, array of structs, or array of arrays to represent in table form
includeHeaders - A list of headers to include.
headerNames - A list/array of column headers to use instead of the default specifically for array of arrays
debug - Only print out the names of the columns and the first row values

When using an array of arrays and not specifying headerNames, the columns will be named col_1, col_2, col_3, etc...

Examples

# array of structs
printTable [{a:1,b:2},{a:3,b:4},{a:5,b:6}]

╔═══╤═══╗
║ a │ b ║
╠═══╪═══╣
║ 1 │ 2 ║
╟───┼───╢
║ 3 │ 4 ║
╟───┼───╢
║ 5 │ 6 ║
╚═══╧═══╝

# array of arrays
printTable data=[[1,2],[3,4],[5,6]] headerNames=foo,bar

╔═════╤═════╗
║ foo │bar ║
╠═════╪═════╣
║ 1   │2   ║
╟─────┼─────╢
║ 3   │4   ║
╟─────┼─────╢
║ 5   │6   ║
╚═════╧═════╝

# Query object
#extensionlist | printTable name,version

╔═════════════════════════════════════════╤═══════════════════╗
║ name                                 │ version         ║
╠═════════════════════════════════════════╪═══════════════════╣
║ MySQL                                │ 8.0.19          ║
╟─────────────────────────────────────────┼───────────────────╢
║ Microsoft SQL Server                 │ 6.5.4           ║
╟─────────────────────────────────────────┼───────────────────╢
║ PostgreSQL                           │ 9.4.1212        ║
╟─────────────────────────────────────────┼───────────────────╢
║ Ajax Extension                       │ 1.0.0.3         ║
╚═════════════════════════════════════════╧═══════════════════╝

# JSON list of all servers
server list --json | printTable name,host,port,status

╔══════════════════════════════╤═════════════════════════════╤═══════╤══════════╗
║ name                       │ host                     │ port  │ status  ║
╠══════════════════════════════╪═════════════════════════════╪═══════╪══════════╣
║ servicetest                │ 127.0.0.1                │ 54427 │ stopped ║
╟──────────────────────────────┼─────────────────────────────┼───────┼──────────╢
║ servicetest2               │ 127.0.0.1                │ 52919 │ stopped ║
╟──────────────────────────────┼─────────────────────────────┼───────┼──────────╢
║ FRDemos                    │ 127.0.0.1                │ 50458 │ stopped ║
╚══════════════════════════════╧═════════════════════════════╧═══════╧══════════╝

jq Command

Using jq with a file

# basic.json
   "a": {
      "b": {
         "c": {
            "d": "value"
         }
      }
   },
   "dan": [1,2,3,4,5,6,7,8],
   "ban": "bar",
   "cat": "baz"
}

> jq "basic.json" "a"
=> "a": {
      "b": {
         "c": {
            "d": "value"
         }
      }
   }

> jq "basic.json" "a.b.c.d"
=> value

> jq "basic.json" "dan"
=> [
    1,
    2,
    3,
    4,
    5,
    6,
    7,
    8
]

> jq "basic.json" "dan[1]"
=> 2

Using jq with a URL

> jq "https://official-joke-api.appspot.com/jokes/ten" [].join('.....',[setup,punchline])
=> [
    "Lady: How do I spread love in this cruel world?.....Random Dude: [...\ud83d\udc98]",
    "Why are skeletons so calm?.....Because nothing gets under their skin.",
    "How come a man driving a train got struck by lightning?.....He was a good conductor.",
    "What do you call a pig with three eyes?.....Piiig",
    "How do you steal a coat?.....You jacket.",
    "Did you hear about the submarine industry?.....It really took a dive...",
    "What does a pirate pay for his corn?.....A buccaneer!",
    "A programmer puts two glasses on his bedside table before going to sleep......A full one, in case he gets thirsty, and an empty one, in case he doesn’t.",
    "How did the hipster burn the roof of his mouth?.....He ate the pizza before it was cool.",
    "Did you hear the news?.....FedEx and UPS are merging. They’re going to go by the name Fed-Up from now on."
]

Using jq with inline json

> jq '{"a": {"b": {"c": {"d": "value"}}}}' a.b.c.d
=> value

Special Keys / Expressions

@ - Current Node (eg. current number/string/array/object) used to evaluate or check value

& - Expression (Function or Keyname) (eg. &to_number() or &keyname)

! - NOT Expression

&& - AND expression

|| - OR expression

{'ab':true} - Literal Expressions (this will be converted to json)

'foo' - Raw String Literals not evaluated (Single Quotes)

Available Functions

Generic Functions

length, reverse, type, not_null

CommandBox> jq [1,2,3,4,5,6,7,8,9] length(@)
=> 9

Conversion Functions

to_list, to_array, to_string, to_number

CommandBox> jq [1,2,-3,4,-5,6,-7,-8,9] [].to_string(@)
> [
    "1",
    "2",
    "-3",
    "4",
    "-5",
    "6",
    "-7",
    "-8",
    "9"
]

String / Number Functions

abs, ceil, floor

CommandBox> jq [1,2,-3,4,-5,6,-7,-8,9] [].abs(@)
=> [
    1,
    2,
    3,
    4,
    5,
    6,
    7,
    8,
    9
]

Boolean Checks

ends_with, starts_with, contains

CommandBox> jq [1,2,-3,4,-5,6,-7,-8,9] [?contains('-8',@)]
=> [
    -8
]

All functions can be used in other functions with the "&" operator.

A common example would be getting a person with the highest or lowest networth max_by(people, &abs(net_worth))

Array Functions

avg, first, join, last, matches, min, max, reverse, sum, sort, split, unique/uniq

CommandBox> jq [1,2,-3,4,-5,6,-7,-8,9] avg(@)
-0.111111111111

Struct or Array of Structs functions

defaults, from_entries, group_by, key_contains, keys, map, max_by, merge, min_by, omit, pluck, sort_by, to_entries, values

# jsonfile.json
[
     {
        "logdir":"logs/aa",
        "Size":308
    },
    {
        "logdir":"logs/bb",
        "Size":303
    }
]

CommandBox> jq jsonfile.json sort_by(@,&Size)
=> [
    {
        "logdir":"logs/bb",
        "Size":303
    },
    {
        "logdir":"logs/aa",
        "Size":308
    }
]

Tab Completion

One of the most productive features of the shell is tab completion. This means you can type a partial command and hit the tab key on your keyboard to be prompted with suggestions that match what you've typed so far. If there is only one match, it will be finished for you. This can save a lot of typing and will be a familiar concept to those already living in a CLI environment.

When "tab" is pressed, the text you've entered so far is run through the CommandBox command parser to see if it can match a namespace, command, or parameters. If you press tab at an empty prompt, all top level commands and namespaces will display. Since tab completion is run through the standard command parser, that means it works on command aliases as well.

The tab completion options are broken up into groups to visualize the commands, parameters, flags, etc. As you type, the list of available options will auto-filter for you. You can keep hitting tab to toggle through the available options and you can press enter to select the one you want.

Commands

If your text matches only command, namespace, or alias, it will be auto-filled in for you. For instance, if you type the following and press tab...

CommandBox> cold

CommandBox> coldbox

CommandBox> coldbox

Commands
  help
  reinit  (This command will reinitialize a running ColdBox application if a server was started with CommandBox)
Namespaces
  create

Parameters

If the parser finds a complete command, it will move on to parameter completion which is slightly more complicated since at first, there is no way to tell if you are going to named parameters, positional parameters, and/or flag. Based on what parameters you've typed so far, if any, CommandBox will do it's best to give you only relevant options. If it is unsure, it will provide you with every possibility it can think of. Don't be afraid to try pressing tab while typing parameters, you may be surprised how often we can guess where you're going!

CommandBox> delete

Flags
  --force     (Force deletion without asking)    --recurse   (Delete sub directories)
Parameters
  path=        (file or directory to delete.)    recurse=    (Delete sub directories)
  force=      (Force deletion without asking)

Named

If you have started typing named parameters, CommandBox will only suggest unused named parameters and flags.

CommandBox> delete path=myDir force=true

Flags
  --recurse  (Delete sub directories)
Parameters
  recurse=   (Delete sub directories)

If you are using named parameters, and you have typed the name of a parameter followed by an equals sign and no space, CommandBox will attempt to prompt valid values. This includes but is not limited to booleans and file system paths.

Here, true and false are offered as possible values for the force parameter.

CommandBox> delete path=myDir force=

Values
  force=true     force=false

CommandBox> delete path=

Directories
  path=tests/       path=models/      path=coldbox/     path=modules/
Files
  path=box.json     path=index.cfm    path=server.json

Positional

Tab completion for positional parameters works the same as the "value" portion of named parameters. Parameter names will also show up when you hit tab even when using positional parameters. This is on purpose to remind you of what options you have, but you obviously won't type them.

Flags

Tab completion will always work for flags if your command has any boolean parameters. Here we type -- in the delete command and we are prompted with --force and --recurse.

CommandBox> delete myDir --

Flags
  --force  (Force deletion without asking)   --recurse   (Delete sub directories)

Custom

Commands have the ability to give hints in the form of a static list or a runtime function with dynamic output.

CommandBox> forgebox show type=

Values
type=di                      type=caching                 type=projects
type=cms                     type=logging                 type=cf-engines
type=mvc                     type=modules                 type=interceptors
type=demos                   type=plugins                 type=wirebox-aspects

REPL

When writing code inside the REPL, you can also press tab to get completion on

CFML function names
Member function names like .append()
Variable names you have created as part of your REPL session

Sublime Text

Quickstart

Installation

via PackageControl

Just type cmd-shift-p/ctrl-shift-p to bring up the command pallete and pick Package Control: Install Package from the dropdown, search and select the CommandBox package there and you're all set.

Manually

You can clone the repo in your /Packages (Preferences -> Browse Packages...) folder and start using/hacking it.

Troubleshooting

Usage

Running a Commandbox Command

You may select pre-configured commands from Menu -> Commandbox, including the ability enter a custom command.

Keyboard Shortcuts:

Ctrl+Shift+B - Run Commandbox Command: A prompt input will open for you to enter your command
Ctrl+Shift+T - Start the Embedded Server: Your Commandbox cwd is always the root of your Sublime Project so any box.json configuration will be honored
Ctrl+Shift+P - Stop the Embedded Server
Alt+P - Show the Commandbox Output Panel ( also available in the View -> Commandbox menu )
Alt+[Command|Windows]+P - Hide the Commandbox Output Panel ( also available in the View -> Commandbox menu )

Settings

The file Commandbox.sublime-settings is used for configuration, you can change your user settings in Preferences -> Package Settings -> Commandbox -> Settings - User.

The defaults are:

exec_args

You may override your PATH environment variable as follows:

box installed locally

If box is installed locally in the project, you have to specify the path to the box executable. Threfore, adjust the path to /bin:/usr/bin:/usr/local/bin:node_modules/.bin

results_in_new_tab

If set to true, a new tab will be used instead of a panel to output the results.

results_autoclose_timeout_in_milliseconds

Defines the delay used to autoclose the panel or tab that holds the Commandbox results.

show_silent_errors

log_erros

Toggles the creation of sublime-commandbox.log if any error occurs.

syntax

Syntax file for highlighting the box results. You can pick it from from the command panel as Set Syntax: Commandbox results.

Set the setting to false if you don't want any colors (you may need to restart Sublime if you're removing the syntax).

nonblocking

When enabled, the package will read the streams from the task process using two threads, one for stdout and another for stderr. This allows all the output to be piped to Sublime live without having to wait for the task to finish.

If set to false, it will read first from stdout and then from stderr.

Bind Your Own Keyboard Shortcuts

You can use a shortcut for running a specific task like this:

JSON Settings

You can customize the way that JSON is formatted when it's written to files such as server.json and box.json as well as how it displays in the console when using commands such as server show and package show

JSON.indent

string

String to use for indenting lines. Defaults to four spaces.

config set JSON.indent="  "

JSON.lineEnding

string

String to use for line endings. Defaults to CRLF on Windows and LF on *nix. Pass the actual character to use, not a placeholder.

config set JSON.lineEnding=`#chr 10`

JSON.spaceAfterColon

boolean

Add space after each colon like "value": true instead of "value":true Defaults to false

config set JSON.spaceAfterColon=true

JSON.sortKeys

string

Specify a sort type to sort the keys of json objects: text or textnocase

config set JSON.sortKeys=textnocase

JSON.ANSIColors

struct

A struct of colors to use when displaying JSON in the CLI. You can use any color name from the system-colors command or a direct ANSI escape sequence.

JSON.ANSIColors.constant

string

The color to use for constant values (true/false/null). Defaults to "red".

config set JSON.ANSIColors.constant=PaleTurquoise1

JSON.ANSIColors.key

string

The color to use for object key names. Defaults to "blue".

config set JSON.ANSIColors.key=Purple5

JSON.ANSIColors.number

string

The color to use for numbers. Defaults to "aqua".

config set JSON.ANSIColors.number=SeaGreen3

JSON.ANSIColors.string

string

The color to use for quoted string values. Defaults to "lime".

config set JSON.ANSIColors.string=MistyRose3

Multi-Engine Support

You can specify the CFML engine via the command line arguments:

CommandBox> start cfengine=adobe@2018

This will start an Adobe ColdFusion 2018 server in your webroot. That's it!

By default, CommandBox uses the cfengine slug to search for the engine on ForgeBox. The format is slug@version where the version is optional. Ortus Solutions maintains the versions of the engines available on ForgeBox.

Supported engines are:

Adobe ColdFusion 9 **
Adobe ColdFusion 10
Adobe ColdFusion 11
Adobe ColdFusion 2016
Adobe ColdFusion 2018
Adobe ColdFusion 2021
Railo 4.2
Lucee 4.5
Lucee 5

Here are some examples:

# Start the default engine
CommandBox> start

# Start the latest stable Railo engine
CommandBox> start cfengine=railo

# Start a specific engine and version
CommandBox> start cfengine=adobe@10.0.12

# Start the most recent Adobe server that starts with version "11"
CommandBox> start cfengine=adobe@11

# Start the most recent adobe engine that matches the range
CommandBox> start cfengine="adobe@>9.0 <=11"

Engines are downloaded and stored in your CommandBox artifacts folder. You can view your engines and clear them using the standard artifacts commands:

CommandBox> artifacts list

# Removes all adobe servers currently in the artifacts
# These servers will need to be re-downloaded the next time they are started
CommandBox> artifacts remove adobe

ColdFusion Admin settings

While Lucee asks for a password the first time running the admin, ColdFusion requires a username and password when CommandBox sets it up. The default username and password for the Adobe ColdFusion servers used are:

Username: admin
Password: commandbox

WAR Support

Additionally, CommandBox can start any WAR given to it using the WARPath argument.

CommandBox> start WARPath=/var/www/myExplodedWAR
CommandBox> start WARPath=/var/www/myWAR.war

If you run a regular start command inside of a folder that has a /WEB-INF/web.xml file, CommandBox will treat that folder as a WAR.

Custom Engines

The cfengine parameter can accept any valid CommandBox endpoint ID. That means it can be an HTTP URL, a Git repo, a local folder path to your company's network share, or a custom ForgeBox entry you've created. As long as that endpoint resolves to a package that contains these files, you're good:

box.json
Engine.[zip|war] (file name doesn't matter)

CommandBox will download the package, unzip it and use the WAR/zip file as the engine for your app.

Normally, the artifacts cache isn't used for non-ForgeBox packages, but CommandBox will only download the engine once per server and then assume the file hasn't changed. You will need to forget the server to trigger a new download.

Here's an example of starting up a web server using a direct download link to a package containing a WAR file:

CommandBox> start cfengine=http://downloads.ortussolutions.com/adobe/coldfusion/9.0.2/cf-engine-9.0.2.zip

server.json Configuration

You can set the cfengine and other related configuration options in your server.json to use them every time you start your app.

CommandBox> server set app.cfengine=adobe
CommandBox> server set app.WARPath=/var/www/my-app

These commands would create the following server.json

{
    "app":{
        "cfengine":"adobe",
        "WARPath":"/var/www/my-app"
    }
}

Just a reminder that starting a server with any command line arguments will save the arguments to your server.json by default.

CommandBox> start cfengine=adobe@9

This command would add adobe@9 to your server.json. If this is not what you want, you can append saveSettings=false or even --!saveSettings when you start your server and CommandBox will not save the arguments you specify to your server.json.

Misc Settings

These are some one-off settings that doen't really belong anywhere else.

nativeShell

string

This setting affects how CommandBox invokes the shell for the run command or when using the !binary shortcut. The default *nix shell used for the run command is /bin/sh but you can override it to use a custom shell. Set the full path to the shell binary.

config set nativeShell=/bin/zsh
config show nativeShell

tagVersion

boolean

Running the bump command from a Git repo will attempt to tag the repo unless you provide the tagVersion parameter. This setting provides a global default to prevent CommandBox from trying to tag Git repos.

config set tagVersion=false
config show tagVersion

tagPrefix

string

Running the bump command from a Git repo will tag the repo using the format v{version} such as v1.0.0 or v4.3.6. You can remove the v or swap it for another prefix using the tagPrefix parameter. Remember, another string like foo1.2.3 will not be parseable by CommandBox as a valid semver. This setting can be overriden by the tagPrefix parameter to the bump command.

config set tagPrefix=''
config show tagPrefix

artifactsDirectory

string

You can control where your artifact cache is stored with the artifactsDirectory config setting. This can be useful to keep your primary drive from filling up, or to point your files to a shared network drive that your coworkers can share.

config set artifactsDirectory=/path/to/artifacts
config show artifactsDirectory

colorInDumbTerminal

boolean

You can enable this setting if you want to force CommandBox to output ANSI formatting code even though you're running box inside of a non-interactive terminal. This is handy for CI builds such as Gitlab, which will process color coded text in your job logs. Default value is false.

config set colorInDumbTerminal=true
config show colorInDumbTerminal

preferredBrowser

string

Used to override the default browser to open when a server starts, or when using a command like server open or calling the openURL() method from a command or Task Runner. Possible values are:

firefox
chrome
opera
edge (Windows and Mac only)
ie (Windows only)
safari (Mac only)
konqueror (Linux only)
epiphany (Linux only)

config set preferredBrowser=chrome
config show preferredBrowser

tabCompleteInline

boolean

You can change CommandBox's default tab completion to be an inline list that follows your cursor. This setting requires you to close and re-open the shell to take affect.

config set tabCompleteInline=true
config show tabCompleteInline

Server Versions

Remember to use Semantic Versions

One minor difference to keep in mind is Lucee server and Adobe ColdFusion use a typical versioning scheme for java projects which looks like this:

<major>.<minor>.<patch>.<build>[-<preReleaseID>]

# Ex of an unstable build
5.3.4.84-SNAPSHOT

# Or a stable build
5.3.4.80

<major>.<minor>.<patch>[-<preReleaseID>]+<build>

# Ex of an unstable build
5.3.4-SNAPSHOT+84

# Or a stable build
5.3.4+80

The important thing to remember is, when starting a server via CommandBox always use the second format shown above since that is how ForgeBox recognizes each release.

As of version 5.3.0, CommandBox will also recognize the fourth digit in 1.2.3.4 as a build ID if there is no plus sign in the version. This makes 5.3.4+80 and 5.3.4.80 equivalent.

What versions exist?

Questions about what versions are available? No problem! Here are some ways you can find out:

View the last few versions via the CLI with the command forgebox show lucee
Start typing your cfengine and hit the <tab> key to invoke the tab-completion feature. This actually phones out to ForgeBox as you hit tab to get the current valid list of versions that match what you've typed so far

You can also follow the Lucee bleeding edge, which means every time you start your CommandBox server you'll get the very latest Lucee snapshot release. Please only use this for local development and not production!

server start cfengine=lucee@be

Pinning Exact Version

It is a nice feature of CommandBox to have it automatically grab the latest version of your favorite CF engine every time it starts.

# Latest Lucee 5.3.7 build
server start cfengine=lucee@5.3.7

# Latest Adobe 2018 update
server start cfengine=adobe@2018

# Lucee bleeding edge-- latest snapshot
server start cfengine=lucee@be

However, you may have good reason to NEVER want a new version automatically installed. In order to do this, you must specify a COMPLETE version number, including the build number, making sure to use the proper version format. This means you need a major, minor, patch, and build number.

# Pinned exact Adobe version
server start cfengine=adobe@2018.0.10+320417

# Pinned exact Lucee version
server start cfengine=lucee@5.3.7+48

Lucee Light builds on ForgeBox

We're now publishing CF Engines to ForgeBox based on the Lucee Light builds which allows you to start up a Lucee Light server. These are under a ForgeBox package named lucee-light and we've also backfilled all the same versions that exist for the normal lucee engine. Note, the three bullets points above apply to Lucee Light as well, Just replace lucee with lucee-light and you're good to go.

# Latest stable
server start cfengine=lucee-light

# Specific version
server start cfengine=lucee-light@5.3.4.77

# Bleeding edge
server start cfengine=lucee-light@be

If you have questions about how to install extensions into a Lucee light server, please hit us up on Slack and we can show you several ways to manage that.

What's New in 5.0.0

Upgrade Compatibility

You should be able to simply replace your box.exe binary and run it to get the same in-place upgrade you're used to. If you run into issue, you can try removing the "engine" folder in your ~/.CommandBox folder and try again. If you need to downgrade for any reason, replace the box binary with the old version, remove the "engine", "cfml", and "lib" folders in your CommandBox home and they will get re-created on the next run.

You may also notice the box binary is larger now. From 44 Megs up to 77 Megs. This is a regrettable byproduct of us turning off the Pack200 process we used to run against the Lucee jar. Lucee seems to have some bugs that causes it to re-download a bunch of OSGI bundles when we compress them and we can't figure it out, or get support on the matter, so for now we're just not compressing as much stuff. This was a huge blocker for anyone needing to run CommandBox on a PC with no external internet access as Lucee provides no mechanism to turn off it's auto-download behavior.

And finally, if you have installed any custom OSGI bundles into your CLI, they will be wiped by the upgrade process now. We didn't want to have to to do this, but Lucee has bugs that cause errors when doing in-place upgrades with the old OSGI bundles left in place and we couldn't get it fixed, so this was the only way to ensure in-place upgrades would "just work" without errors. We are leaving the Lucee engine folder, so any settings you may have put into your CLI should remain in place.

What's New?

There's a lot of new stuff in CommandBox 5.0.0. Here's an overview. One of the biggest new "features" is you can finally use CommandBox on Java 11+. This was not possible in CommandBox 4.x due to the version of Lucee not fully supporting newer versions of Java. Now that Lucee has been bumped to 5.3 (see below) you are free to leave java 8 behind for the CLI. Note if you're using CommandBox to start up older versions of Adobe CF or Lucee/Railo, you may still need to use java 8 specifically for your servers.

New Libraries

Let's start with the library updates. For the most part, all the jars we bundle are a "black box" but in reality, every update is usually for new features, fixes, or security patches. Here's an overview of the new libs:

WireBox 5.6.2
JLine 3.13.0
Runwar 4.0.3 (major bump from 3.x)
JBoss Undertow 2.0.27.Final (major bump from 1.x)
JGit 5.5.1.201910021850-r
Lucee 5.3.4.77_("major" bump from 5.2)_
AdoptOpenJDK jdk-11.0.6+10 (In the JRE-included download) (major bump from 8.x)

New Features/Enhancements

You can now use user/pass or personal access token authentication when cloning Git repos over HTTPS. This has been tested with Github and Gitlab and is an alternative to SSH keys. Please check the docs, as Github and Gitlab both expect slightly different inputs.

install git+https://username:password@domain.com/user/repo.git
or
install git+https://AccessTokenHere@github.com/user/repo.git

There is a new Lex installation endpoint to help you acquire Lucee Extensions your app needs via the "install" command or a dependency in your box.json file. If the current directory has a Lucee server in it, CommandBox will install the extension file directly into your server's "deploy" folder (server context)

install lex:https://downloads.ortussolutions.com/ortussolutions/lucee-extensions/ortus-redis-cache/1.4.0/ortus-redis-cache-1.4.0.lex

The auto-install feature into your server will work on any Lex package, even one coming from ForgeBox:

// ForgeBox slug for Ortus Redis Extension
install 5C558CC6-1E67-4776-96A60F9726D580F1

Tuning your server is easier now. You can configure your Undertow worker-threads setting with first-class server.json property

server set web.maxRequests=200

Which gives you this in your server.json

{
  "web" : {
    "maxRequests" : 200
  }
}

We've also unlocked a method for you to set ANY valid Undertow option or XNIO option. So if Undertow supports it, you can configure it!

server set runwar.undertowOptions.ALLOW_UNESCAPED_CHARACTERS_IN_URL=true

server set runwar.XNIOOptions.WORKER_NAME=myWorker

We've added a new experimental feature that lets you create a batch file, powershell script, or bash shell script that directly starts a server with the exact settings that you get from "server start". This is for you to create super-optimzed startups in Docker or Service that bypass the CLI steps and "lock in" the settings. No server.json or CFConfig, or dotenv code will be processed, but you will have a fast streamlined start that is the same every time. Couple this with our new "dryRun" flag on server start that will unpack the CF engine, but not actually start the server, and you can create your customs start script like so:

server start --console --dryRun startScript=bash startScriptFile=startmebaby.sh

// Later directly from bash...

./startmebaby.sh

The Globber helper can now take more than one globbing pattern. This also means every built-in command in CommandBox that takes a globbing pattern, can now take a comma delimited list of patterns. We've also added an exclude list of globbing patterns to the dir command as well.

dir **.cfc,*.cfm
dir paths=modules excludePath=**.md --recurse
dir paths=samples sort="directory asc, name desc"

We've got a couple new handy commands to help you from the command line, "unique" (modeled after the Bash "uniq" command)

cat names.txt | unique
cat names.txt | unique --count

And "sort" (modeled after the Bash "sort" command)

cat names.txt | sort
cat names.txt | sort type=text
cat names.txt | sort type=numeric
cat names.txt | sort direction=desc

The "grep" command has received a "count" parameter if you just want the count of lines that match the regex (or no regex will count all lines)

dir **.cfc | grep --count

dir | grep .*\.md --count

The tray icon for your servers now has a new option under the "Open" menu that will open up the file system folder where the server home lives. This is nice for finding your CF Engine's log files.

Release Notes

There are a lot of bug fixes and even more enhancements I didn't cover above. You can read the full release notes here: