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.

• Versions 5.x - Mar 2020 - May 2021

• Versions 4.x - Jun 2018 - Sept 2019

• Versions 3.x - Feb 2016 - Nov 2017

• Versions 2.x - June 2015 - Nov 2015

• Versions 1.x - Feb 2015

• 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

Release Notes

Bug

COMMANDBOX-1374 Some installs unnecessarily write to the box.json

COMMANDBOX-1370 ConfigService::settingExists() fails in race conditions due to non-varscoped variables in JSONService

Improvement

COMMANDBOX-1372 Support excludePaths in watcher DSL and watch command

COMMANDBOX-1369 Ensure Adobe wars have a seeds.properties file

COMMANDBOX-1368 Add tab complete for "env clear" command

COMMANDBOX-1367 Ignore empty startScript on server start

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

• Version 5.4.2 - October 2021

• Version 5.4.1 - September 2021

• Version 5.4.0 - August 2021

• Version 5.3.0 - May 2021

• Version 5.2.1 - Dec 2020

• Version 5.2.0 - Nov 2020

• Version 5.1.1 - June 2020

• Version 5.1.0 - May 2020

• Version 5.0.0 - Mar 2020

web.xml Overrides

When you start an Adobe or Lucee CF Engine, the WAR CommandBox uses has a stock web.xml baked into it. Sometimes you may want to add custom servlets, servlet mappings, etc into your server. You can override the stock web.xml in part or in total with a file of your own which you specify in the server.json like so:

{
  "app" : {
    "webXMLOverride" : "path/to/web-override.xml"
  }
}

More info here:

https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/web.xml-overrides

Funky Parameters

In addition to quoting parameter values, parameter names can also be quoted. This is useful when setting keys into settings or JSON files that have spaces, hyphens or special characters. Each of these examples are now supported:

# quoted string
package set foo."bar.baz"=bum

# bracketed string
package set foo[bar.baz]=bum

# quoted, bracketed string
package set foo["bar.baz"]=bum

More info here:

https://commandbox.ortusbooks.com/usage/parameters

Library updates

Lucee Server has been updated to 5.3.8.201 and JBoss Undertow has been updated to 2.2.10.Final. The Lucee update, as usual, applies to the CLI as well as the default server you get when you run server start.

Smarter Jar Endpoint

When you install a Jar via HTTP URL and the version number is baked into the URL, the jar endpoint now makes more assumptions about what the version of the package is that allows it to optimize the update checks and eliminate unnecessary downloads.

More info here:

https://commandbox.ortusbooks.com/package-management/code-endpoints/jar-via-http#semantic-versioning

ask and confirm commands

Here are some fun commands for user interactivity in the shell. You can use these as part of a recipe or a nice "one-liner".

ask

The ask command is similar to the ask() method in Task Runners. It requires an interactive terminal and will ask the user a question and return their answer. It is meant to be changed with other commands.

set color=`ask "favorite Color? "`
echo "you said ${Setting: color not found}"

or with default values

ask question="Who is cool? " defaultResponse="Balbino!"

or with masked input

ask question="What is your password? " mask=*

Or fun stuff like this

ask "Secret phrase: " | assertEqual "mockingbird" || echo "access denied!" && exit 1

confirm

The confirm command will ask the user a yes/no question and return a passing or failing exit code from the command based on the answer.

confirm "do you want to update your packages? " && update

Remember the && operator will only execute the second command if the first command returns an exit code of 0.

More info here:

https://commandbox.ortusbooks.com/helpful-commands/ask-and-confirm

server prune command

You can easily forget all servers which have not been started for a certain period of time with the server prune command. It accepts the number of days that need to have passed since a server was last started in order to prune it.

server prune days=30

# Skip the confirmation check
server prune --force

More info here:

https://commandbox.ortusbooks.com/embedded-server/manage-servers#prune-old-servers

Release Notes

Here are the full release notes for CommandBox 5.4.0

Bug

COMMANDBOX-1364 Cancelling a prompt with active job doesn't clear job logs

COMMANDBOX-1361 Param tab completion is off-by-one when piping

COMMANDBOX-1360 Can't list files in directory with brackets ( [ or ] ) in the name

COMMANDBOX-1356 forgebox timeout is too small when publishing packages

COMMANDBOX-1354 dir command returns no results in drive root

COMMANDBOX-1353 Summary over 200 chars in box.json causes error when publishing

COMMANDBOX-1352 Addition of Apache logging classes breaks 3rd party libs using it

COMMANDBOX-1350 Installing a system module as one-off command doesn't clear wirebox metadata cache

COMMANDBOX-1348 Commenting server rules doesn't work correctly in text files

COMMANDBOX-1346 CommandDSL doesn't handle struct args

COMMANDBOX-1344 create a server prune command

COMMANDBOX-1339 Server start can hang when CF engine blows up

COMMANDBOX-1338 Tab complete doesn't work after a pipe

COMMANDBOX-1337 Working dir of server custom menu items doesn't default properly

COMMANDBOX-1336 Error when setting failing exist code in Task Runner

COMMANDBOX-1334 updating commandbox to 5.3.1 via Homebrew breaks with a java error

COMMANDBOX-1333 Rewrite rule with query string doubles up question mark

COMMANDBOX-1332 printTable column validation breaks with spaces in list

COMMANDBOX-1330 Directory listing not showing folders properly when names are numeric

COMMANDBOX-1230 Certain Java installs fail version check

Improvement

COMMANDBOX-1366 ask and confirm command to capture user input from shell

COMMANDBOX-1365 Improve version handling in JAR endpoint

COMMANDBOX-1351 Update to Lucee 5.3.8

COMMANDBOX-1347 Support dots in struct keys with set/show/clear commands

COMMANDBOX-1342 printTable custom header names for non-array input

COMMANDBOX-1331 Add printTable check for data with no columns

COMMANDBOX-1329 Sort column names in printTable --debug

New Feature

COMMANDBOX-1362 Set env vars directly in server.json for local one-off overrides

COMMANDBOX-1011 Support web.xml Overrides

Task

COMMANDBOX-1363 Update to Undertow 2.2.10.Final

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.

lucee.runtime.exp.NativeException: mac os x is not a supported OS platform.

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 5.0.0 and 5.1.0 release blogs.

Release notes

Bug

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

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

• [COMMANDBOX-1178] - writedump failing in Lucee

• [COMMANDBOX-1179] - File globbing matching partial file names

Improvement

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

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:

https://ortussolutions.atlassian.net/browse/COMMANDBOX-1064

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:

https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/server-profiles

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

There are TON of built in predicates and handlers your rules can use. We've documented some of them here:

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:

https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/server-rules

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:

https://commandbox.ortusbooks.com/task-runners/lifecycle-events

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:

https://commandbox.ortusbooks.com/usage/system-setting-expansion-namespaces

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:

https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/gzip-compression

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:

https://commandbox.ortusbooks.com/usage/watch-command

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:

https://commandbox.ortusbooks.com/config-settings/misc-settings#preferredbrowser

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]

https://ortussolutions.atlassian.net/browse/COMMANDBOX-1221

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

https://ortussolutions.atlassian.net/browse/COMMANDBOX-1209

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.

https://commandbox.ortusbooks.com/usage/execution/os-binaries#piping-to-the-native-binarys-standard-input

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

• [COMMANDBOX-1138] - Tuckey UrlRewrite DTD version issues

• [COMMANDBOX-1141] - when installing a package which doesn't exist, commandbox claims forgebox is unreachable

• [COMMANDBOX-1199] - Remove mail-4.1.1.jar from runwar's lib dir

• [COMMANDBOX-1201] - "testbox run" output garbled on Windows (wrong encoding)

• [COMMANDBOX-1205] - UndertowOptions and XNIOOptions don't work for Long type

• [COMMANDBOX-1206] - HTTP endpoint leaves a zip file in the CommandBox temp folder

• [COMMANDBOX-1213] - url rewrite no longer works

• [COMMANDBOX-1218] - Piping a command into run does not execute interactivley

• [COMMANDBOX-1221] - Support flags on .htaccess file for Tuckey rewrites

New Feature

• [COMMANDBOX-126] - Restart server via tray icon

• [COMMANDBOX-1012] - Stop expanding /WEB-INF paths in servlet init params

• [COMMANDBOX-1021] - Allow configuring default browser to use when opening a URL

• [COMMANDBOX-1084] - Add a preInstallAll and postInstallAll interception points when running an `install` command

• [COMMANDBOX-1167] - Add Task Runner lifecycle events

• [COMMANDBOX-1197] - Generic watch command

• [COMMANDBOX-1200] - When starting an already-started server, offer to open the existing one instead

• [COMMANDBOX-1209] - Add directory expansion command for going back multiple directories

• [COMMANDBOX-1214] - Add built-in predicates and handlers for undertow for easier lockdown

• [COMMANDBOX-1215] - Add "profile" setting to help default security settings

• [COMMANDBOX-1220] - Allow standard input to be piped to native binaries

Task

• [COMMANDBOX-1064] - review all the runwar dependencies and check for outdated ones

Improvement

• [COMMANDBOX-1044] - Block TRACE HTTP Verb by default

• [COMMANDBOX-1094] - Implement web server rules in Undertow

• [COMMANDBOX-1103] - Add an option to console log output without ANSI codes

• [COMMANDBOX-1109] - Migrate to AdoptOpenJDK API v3

• [COMMANDBOX-1131] - Move ANSI logging format from Runwar to CommandBox

• [COMMANDBOX-1157] - Automated flag negation hint is the same as the hint for the flag itself

• [COMMANDBOX-1182] - Default server menu actions working directory to web root

• [COMMANDBOX-1183] - Expand working directory when specified for a menu item

• [COMMANDBOX-1191] - Validate incoming version for bump command

• [COMMANDBOX-1192] - Programmatic skipping of package install via interceptor

• [COMMANDBOX-1193] - Adding support for installing lex files from file or unc paths

• [COMMANDBOX-1195] - Add File Filtering For GZIP Compression

• [COMMANDBOX-1196] - Allow default server java version to be cleared

• [COMMANDBOX-1198] - Add setSystemSetting() to BaseCommand

• [COMMANDBOX-1202] - "testbox run" command - show tag context for global bundle exceptions

• [COMMANDBOX-1203] - Add --trayEnable flag to server start

• [COMMANDBOX-1204] - Allow ${} system setting expansions to have extendable namespaces

• [COMMANDBOX-1208] - Improve verbose output of JVM args if args contain " - " in them

• [COMMANDBOX-1217] - forgeboxstorage default ignores are over-aggresive

• [COMMANDBOX-1219] - If native command is piped into RUN, allow the output to be piped again

Sub-task

• [COMMANDBOX-1185] - Load predicates in Runwar

• [COMMANDBOX-1186] - Pass Predicates as part of Server Start in CommandBox

• [COMMANDBOX-1187] - Add default server rules/predicates in CommandBox for default lockdown

• [COMMANDBOX-1188] - Improve logging in Undertow for execution of predicate handlers

• [COMMANDBOX-1189] - Track/address Undertow tickets

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

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

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.

server start cfengine=none

https://commandbox.ortusbooks.com/v/5.1.0/embedded-server/start-html-server

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 Minibox image to see both of these in use in a super tiny 78 Meg docker image. More docs here:

https://commandbox.ortusbooks.com/v/5.1.0/setup/light-and-thin-binaries

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.

box -cliworkingDir=C:/my/path/here/

https://commandbox.ortusbooks.com/v/5.1.0/usage/execution#custom-working-directory

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.

{
    "trayOptions" : [
        {
            "label" : "Does the Internet work?",
            "action" : "run",
            "command" : "ping google.com"
        },
        {
            "label" : "Math is math!",
            "action" : "runAsync",
            "command" : "calc.exe"
        },
        {
            "label" : "Update dependencies",
            "action" : "runTerminal",
            "command" : "box update"
        }
    ]
}

Release Notes

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

Bug

• [COMMANDBOX-1121] - Runwar deadlocks when using Lucee server warmup flag

• [COMMANDBOX-1122] - Server start console output isn't always formatted correctly

• [COMMANDBOX-1125] - Boolean env var causes error on server start

• [COMMANDBOX-1127] - Output of foreach can't be piped

• [COMMANDBOX-1133] - Lucee Extension install doesn't recognize Lucee Light

• [COMMANDBOX-1135] - Package unlink command misspelled parameter moduleDirectory as moduleDrectory

• [COMMANDBOX-1137] - Package link command misspelled parameter moduleDirectory as moduleDrectory

• [COMMANDBOX-1140] - Tab complete doesn't work on Windows paths with backslashes

• [COMMANDBOX-1144] - CommandBox Watcher shows error on Ctrl-C

• [COMMANDBOX-1148] - Extension management doesn't "recognize" a Lucee server started with --dryRun

• [COMMANDBOX-1151] - Downgrading a package with install doesn't work without --force

• [COMMANDBOX-1152] - The run command doesn't always seem to kill interactive binaries

• [COMMANDBOX-1154] - Relative paths incorrect in drive root on *nix

• [COMMANDBOX-1166] - Using a warPath of ./ gets normalized to "" and then ignored in subsequent starts

• [COMMANDBOX-1176] - native commands with * can fail due to missing regex escape

• [COMMANDBOX-1177] - Incorrect serverInfo for a server that hasn't started

New Feature

• [COMMANDBOX-1015] - Allow arbitrary actions for menu items

• [COMMANDBOX-1019] - Allow to start a pure HTML server

• [COMMANDBOX-1130] - Update ColdBox Templates to new standards

• [COMMANDBOX-1145] - Allow default working dir of box to be overridden

• [COMMANDBOX-1146] - Create box-thin binaries that don't bundle any libs

• [COMMANDBOX-1147] - Create CommandBox Light built that uses Lucee Light jar

• [COMMANDBOX-1153] - Add two new methods to commands for working with async futures: getCurrentThread() getThreadName()

• [COMMANDBOX-1170] - TestBox run commands now support the outputFormats argument to allow you to output post-test reports in many formats

• [COMMANDBOX-1171] - TestBox revamped UI for the CLI reporter

• [COMMANDBOX-1172] - Add Java info debug to box binary

Task

• [COMMANDBOX-1102] - Add Java version as info log

Improvement

• [COMMANDBOX-1080] - Provide way to disable server instance icon in MacOS dock

• [COMMANDBOX-1126] - Add --full flag to dir command to output full path

• [COMMANDBOX-1129] - Rework the server list command so it is more performant

• [COMMANDBOX-1132] - Bump to Lucee 5.3.6.61

• [COMMANDBOX-1134] - Tab complete for sort options in dir command

• [COMMANDBOX-1143] - Have the ProgressableDownloader send an Accept header

• [COMMANDBOX-1150] - Don't overwrite lucee-server.xml file when updating libs

• [COMMANDBOX-1155] - Auto-detect *unix distros with non-bash shells

• [COMMANDBOX-1156] - Copy lco files so Lucee server can start on CommandBox Light

• [COMMANDBOX-1168] - Reset console window title after `run` executes a process

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

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

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

Task Target Dependencies

For a task that has more than one target (method) you can specify dependencies that will run, in the order specified, prior to your final target. Specify task target dependencies as a comma-delimited list in a depends annotation on the target function itself. There is no limit to how many target dependencies you can have, nor how deep they can nest.

component {
  
  function run() depends="runMeFirst" {
  }

  function runMeFirst() {
  }

}

Given the above Task Runner, typing

task run

would run the runMeFirst() and run() method in that order.

Docs:

https://commandbox.ortusbooks.com/task-runners/task-target-dependencies

GZip Compression

The web server in CommandBox is capable of enabling GZIp compression to reduce the size of HTTP responses. To enable GZip compress on your CommandBox server, add a web.gzipEnable setting in your server.json file.

server set web.gzipEnable=true

Docs: https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/gzip-compression

Add --simple flag to ls/dir command

When you get a directory listing in CommandBox, you can add the --simple flag which will only output the file and folder name without any other information. This feature was added to compliment the feature below.

ls --simple

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 example will find all JSON files in a directory and run the cat command against them.

ls *.json --simple | forEach cat

Docs: https://commandbox.ortusbooks.com/usage/foreach-command

Java 9/10/11 support

This is still a little experimental since it hasn't gone through full testing, but we upgraded to Lucee 5.2.9.31 in the core CLI which has support for the newer versions of Java. We've removed the checks that previously preventing CommandBox from even trying to run on versions of Java later than 8 and at first glance it seems to be working though there's been some flakiness on Java 11. Please help test these later Java versions and remember that if you spin up a server, you'll want to still dial in Java 8 for Adobe CF 2016 and prior and Lucee 5.2.8.50 and prior even if you have the CLI running on Java 9+.

Docs for setting custom Java version in your server:

https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/custom-java-version

Release notes

Here's the full release notes for CommandBox 4.3.0.

Bug

• [COMMANDBOX-692] - Command Box failed to initialize using java 9

• [COMMANDBOX-845] - CFFileServlet doesn't work with default rewrites in ACF 2016

• [COMMANDBOX-849] - We need to review exit codes in Tasks

• [COMMANDBOX-856] - WireBox/LogBox upgrade broke system logging

• [COMMANDBOX-857] - Engine name not detected correctly when using HTTP URL for cfengine

• [COMMANDBOX-860] - Fix annoying web-inf folder for Flex logs on Adobe engines

• [COMMANDBOX-861] - Missing line break when following log file

• [COMMANDBOX-865] - Spelling error in info message for accessLogEnable

• [COMMANDBOX-867] - coldbox create app cuts last char from package name

• [COMMANDBOX-869] - Starting Adobe server errors when no CFIDE mapping is defined

• [COMMANDBOX-871] - CommandDSL parsing doesn't handle quoted text in command

New Feature

• [COMMANDBOX-848] - Task method dependencies

• [COMMANDBOX-852] - Add setting for GZip compression

• [COMMANDBOX-858] - Add --simple flag to ls/dir command to only output filename

• [COMMANDBOX-859] - Add "forEach" command to execute command once per incoming line

Improvement

• [COMMANDBOX-824] - TestBox Run command could use a way to add custom url parameters. Also the options parameter does nothing

• [COMMANDBOX-846] - Improve progress bar cleanup and exit codes on Ctrl-C

• [COMMANDBOX-851] - Allow Java jars to be installed from S3

• [COMMANDBOX-854] - JSON Schema for server.json

• [COMMANDBOX-863] - Upgrade CLI to Lucee 5.2.9.31

• [COMMANDBOX-864] - Support sorting JSON objects by key when formatting

• [COMMANDBOX-866] - Task DSL assume CWD of task file

• [COMMANDBOX-868] - coldbox scaffold install testbox by default

• [COMMANDBOX-870] - Allow command DSL params() to be called more than once

• [COMMANDBOX-872] - Make resolvePath() in Base command/task

• [COMMANDBOX-873] - Reload shell doesn't always fire when non-CommandBox modules get updated in core

• [COMMANDBOX-874] - Allow print helper to accept complex objects and serialize them for output.

Cached HTTP Downloads

You can now cache downloads using the HTTP(S) endpoints using the following syntaxes:

install https+cached://downloads.ortussolutions.com/ortussolutions/coldbox-modules/cbi18n/1.4.0/cbi18n-1.4.0.zip

start cfengine=http+cached://update.lucee.org/rest/update/provider/forgebox/5.3.3.60-RC

This will speed up builds.

Change to Previous Directory

Thanks to a pull request from John Berquist, we've borrowed a Bash and Powershell feature of being able to change back to your previous working directory by typing this:

cd -

Better Tab Completion

Thanks to more pull requests from John Berquist, you can use file and folder based tab completion when typing native binaries from CommandBox

!foo bar "C:/Program Files/baz/myFile.cf_

And tab completion also works better now when typing a quoted string such as a file path that contains a space. This is a huge timesaver!

cd "C:/program Fi_

Access to Intercept data in package scripts

Package scripts that are fired from internal interception points, can access any intercept data via environment variables. This example writes a file into a server home directory when the server starts, using an environment variable to dynamically find the correct path.

package set scripts.onServerStart="touch \$ {interceptData.SERVERINFO.serverHomeDirectory}/hi.txt"

Release Notes

Here are the full release notes for CommandBox 4.8.0:

Bug

• [COMMANDBOX-991] - Can't always install modules - git error: Directory already exists

• [COMMANDBOX-994] - regex metachars not escaped properly in first token of run command

• [COMMANDBOX-998] - testbox watch command doesn't obey verbose flag in box.json

• [COMMANDBOX-999] - Sometimes line breaks leak to console when using expansions

• [COMMANDBOX-1000] - Pass ad-hoc parameters to package scripts

• [COMMANDBOX-1003] - Servers bound to 0.0.0.0 don't open useful browser URL

• [COMMANDBOX-1030] - unicode chars not read from readme files when publishing

• [COMMANDBOX-1040] - Native OS execution doesn't handle exit on fail for *nix

• [COMMANDBOX-1041] - Install path not respected when createPackageDirectory set to false

New Feature

• [COMMANDBOX-1002] - Add cached version of HTTP(S) endpoints

• [COMMANDBOX-1031] - Output binary objects in REPL

• [COMMANDBOX-1039] - Add support for "cd -"

Improvement

• [COMMANDBOX-993] - Announce onServerStop when stopping a --console server

• [COMMANDBOX-996] - Support path completion with "run" or "!" command

• [COMMANDBOX-997] - Expand log output of failed job steps

• [COMMANDBOX-1001] - Pass interceptData to package scripts

• [COMMANDBOX-1004] - Allow tab completion on quoted parameters

• [COMMANDBOX-1033] - Editor on Linux

• [COMMANDBOX-1042] - Return actual exit code of server process from server start

• [COMMANDBOX-1045] - Java install endpoint allows invalid slugs

• [COMMANDBOX-1046] - Pass CommandBox shell env vars to server starts

• [COMMANDBOX-1047] - Better detection of CF Engine when using HTTP provider

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.

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: https://commandbox.ortusbooks.com/config-settings/env-var-overrides

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.

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: https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/env-var-overrides

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: https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/server-port-and-host#http-2

JMES JSON filtering / jq Command

Thanks to a massive effort from Scott Steinbeck, the CFML world has a new CF implementation of the JMES spec, which is what powers the popular "jq" (or JSON Query) bash command. We've plugged this new library into CommandBox and exposed it in the following ways.

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.

# 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 much more than you realize! Make sure you check out the docs for more ideas.

More Info: https://commandbox.ortusbooks.com/usage/jq-command

AJP Secret Support

CommandBox's AJP listener (provided by Undertow) is already protected against the Ghostcat vulnerability. 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: https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/server-port-and-host#ajp-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.

// 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: https://commandbox.ortusbooks.com/task-runners/threading-async#asyncmanager

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:

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"

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.

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

More Info: https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/experimental-features

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.

server set web.SSL.forceSSLRedirect=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: https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/https-redirect-hsts

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:

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"

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.

server set web.host=mySite.localhost

More Info: https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/server-port-and-host#a-gracious-host

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.

commandbox_home=../customHome

More Info: https://commandbox.ortusbooks.com/setup/installation

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

box_server_web_http_port=0

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:

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

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:

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

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

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

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

COMMANDBOX-1276 Corrupted WireBox metadata cache file will prevent CommandBox from starting

COMMANDBOX-1275 HTTP2 Additional Port Handling and Flexibility

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

COMMANDBOX-1270 JVM arg ending in backslash doesn't work

COMMANDBOX-1268 Coldbox Watch-Reinit Watches Unwanted Folders

COMMANDBOX-1263 Package installation doesn't always optimize duplicate packages

COMMANDBOX-1261 Globber.count() bombs if run after .asQuery()

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

COMMANDBOX-1255 Loading class files in task runner doesn't work

COMMANDBOX-1253 variables scope doesn't persist between task dependencies

COMMANDBOX-1250 tokenreplace removes BOM from files

COMMANDBOX-1212 trayOptions.json not respecting serverHomeDirectory

COMMANDBOX-664 Server status not always correct.

Improvement

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

COMMANDBOX-1296 Improve error message if version isn't found in ForgeBox

COMMANDBOX-1295 Loosen parsing of build ID in semver

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

COMMANDBOX-1290 Remove runwar hack that sets java vesrion

COMMANDBOX-1288 Runwar timesout when Lucee's new warmup flag is used

COMMANDBOX-1287 Add option for PID file

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

COMMANDBOX-1284 Have parser ignore quotes inside a token

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

COMMANDBOX-1267 Add setters for run() arguments in CommandDSL

COMMANDBOX-1258 Default embedded server only needs to copy lucee.jar

COMMANDBOX-1256 Have outdated also show latest version of a package

COMMANDBOX-1252 Integrate AsyncManager into CommandBox

COMMANDBOX-1251 Upgrade to latest WireBox 6.x

COMMANDBOX-1249 Bundle testbox in testbox module to prevent auto download

COMMANDBOX-1248 Halt server start if asked for port is in use

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

COMMANDBOX-1216 Support AJP secret in Undertow

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

COMMANDBOX-1136 Can't link package if no modules are installed

COMMANDBOX-1117 New first-class setting to enable HTTP2

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

New Feature

COMMANDBOX-1294 Allow server rules to be commented out with #

COMMANDBOX-1293 Allow servers to use random.localhost domains

COMMANDBOX-1289 Integrate JMES JSON filtering

COMMANDBOX-1282 Debug when lucee-extensions don't find Lucee server

COMMANDBOX-1281 Allow JSON service to create implicit arrays

COMMANDBOX-1280 Add config setting to enable ANSI colors in dumb terminals

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

COMMANDBOX-1278 Add --json flag to server list

COMMANDBOX-1277 Add HTTP redirect options

COMMANDBOX-1273 Add optional servlet path cache in Runwar

COMMANDBOX-1262 Allow caching of task runners

COMMANDBOX-1260 Support for generating ColdBox RESTHandlers

COMMANDBOX-1245 Support default module export as @moduleName,

COMMANDBOX-676 Allow commandbox_home to be relative

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

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.

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

CommandBox Manual - Version 5.7.0

Welcome to the CommandBox Manual. CommandBox is a standalone, native tool for Windows, Mac, and Linux that will provide you with a Command Line Interface (CLI) for developer productivity, tool interaction, package management, embedded CFML server, application scaffolding, and sweet ASCII art. It seamlessly integrates to work with any of Ortus Solutions *Box products, but it is also open for extensibility for any ColdFusion (CFML) project as it is written in ColdFusion (CFML) using our concepts of CommandBox Commands.

Versioning

CommandBox is maintained under the Semantic Versioning guidelines as much as possible. Releases will be numbered with the following format:

<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

CommandBox is open source and bound to the LGPL v3 GNU LESSER GENERAL PUBLIC 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

The CommandBox help and discussion group can be found here: https://community.ortussolutions.com/c/communities/commandbox/

Reporting a Bug

We all make mistakes from time to time :) so why not let us know about it and help us out. We also love pull requests, so please star us and fork us: https://github.com/ortus-solutions/commandbox

• https://ortussolutions.atlassian.net/browse/COMMANDBOX

Professional Open Source

CommandBox is professional open source software backed by Ortus Solutions, Corp offering services like:

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

• Much More

Resources

• Official Site: http://www.ortussolutions.com/products/commandbox

• Source Code: https://github.com/ortus-solutions/commandbox

• Ortus Community Forum: https://community.ortussolutions.com/c/communities/commandbox/14

• Bug Tracker: https://ortussolutions.atlassian.net/browse/COMMANDBOX

• Twitter: @ortussolutions

• Facebook: https://www.facebook.com/ortussolutions

• Google+: https://google.com/+OrtusSolutions

• Vimeo Channel: http://vimeo.com/channels/commandbox

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

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

# Logout one user
forgebox logout username

# logout all users
forgebox logout

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

Read more here:

https://commandbox.ortusbooks.com/config-settings/misc-settings#tabcompleteinline

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.

|------------------------------
   | √ | Setting Server Profile to [development]
   |   |------------------------------------------------------
   |   | Profile set from "environment" env var
   |   | Block CF Admin disabled
   |   | Block Sensitive Paths enabled
   |   | Block Flash Remoting enabled
   |   | Directory Browsing enabled
   |   |------------------------------------------------------

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:

https://commandbox.ortusbooks.com/embedded-server/single-server-mode

Release Notes

Here are the release notes for the 5.2.1 release.

Bug

• [COMMANDBOX-1231] - Installing via lex endpoint uses incorrect file extension

• [COMMANDBOX-1232] - Location of predicate file is in a folder that the Docker finalization script deletes

• [COMMANDBOX-1238] - Command alas for run command doesn't expand properly

New Feature

• [COMMANDBOX-1237] - Add config setting to activate JLine's AUTO_MENU_LIST

• [COMMANDBOX-1240] - forgebox logout command

Improvement

• [COMMANDBOX-1227] - verbose server start output for profile and security settings

• [COMMANDBOX-1228] - Extend ${} scopes to apply to any getSetting() call or "env show" command

• [COMMANDBOX-1229] - Modules aren't unloaded on reload or shutdown

• [COMMANDBOX-1233] - Add debug output that shows location of commandbox.properties file on start

• [COMMANDBOX-1234] - Add single server mode for CommandBox in a Docker container

• [COMMANDBOX-1236] - Add Testbox runner to sensitive paths in production profile

• [COMMANDBOX-1241] - Use UTF-8 when reading files with "cat" command

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

• - Sept 2019

• - June 2019

• - Mar 2019

• - Dec 2018

• - Nov 2018

• - Oct 2018

• - Aug 2018

• - Jun 2018

• - Jun 2018

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

• - Nov 2017

• - Aug 2017

• - Jul 2017

• - Mar 2017

• - Jan 2017

• - Nov 2016

• - Oct 2016

• - Jul 2016

• - Jul 2016

• - Feb 2016

• - Feb 2016

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

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)

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

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

Which gives you this in your server.json

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!

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:

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.

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

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

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)

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

Bug

New Feature

Task

Improvement

Iterate over JSON with foreach command

The foreach command which was introduced recently and allows you to iterate over any list of input and run a command using each item in the list has been enhanced to also allow you to iterate from the CLI over any JSON string that you pipe in.

Directory Watchers have more data

Now when you create a directory watcher in a task runner or custom command, you can not only get notified when something in that directory changes, but you also now receive a list of files added, removed, and modified.

New "coldbox watch-reinit" command

Thanks to Scott Steinbeck, we have a new command called coldbox watch-reinit. This will watch for changes to certain files in your project and will automatically issue a framework reinit when you edit things like configs or services.

Color all the JSONs

Thanks to John Berquist, CommandBox now has sweet color coding any time it outputs JSON to the screen. Try it out by running something like "server show".

Users can also customize the colors they see for JSON with the following config settings:

• json.ansiColors.constant

• json.ansiColors.key

• json.ansiColors.number

• json.ansiColors.string

Setting values can be any color name from the system-colors command.

New Gist endpoint

Thanks to Jason Steinshouer we have a new Gist endpoint for installing code from a public Gist.

4.4.0 Release Notes

Bug

New Feature

Improvement

Release Highlights

• Fixed the annoying "server spanner" error that *nix users saw when starting servers.

• Updated CLI engine (and default server) version to Lucee 5.2.7.63 which includes an important security fix.

• Added a new "noninteractive" setting to improve the output on build servers like Jenkins or Travis-CI

• Task runner metadata changes picked up without needing to reload the CLI

• Ability to load ad-hoc modules on the fly from Task Runners

Release Notes

Here's the full list of tickets we addressed in the 4.1.0 release. Thanks to those who send me pull requests for some of these fixes and features!

Bug

• [] - server start on linux: "/bin/bash not found" message displays

• [] - Improve port binding logic

• [] - Task component metadata is not refreshed before each run

• [] - Error when invalid UTF-8 characters are in servers.json

New Feature