• There is a fix for a regression introduced in 5.4.0 where updating the version of a CF engine doesn't work without forgetting the server first.

• There is also an important security improvement to CommandBox servers. Thanks to Abram Adams for reporting this to Ortus so we could address it.

Release notes

Note, the details of the security improvement have been tracked privately.

Bug

COMMANDBOX-1382 Java path shows up twice in "server info --verbose"

COMMANDBOX-1381 Updating server in-place keeps old web.xml path

COMMANDBOX-1375 recipe with multiple "install" instructions fails

Improvement

COMMANDBOX-1380 Add additional interceptData to server interceptors

COMMANDBOX-1379 Update to WireBox 6.5.2

COMMANDBOX-1376 Immediately activate modules after installation

COMMANDBOX-1349 Improve multiselect DSL

Story

COMMANDBOX-1120 Add JSON and Properties output for info command

Luis Fernando Majano Lainez

Luis Majano is a Computer Engineer with over 15 years of software development and systems architecture experience. He was born in San Salvador, El Salvador in the late 70’s, during a period of economic instability and civil war. He lived in El Salvador until 1995 and then moved to Miami, Florida where he completed his Bachelors of Science in Computer Engineering at Florida International University. Luis resides in Houston, Texas with his beautiful wife Veronica, baby girl Alexia and baby boy Lucas!

He is the CEO of Ortus Solutions, a consulting firm specializing in web development, ColdFusion (CFML), Java development and all open source professional services under the ColdBox and ContentBox stack. He is the creator of ColdBox, ContentBox, WireBox, MockBox, LogBox and anything “BOX”, and contributes to many open source ColdFusion projects. He is also the Adobe ColdFusion user group manager for the Inland Empire. You can read his blog at www.luismajano.com

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 grew up in southern Missouri where he systematically disassembled every toy he ever owned which occasionally led to unintentional shock therapy (TVs hold charge long after they've been unplugged, you know). After high school he majored in Computer Science with a music minor at MidAmerica Nazarene University (Olathe, KS). Today he lives in Kansas City with his wife and three girls where he still disassembles most of his belongings (including automobiles) just with a slightly higher success rate of putting them back together again.) Brad enjoys church, all sorts of international food, and the great outdoors.

Brad has been programming CFML since 2001 and has used every version of CF since 4.5. He first fell in love with ColdFusion as a way to easily connect a database to his website for dynamic pages. Brad blogs at (http://www.codersrevolution.com) and likes to work on solder-at-home digital and analog circuits with his daughter as well as building projects with Arduino-based micro controllers.

Brad's CommandBox Snake high score is 141.

Contributors

• Jorge Reyes - ColdBox Aficionado

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.

# 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

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.

# 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

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!

# 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

COMMANDBOX-1320 Server stop doesn't message user when it fails

COMMANDBOX-1319 Stop loading cfusion/lib in system class loader

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

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

COMMANDBOX-1311 Table printer error with no rows

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

COMMANDBOX-1308 Relative Web Alias Behavior (regression)

COMMANDBOX-1307 jq doesn't resolve file paths to current working directory

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

Improvement

COMMANDBOX-1328 Improve performance of piping large strings to "cfml" command

COMMANDBOX-1317 Format XML in REPL

COMMANDBOX-1316 Change default CLI JSON representation of query to array of structs

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

COMMANDBOX-1305 Update bundled java libraries

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

COMMANDBOX-1210 Allow for relative URLs when defining trayoption elements

COMMANDBOX-1194 Add Libraries To Runwar Necessary For URLRewrite Proxy

New Feature

COMMANDBOX-1324 New "printTable" command to add CLI usage of table printer

COMMANDBOX-1323 New "sql" command to filter tabular data with SQL

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

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

The source code for this book is hosted in GitHub: https://github.com/ortus-solutions/commandbox-docs. You can freely contribute to it and submit pull requests. The contents of this book is copyright by Ortus Solutions, Corp and cannot be altered or reproduced without author's consent. All content is provided "As-Is" and can be freely distributed.

• 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

We highly encourage contribution to this book and our open source software. The source code for this book can be found in our GitHub repository where you can submit pull requests.

Charitable Proceeds

15% of the proceeds of this book will go to charity to support orphaned kids in El Salvador - http://www.harvesting.org/. Please donate and purchase the printed version of this book as every book sold can help a child for almost 2 months.

Shalom Children's Home

Shalom Children’s Home (http://www.harvesting.org/) is one of the ministries that is dear to our hearts located in El Salvador. During the 12 year civil war that ended in 1990, many children were left orphaned or abandoned by parents who fled El Salvador. The Benners saw the need to help these children and received 13 children in 1982. Little by little, more children came on their own, churches and the government brought children to them for care, and the Shalom Children’s Home was founded.

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.

This release was primarily to address a regression in 5.1.0 affecting Mac OS users who tried to start Lucee servers. If you see an error similar to this on a Lucee server and you're running a Mac and CommandBox 5.1.0, then this release will fix it for you.

If you are upgrading from CommandBox 5.1.0, there are only a handful of tickets which are listed below. If you are updating from an earlier version of CommandBox, please check out our and release blogs.

Release notes

Bug

• [] - Overzealous gitignore matching of parent directories when zipping up for ForgeBox storage

• [] - Enabling SSL results in some CFHTTP requests to fail.

• [] - writedump failing in Lucee

• [] - File globbing matching partial file names

Improvement

• [] - Allow for verbose startup without debug logging of requests

There is now a new "forgebox logout" command you can use for testing or just to remove your API token from the local CLI.

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.

Read more here:

We've added better debugging information for Server Profiles. If you add the --verbose flag to your server start, you'll be able to see what profile was detected for your server, and what baked-in rules have been turned on as a result.

We've added a new Single Server Mode you can enable in the CLI to make using CommandBox in Docker images easier.

Read more here:

Release Notes

Here are the release notes for the 5.2.1 release.

Bug

New Feature

Improvement

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.

Read more about library updates here:

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

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

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.

‌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:

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

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

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:

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:

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.

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.

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:

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:

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.

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

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:

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:

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:

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:

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

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

Java 14 support

Java 14 is now supported in CommandBox 5.1.0. In order to support Java 14, we had to stop using Pack200 which means the binary sizes have grown a little. The good news is CommandBox will start up a little faster on its first run since there's less to unpack now.

Start pure HTML Server

You can start up a lightweight server that only serves static files now with CommandBox.

New CommandBox Light and CommandBox Thin Binaries

In pursuit of the smallest possible Docker images, we have CommandBox light which is built on Lucee Light. We also have a box "thin" binary you can swap out with the full self-extracting binary when using CommandBox in custom docker images. Check out Pete Freitag's to see both of these in use in a super tiny 78 Meg docker image. More docs here:

Force working directory when starting

If you're using box in an integration where you want it to start up in a specific working directory, there is a new bootstrap CLI arg for that.

Server tray menu item custom commands

You've always been able to specify custom menu items in your server.json or global config settings, but we've kicked it up a notch. Not only can you contribute to existing sub menus now, you can execute arbitrary native commands synchronously or async.

Release Notes

Here's the full list of tickets closed down in the 5.1.0 release.

Bug

New Feature

Task

Improvement

Here's the full list of what we've packed into the 4.7.0 release. Click any ticket link for more details.

Bug

• [COMMANDBOX-962] - CommandBox not recognizing implicit folder endpoint

• [COMMANDBOX-967] - Update semver for fix in prerelease comparison

• [COMMANDBOX-970] - Tokenizer breaks "run" command with odd syntax

• [COMMANDBOX-972] - init-wizard command is incorrectly aliasing as init

• [COMMANDBOX-978] - File watcher that modifies the file system triggers the watcher again

• [COMMANDBOX-985] - bump command doesn't work on a submodule

• [COMMANDBOX-986] - Text on standard input causes banner and prompt to be blank

• [COMMANDBOX-988] - Inconsistent behavior of "run" command.

• [COMMANDBOX-989] - Tab completion incorrect for some partial command names

• [COMMANDBOX-990] - Interactive jobs are not thread safe

Improvement

• [COMMANDBOX-956] - Leading zeros in semver prevent them from being matched

• [COMMANDBOX-957] - Allow --verbose flag on uninstall command

• [COMMANDBOX-958] - Add --roundup flag to indents command

• [COMMANDBOX-959] - JSON Schema for box.json

• [COMMANDBOX-968] - Update JGit to 5.3.0.201903130848-r

• [COMMANDBOX-969] - Update Jline to 3.10.0

• [COMMANDBOX-971] - Remove Riaforge endpoint Rince riaforge is dead

• [COMMANDBOX-973] - Modify default box.json from "init" command

• [COMMANDBOX-974] - Add box: namespace for compat with Coldbox injection DSL

• [COMMANDBOX-976] - Improve debugging and error messages for custom ForgeBox endpoints

• [COMMANDBOX-979] - If the test runner produces a 500 exception during watcher no output is shown

• [COMMANDBOX-982] - support for Environment variables in "Key" names

• [COMMANDBOX-983] - Make env vars in CommandBox visible to native OS binaries

• [COMMANDBOX-984] - Launching VSCode from ConEMU screws up the integrated terminal

• [COMMANDBOX-987] - Keep relative installPaths in box.json

The main features of CommandBox 4.5.0 are:

• Ability to install OpenJDK automatically for your servers to use (read more)

• Environment Variables in the shell (read more)

• Support for Forgebox Enterprise (TBA soon)

• JRE Bundled CommandBox installs now use OpenJDK instead of Oracle JDK

• TestBox Code Coverage integration (read more)

I already wrote a fairly comprehensive overview of the new features and big fixes here. Go read it:

https://www.ortussolutions.com/blog/commandbox-450-rc-release-candidate-ready-for-testing

Note, there are two backwards incompatible changes. The first is we turned OFF directory browsing by default on servers. You can easily get the old behavior back with

config set server.defaults.web.directoryBrowsing=true

The second is that unhandled errors in the shell no longer show the stack trace (you probably wouldn't have noticed if I didn't tell you!) Get the old behavior back with:

config set verboseErrors=true

Release Notes

Here's the full list of everything that went into this release.

Bug

• [COMMANDBOX-784] - editing in the shell prompt is buggy while using Gitbash in VSCode

• [COMMANDBOX-895] - Passing positional args to task errors with required param

• [COMMANDBOX-897] - Passing command string as single arg to box fails

• [COMMANDBOX-899] - Exitting recipe with exit code errors

• [COMMANDBOX-901] - external module mappings broken in CommandBox 4

• [COMMANDBOX-903] - Incorrect behavior when parsing unmatched quotes

• [COMMANDBOX-915] - Cruft left in temp folder

• [COMMANDBOX-917] - Silence annoying ESAPI warnings

• [COMMANDBOX-919] - Warnings on java 11 about illegal reflective access

New Feature

• [COMMANDBOX-516] - Add concept of env vars for commands to use

• [COMMANDBOX-906] - Add preCommandParamProcess interception point

• [COMMANDBOX-907] - outdated commands now verify packages in parallel

• [COMMANDBOX-908] - Automatically download JRE for server if specified by version range

• [COMMANDBOX-910] - Support multiple ForgeBox endpoints

• [COMMANDBOX-911] - New Java endpoint that ties into the AdpotOpenJDK builds

• [COMMANDBOX-914] - Make exit code of native binary from run command available in the exception that is thrown

• [COMMANDBOX-916] - Pull Code Coverage data on "testbox run"

• [COMMANDBOX-921] - Allow recipe args to be used as environment variables for that command

Improvement

• [COMMANDBOX-896] - Add ETA to progress bar when downloading

• [COMMANDBOX-898] - Improve default handling of JVM heap size

• [COMMANDBOX-900] - Default directoryBrowsing to false

• [COMMANDBOX-902] - Allow box to be called with a single string containing a command chain

• [COMMANDBOX-904] - Prevent folder endpoint from picking up folders in CWD on install

• [COMMANDBOX-909] - Hide stack trace by default when CLI errors

• [COMMANDBOX-922] - Allow recipe command to accept arbitrary commands directly

• [COMMANDBOX-923] - Include mapping-tag in rewrite exclusion list

• [COMMANDBOX-924] - Update JRE builds to use OpenJDK instead of Oracle JDK

• [COMMANDBOX-925] - Provide all other args to command completor UDFs

• [COMMANDBOX-926] - Announce postInstall interceptions even if package was found to be already installed

Release Notes

Bug

• [COMMANDBOX-934] - Server commands can have huge delay on Windows

• [COMMANDBOX-937] - List artifacts alphabetically.

• [COMMANDBOX-939] - /usr/bin/open on Linux

• [COMMANDBOX-942] - Errors in command CFCs can cause box to exit completely during tab complete

• [COMMANDBOX-949] - Running native binary that returns lots of text can perform poorly

• [COMMANDBOX-950] - Interceptor service blows up if you register a module with an interceptor not matching any current states

• [COMMANDBOX-951] - Allow modules to register an interceptor with no currently valid states

• [COMMANDBOX-953] - Catch errors from desktop.isDesktopSupported()

New Feature

• [COMMANDBOX-930] - Allow system setting (env var) expansions in REPL

• [COMMANDBOX-932] - Improve task DSL to allow access to exit code

• [COMMANDBOX-944] - Add config setting to debug raw native command being used in the "run" command

Improvement

• [COMMANDBOX-249] - Enforce correct casing conventions on scaffolding commands

• [COMMANDBOX-927] - Update propertyFile core module

• [COMMANDBOX-928] - Improve default ignores in box.json from init command.

• [COMMANDBOX-929] - Disable ping to time server host by default

• [COMMANDBOX-931] - Allow exit code to be returned via "return" keyword

• [COMMANDBOX-935] - Improve syntax highlighting in REPL

• [COMMANDBOX-938] - Checking interrupted status from inside a thread doesn't end the task/command

• [COMMANDBOX-943] - Remove hint from default CFC in Lucee for CommandBox CFCs with no hint of their own

• [COMMANDBOX-945] - Endpoint URL shows incorrectly for forgebox endpoints

• [COMMANDBOX-948] - Enhance tab complete for private slugs

Upgrade Compatibility

Even though this is a new major version, it should be very backwards compatible. CommandBox proper has no known backwards compatibility issues we're aware of, but note we've bumped libraries like Lucee Server, Undertow, and Java support, so you may notice differences due to these 3rd party lib updates. For example, one breaking change in Lucee 5.3 (which now powers your default server) is how page output buffer is handled.

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:

Sub-task

• [COMMANDBOX-1069] - Remove extra stashes on url paths when servlet init params starts with WEB-INF

Bug

• [COMMANDBOX-643] - Tray Icon not displaying on Debian8

• [COMMANDBOX-711] - X Window Errors

• [COMMANDBOX-812] - "Coldbox create resource" uses wrong paths on Windows

• [COMMANDBOX-941] - urlrewrite.xml has file size of 0 on docker restart but not regular start

• [COMMANDBOX-946] - CommandBox instances crashing because of TrayIcon rendering

• [COMMANDBOX-975] - CommandBox always reads STDIN even when in non-interactive mode

• [COMMANDBOX-980] - Using zsh exits out of CommandBox when running a binary command

• [COMMANDBOX-992] - Shebang scripts no longer work without .cfm extension

• [COMMANDBOX-1005] - If custom rewrite file is already in correct destination, runwar overwrites it as 0 bytes

• [COMMANDBOX-1008] - worker-threads setting no longer has any affect

• [COMMANDBOX-1009] - Tray icon not showing in Ubuntu 18.04

• [COMMANDBOX-1013] - Undertow error output when starting server

• [COMMANDBOX-1014] - [RUNWAR] Tray menu placeholders such as ${Setting: runwar.port not found} are not replaced in sub menus

• [COMMANDBOX-1022] - regex string index out of bounds exception

• [COMMANDBOX-1035] - URL Rewrites fire incorrect on URL containing a space

• [COMMANDBOX-1036] - Browser doesn't open when server start

• [COMMANDBOX-1037] - Host updater does not work

• [COMMANDBOX-1038] - Server doesn't stop on Windows

• [COMMANDBOX-1043] - ConcurrentModificationException with undertow?

• [COMMANDBOX-1048] - Restrict /dumprunwarrequest to be used only on Unit Testing

• [COMMANDBOX-1050] - Remove trailing slash from Adobe updates path

• [COMMANDBOX-1054] - Default command parameters don't work on commands in namespaces

• [COMMANDBOX-1061] - Command DSL has unexpected behavior with equals sign in positional tokens

• [COMMANDBOX-1062] - Tab complete for negated flags isn't complete

• [COMMANDBOX-1063] - box fails to open in vSphere Web Client console due to outdated JLine jar

• [COMMANDBOX-1068] - Server start doesn't correctly expand relative Java Home directory

• [COMMANDBOX-1070] - slashes into the servlet init param paths

• [COMMANDBOX-1071] - Tray icon doesn't disappear on Windows when server stops from CLI

• [COMMANDBOX-1076] - Install dependency from box.json with env var placeholder gets overwritten with actual value

• [COMMANDBOX-1077] - coldbox create resource command ignores specsDirectory argument

• [COMMANDBOX-1079] - foreach cannot be interrupted with Ctrl-C

• [COMMANDBOX-1081] - validate non-numeric exit codes from the "exit" command

• [COMMANDBOX-1089] - Task Runner's loadModule() fails on path with period

• [COMMANDBOX-1090] - Tasks don't treat return 1 and setExitCode( 1 ) the same

• [COMMANDBOX-1091] - When a task sets a failing exit code, no output is sent to console

• [COMMANDBOX-1092] - Commands that set a failing exit code don't raise proper exception

• [COMMANDBOX-1098] - foreach, grep, and sed only break on chr(10)

New Feature

• [COMMANDBOX-148] - Ability to install/uninstall box server services

• [COMMANDBOX-715] - Server command to explode server war but not start it

• [COMMANDBOX-1007] - Set any valid XNIO option

• [COMMANDBOX-1018] - Add generic feature to set any valid Undertow option

• [COMMANDBOX-1028] - Allow no rest mappings to be supplied

• [COMMANDBOX-1032] - Tab completion for task targets

• [COMMANDBOX-1052] - New TestBox commands: generate visualizer and generate browser

• [COMMANDBOX-1053] - Update ColdBox module templates for 5.0 standards

• [COMMANDBOX-1067] - Expose Undertow worker-threads setting with first-class server.json property

• [COMMANDBOX-1075] - Support HTTPS username/password auth

• [COMMANDBOX-1083] - Option for server start to write file with full start args for direct Runwar call

• [COMMANDBOX-1088] - Add lex endpoint for installing Lucee extensions

• [COMMANDBOX-1096] - Add unique command to filter out duplicates rows of input

• [COMMANDBOX-1097] - Add sort command to sort rows of input

Task

• [COMMANDBOX-964] - Make sure the build works

• [COMMANDBOX-965] - Document Setup in the Repo

• [COMMANDBOX-995] - Vet all changes on Runwar since April 25, 2018.

Improvement

• [COMMANDBOX-885] - Enhance Globber to take more than one pattern

• [COMMANDBOX-886] - Enhance Globber to have exclude patterns

• [COMMANDBOX-963] - Update CLI to Lucee 5.3 and test Java 11

• [COMMANDBOX-1029] - Change CommandBox build to pull Ortus build of Runwar

• [COMMANDBOX-1049] - Output Runwar version and jar path in "info" command output

• [COMMANDBOX-1055] - Need Config for Max Thread Request at runwar

• [COMMANDBOX-1057] - Enhance dir command with new Globber features

• [COMMANDBOX-1058] - Optimize installation of packages with createPackageDirectory set to false

• [COMMANDBOX-1059] - Improve performance of print buffer by using String Builder internally

• [COMMANDBOX-1060] - Add --count flag to grep command

• [COMMANDBOX-1065] - Update CommandBox to Runwar 4.0.0

• [COMMANDBOX-1066] - Upgrade to JGit 5.5

• [COMMANDBOX-1074] - Tie into FusionReactor to report transactions for tasks, commands, etc.

• [COMMANDBOX-1086] - Default location to forgeboxStorage for package init command

• [COMMANDBOX-1087] - Improve default package naming of jar endpoint

• [COMMANDBOX-1093] - Add option to tray menu to open server home directory

• [COMMANDBOX-1095] - Update to latest WireBox

• [COMMANDBOX-1099] - Stop outputting extra line break for commands with no output

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...

• Custom commands have more control over their tab completion candidates. Docs Here

• 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)

• Automatic detection for build servers like Travis-CI to hide progress bar animations. Docs Here

• Cloning Git repos during install has a nice new progress bar that plays well with interactive jobs

• You can use the aforementioned progress bar for your own purposes in custom commands and Task Runners. Docs Here

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.

https://commandbox.ortusbooks.com/usage/execution/exit-codes

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.

https://commandbox.ortusbooks.com/usage/execution/exit-codes#assertions

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:

https://commandbox.ortusbooks.com/package-management/code-endpoints/s3

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

• [COMMANDBOX-417] - .zip files in artifacts cache don't include empty folders

• [COMMANDBOX-808] - "bash: no job control in this shell" error message (pull request)

• [COMMANDBOX-809] - external commands/shells that are interactive (such as vi) are not working when executed from commandBox

• [COMMANDBOX-810] - tab hinting colors wrong in PowerShell terminals.

• [COMMANDBOX-811] - System settings not always used in server.json

• [COMMANDBOX-829] - "testbox run" formats outputfile as JSON even if it's not

• [COMMANDBOX-833] - Piping input to CommandBox broken

• [COMMANDBOX-834] - Bleeding edge upgrades show wrong URL after S3 artifacts move

• [COMMANDBOX-835] - --debug doesn't dump job logs on error

New Feature

• [COMMANDBOX-814] - Allow arbitrary command params to have file/folder completion via annotation

• [COMMANDBOX-815] - Allow custom completion UDFs to provide group and description

• [COMMANDBOX-839] - New conditional commands pathExists, assertTrue and assertEqual

• [COMMANDBOX-840] - Allow access to previous exitCode as system setting

• [COMMANDBOX-841] - Allow user to exit shell with specific exit code

• [COMMANDBOX-842] - Improve recipe handling of exitCodes

Improvement

• [COMMANDBOX-746] - Compact package listing

• [COMMANDBOX-779] - Write a custom JGit progress updater that clears out at the end

• [COMMANDBOX-813] - Hide JLine warning about dumb terminals

• [COMMANDBOX-817] - S3 Endpoint

• [COMMANDBOX-818] - Upgrade to JGit 5.0.1

• [COMMANDBOX-819] - Upgrade to Launch4J 3.12

• [COMMANDBOX-820] - Skip forgebox checks on server start with server home dir that's already installed.

• [COMMANDBOX-821] - Upgrade to JLine 3.8.2

• [COMMANDBOX-823] - Pack200 Lucee bundles

• [COMMANDBOX-825] - Upgrade to Lucee 5.2.8.50

• [COMMANDBOX-826] - Default rewrites support /pms servlet used for Adobe CF 2018 performance monitor

• [COMMANDBOX-827] - Default nonInteractiveShell setting in commonly known build environments

• [COMMANDBOX-828] - Improve messaging when initting private package

• [COMMANDBOX-837] - Reorganize the tray menus

• [COMMANDBOX-843] - Upgrade to Wirebox 5.1

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

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:

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:

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:

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:

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:

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.

You can view and tail this log file like so:

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.

You can view and tail this log file like so:

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.

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.

Task DSL

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

Example:

(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:

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:

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

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.

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.

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.

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 will always re-download snapshot versions of packages to make sure you get a fresh version.

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.

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.

Server Welcome Files

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

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:

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.

Read more about this here:

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.

Read more about this here.

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

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.

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.

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

"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:

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.

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