1 of 50

Release History

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

Versions 6.x - Feb 2024 -
Versions 5.x - Mar 2020 - August 2023
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

6.x Versions

What's New in 6.0.0

There are a lot of new features in CommandBox 6. Here's an overview of the biggest ones. Check out the release notes for the full list.

Multi-Site Servers

This one is huge. It's the hallmark feature of CommandBox 6 and allows you to easily run as many web sites (with different web roots) in a single CommandBox server. This finally gives you the same behavior you get with Adobe ColdFusion and IIS or Lucee/Tomcat and Apache with mod_cfml. CommandBox has had built-in ModCFML support for a while, but it still needed a web server in front to work fully. CommandBox Multi-Site gives you a fully powered web server that allows you to define as many separate web sites as you like, each with COMPLETE configuration control, all inside a single server process.

Rewrites
web aliases
security profile
HTTP/SSL/AJP bindings
SSL Certs
welcome files
MIME types
GZIP settings
Basically everything can currently configure under the "web" object of your server.json can be set on a per-site basis!

CommandBox is now truly a One-Stop-Shop for running your apps from development to production. You don't need Apache, Nginx, IIS, or Tomcat!

{
  "name": "commandbox-multi-site",
  "web": {
    "bindings": {
      "HTTP": {
        "listen": "80"
      }
    }
  },
  "sites": {
    "site1": {
      "hostAlias": "site1.com",
      "webroot": "site1"
    },
    "site2": {
      "hostAlias": "site2.com",
      "webroot": "site2"
    },
    "site3": {
      "hostAlias": "site3.com",
      "webroot": "site3"
    }
  }
}

Enhanced Server Bindings

Going hand-in-hand with our Multi-Site features, is the ability to bind to more than one HTTP port, more than one SSL port and more than one AJP port. You can configure proper host name matching on any binding, and even have multiple SSL certs. This new feature is available not only for Multi-Site but also for single site servers. The new server bindings come with a new JSON syntax in the server.json (we still support the old one too)

{
    "web" : {
        "bindings" : {
            "HTTP" : {
                "listen" : "10.10.0.123:8080",
                "host" : "site.com,site2.net"
            }
        }
    }
}

SSL SNI Support

Going hand-in-hand with our enhanced server bindings, is the ability not only to be able to specify multiple SSL certs per site, but also multiple SSL certs per SSL binding. CommandBox automatically enables SNI (Server Name Indication) which will choose the proper cert based on the incoming host name. With support for PEM files, DER formats, and PFX formats, this really opens up a lot of capabilities.

Rewrite Maps

We added a popular feature from Apache's mod_rewrite called rewrite maps. This allows you to create a simple text file of values you can reference in your rewrite rules to map incoming URL values to another value.

{
  "web" : {
    "rules":[
      "rewrite-map( name=myMap, file='/path/to/myMap.txt' case-sensitive=false )",
      "regex-nocase( '^/foo/(.*)$' ) -> rewrite( 'index.cfm?page=%{map:myMap:$[1]|99}' )"
    ]
  }
}

Publish command directly uploads to S3

This is a nice little productivity enhancement. When you run the publish command, the CLI will now directly upload your zip file to S3 instead of sending it to ForgeBox first. This improves the speed and efficiency of your deployments.

Add a proxy server rule alias

This is a simple one. If you want to create a simple reverse proxy to a single back-end server, we've created an alias for the existing load-balanced-proxy() handler called just proxy which accepts a single host with less verbosity.

proxy( 'http://localhost:8085' )

Specify Package and Server scripts as an array

You're already familiar with specifying package scripts and server scripts in your box.josn and server.json as a string containing one or more commands. Instead of using && for multiple commands, you can also do this by specifying an array of strings instead of a string like so:

{
  "name" : "My Package",
  "scripts" : {
      "build" : [
          "!grunt build",
          "testbox run",
          "run-script generateAPIDocs",
          "bump --patch && publish"
       ],
  }
}

This can be much more readable for multiple commands. Note, this is functionality equivalent to using &&, which means any erroring command will stop execution.

ColdBox, TestBox and ContentBox commands are now modules

CommandBox still bundles helpful scaffolding commands for your favorite MVC framework Testing framework, and CMS, but these commands are no longer part of the core CommandBox source code. We've given them new life as independent modules. They are installed by default, but they now have their own lifecycle and can get releases at any time. You can view and update them with the rest of your system modules.

list --system
update --system

Adobe CF Script Alias

CommandBox adds a /cf_scripts/scripts alias for you any time you start an Adobe CF server. This alias points to the same folders in the root of the Adobe WAR. If you set a custom scripts src path in the CF administrator then you'll want to ensure CommandBox uses the expected alias. There is now a setting called web.adobeScriptsAlias which allows you to control the public, web-accessible path to the scripts folder that CommandBox creates for you. And better yet, if you're using CFConfig, will automatically update the Adobe script source setting to match and vice versa.

CommandBox Pro Config settings auto-sync

As a perk of CommandBox pro, once you log into the CLI with your ForgeBox Pro account, your config settings will now automatically sync to and from ForgeBox. This is a great way to keep multiple CLI instances across computers up to date.

Release Notes

Here are the full release notes for CommandBox 6.0.0

Bug

COMMANDBOX-1590Some server.json config options unavailable as environment variables

COMMANDBOX-1598Runwar doesn't load servlet filter mappings correct in web.xml override

COMMANDBOX-1604 semantic version parsing ignores part of pre-release IDs with hyphen

COMMANDBOX-1608 Stackoverflow when using serverinfo system setting expansion in a server script

COMMANDBOX-1613 Lucee Light Engine

COMMANDBOX-1615 Installing package crashes when PackageService cannot delete tmp folder

New Feature

COMMANDBOX-1589 Add a `proxy` server rule alias to `load-balanced-proxy` which takes in one item instead of an array.

COMMANDBOX-1592 Add Rewrite Map feature similar to Apache

COMMANDBOX-1593 Multi-Site mode

COMMANDBOX-1611 CommandBox Pro users get config auto sync

Improvement

COMMANDBOX-1477 box install <package>: constrain to version already defined in box.json

COMMANDBOX-1572 Publish command directly upload to S3

COMMANDBOX-1591 Allow the scripts key under the server.json and box.json to use an array of scripts to run under the same script key name

COMMANDBOX-1594 XML formatting in print helper can kick in a bad time

COMMANDBOX-1595 Allow control over undertow' s transferMinSize

COMMANDBOX-1599Provide way to escape literal colon (:) command parameter name

COMMANDBOX-1600Remove contentbox, coldbox, etc modules from the core

COMMANDBOX-1603Customize Adobe cf scripts alias

Task

COMMANDBOX-1609Update bundled JRE to 11.0.22+7

COMMANDBOX-1610Update to Lucee 5.4.4.38

5.x Versions

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

Version 5.9.1 - August 2023
Version 5.9.0 - May 2023
Version 5.8.0 - April 2023
Version 5.7.0 - December 2022
Version 5.6.0 - September 2022
Version 5.5.2 - May 2022
Version 5.5.1 - May 2022
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

What's New in 5.9.0

Java 17 Support

Java 17 was a breaking change for Java users as it now blocks illegal reflective access. Both Adobe and Lucee have been slow to address this. Lucee 5.3.10 mostly seems to run on Java 17, but only the public beta of ColdFusion 2023 (Fortuna) supports Java 17. You may want to start testing Java 17 out, so the CommandBox CLI and its servers seem to have basic support for running on Java 17 now. Note, you may need to add additional JVM args to any servers based on the specific Java libraries you use.

Library Updates

We've bumped library versions such as Redhat Undertow to stay current with recent CVE fixes.

Override package install paths

If you have a project and want all packages of a certain type to use a different-than-normal default install location, you can override each package type just for that project. Create an installPathConventions key in the containing package's box.json which is an object containing keys for each package type you wish to override package install paths for.

{
  "installPathConventions" : {
    "modules" : "../lib/modules",
    "mvc" : "../lib/framework",
    "testing" : "they-will-never-find-it-here-lol/"
  }
}

ls --tree

You can get recursive file listings now in a tree view by using the --tree flag

ls --tree

Tree Print Helper

In task runners and custom commands, you can now tap into the same tree printer that the "package list" and "ls --tree" use to output your own ASCII trees.

print.tree(  [
	'Ortus Solutions' : [
		'Products' : [
			'Open Source' : {
				'ColdBox MVC' : {},
				'CommandBox CLI' : {},
				'ContentBox CMS' : {}
			},
			'Commercial' : {
				'ForgeBox Pro' : {},
				'CommandBox Pro' : {},
				'TimeBox BMP' : {}
			}
		],
		'Services' : {
			'Consulting' : {},
			'Training' : {},
			'Design' : {}
		}
	]
] )

which outputs

└─┬ Ortus Solutions
  ├─┬ Products
  │ ├─┬ Open Source
  │ │ ├── CommandBox CLI
  │ │ ├── ContentBox CMS
  │ │ └── ColdBox MVC
  │ └─┬ Commercial
  │   ├── ForgeBox Pro
  │   ├── TimeBox BMP
  │   └── CommandBox Pro
  └─┬ Services
    ├── Training
    ├── Design
    └── Consulting

Column Print Helper

There is also a print helper method for task runners and custom commands as well as a CLI command you can use that accepts an array or list of simple values and prints them in a column format based on the widest value and the available terminal width.

ls --simple | printColumns

unansi Command

This command will accepted piped text and strip any ANSI formatting from it. Especially useful if piping the text to a native OS binary which doesn't handle formatting well.

package list | unansi

clipboard Command

We've introduced a new command for piping text onto your native operating system's clipboard.

echo "Hello World!" | clipboard
Copied to clipboard!

Release Notes

Here's the full list of all the changes in CommandBox 5.9.0.

What's New in 5.7.0

Check Out The New Stuff

The notable updates include:

Updated version of JBoss Undertow, which contains security fixes
Updated version of Lucee to 5.3.10 which also contains library security updates
New "artifacts prune" command to remove older artifacts that haven't been used recently
Improved "upgrade" command which can also update new jars (you'll be able to use this in the NEXT update!)
Support for PFX cert file for server SSL

And here are the full release notes:

New Feature

COMMANDBOX-1535 update coldbox resources to support api resources

COMMANDBOX-1536 artifacts prune command

Bug

COMMANDBOX-1507 Use user.home instead of user.dir to test case sensitivity

COMMANDBOX-1510 Cursor position get's off-track when using a multiselect with content that exceeds the terminal size

COMMANDBOX-1511 ModCFML doesn't save actual Lucee webConfigDir

COMMANDBOX-1513 Runwar server's regex path info filter doesn't take servlet context into account

COMMANDBOX-1517 Two servers get same name when moving folder

COMMANDBOX-1518 Can't pass Windows drive letter to "open" command

COMMANDBOX-1519 Error passing empty version to "java search" command

COMMANDBOX-1524 Interactive job logs don't obey terminal width config setting

COMMANDBOX-1525 REPL errors when representing some Java objects

COMMANDBOX-1527 recipe file validation fails

COMMANDBOX-1528 Java integration doesn't recognize ARM CPUs

COMMANDBOX-1533 coldbox resources command failing on relative models directory not found

Improvement

COMMANDBOX-1378 make "upgrade" command handle new jars

COMMANDBOX-1499 Support pfx format for server certs

COMMANDBOX-1512 Have fileAppend (>>) and fileWrite (>) commands create missing parent directories

COMMANDBOX-1514 REPL obey verboseErrors config setting

COMMANDBOX-1516 cfpm doesn't find Adobe server with different web root

COMMANDBOX-1520 Make client cert CGI vars available immediately after SSL renegotiation

COMMANDBOX-1521 Add --json to artifacts list

COMMANDBOX-1523 Touch artifacts on use so we can prune unused ones easier

COMMANDBOX-1534 Update coldbox resources command to latest version

Task

COMMANDBOX-1526 Update bundled JRE to 11.0.17+8

COMMANDBOX-1529 Update Undertow lib in Runwar

COMMANDBOX-1530 Update json-smart-mini and Lucee libs

What's New in 5.6.0

Library Updates

We know this stuff may seem boring, but it's super important to ensure you stay safe and secure on the latest versions of our bundled libraries. We updated the following libs in this release:

org.lucee:lucee 5.3.9.141 -> 5.3.9.160
io.undertow:undertow-servlet 2.2.17.Final -> 2.2.19.Final
io.undertow:undertow-websockets-jsr 2.2.17.Final -> 2.2.19.Final
net.minidev:json-smart-mini 1.0.8 -> 1.3.2
commons-cli:commons-cli 1.2 -> 1.5.0
org.jooq:joox 1.2.0 -> 1.6.2
org.apache.logging.log4j:log4j-slf4j-impl 2.17.1 -> 2.18.0
org.apache.logging.log4j:log4j-core 2.17.1 -> 2.18.0
org.jboss.logging:jboss-logging 3.4.1.Final -> 3.4.3.Final

Lots of Bug Fixes

Over half of the tickets in this release were bug fixes to keep the CLI running smoothly on all operating systems. You can check out the full list of ticket below to see the screws we tightened.

New Server Security System

CommandBox servers have an exciting new weapon in their arsenal, and that is a new system of security that allows you to protect certain parts of your site from the general public. This could be CF admins, private dashboards, or a subfolder of sensitive files.

You'll find a new section in the server.json called web.security where these settings live. You can leverage the power of our Server Rule predicates to match whatever requests you want to secure, based on folder, HTTP method, remote IP, HTTP headers and more.

{
  "web" : {
    "security" : {
      "realm" : "My Realm",
      "authPredicate" : "path-prefix( /lucee/admin/ ) and not equals('%{REMOTE_IP}', 127.0.0.1)"
    }
  }
}

That authPredicate would require authorization for any pages in the Lucee admin unless you were on localhost. NOTE: path-prefix is case sensitive, so on Windows you'd want to use a regex() based check such as regex( pattern='^/lucee/admin/.*', case-sensitive=false )

When a request is marked as requiring authentication, you can enable one or more auth mechanisms to challenge the user as discussed below.

Basic Auth Security

CommandBox has supported basic auth for a while, but it was a simple all-or-nothing implementation. Basic auth has been revamped and rolled into the new security system. If no authPredicate is defined, it will still apply to the whole site. But when an authPredicate is declared in your server.json, it will only kick in for those pages.

We've also moved the basic auth settings in server.json to here:

{
    "web":{
        "security" : {
            "realm" : "My Realm",
            "authPredicate" : "regex( pattern='^/lucee/admin/.*', case-sensitive=false )"
            "basicAuth":{
                "users":{
                    "brad":"pass",
                    "luis":"pass2"
                },
                "enable":"true"
            }
        }
    }
}

Don't worry, the old location still works too for now. We won't remove support for it until the next major release of CommandBox. If both the settings exist (Ex: web.basicAuth.enable and web.security.basicAuth.enable), the new location will be given precedence.

Client Cert Security

Adding support for client SSL certs was one of our largest undertakings and is a very exciting new feature for government shops who use PKI based authentication, often times in the form of DoD CAC (cards) which are physical cards containing a private PKI cert that identifies the user. This feature was one of the last reasons to need IIS or Apache in your mix, but now CommandBox can do it all!

Client certs have two part-- first is the ability of the web server to prompt the user's browser to ask for a client cert to send. This requires configuring a trust store or a list of trusted CA certs to accept. When the user sends a cert, it automatically makes a number of CGI and request variables available to your CF code. You can configure your SSL connection to accept or require client certs like so:

{
  "web" : {
    "ssl" : {
      "enable" : true,
      "clientCert" : {
	"mode" : "Requested",
	"CACertFiles" : "rootCA.cer,anotherRootCA.cer",
	// OR...
	"CACertFiles" : [
          "rootCA.cer",
          "anotherRootCA.cer"
	],
        // OR...
	"CATrustStoreFile' : "cacerts",
	"CATrustStorePass' : "changeit"
      }
    }
  }
}

Some of the CGI variables which are automatically created when a client cert is present are

CGI.SSL_CLIENT_CERT - PEM-encoded cert (base 64 string)
CGI.CERT_SUBJECT - The Subject distinguished name of the client cert (CN=foo, O=bar, OU=baz)
CGI.CERT_SERIALNUMBER - The serial number of the cert in the format 91-7e-5f-a5-b2-20-a1-8b-4c-d0-40-3b-1c-a1-a8-58
CGI.CERT_ISSUER - The Issuer distinguished name of the client cert (CN=foo, O=bar, OU=baz)
CGI.SSL_CLIENT_VERIFY - Matches Apache HTTP. Values will be "SUCCESS" or "NONE"

The second part of client certs is the ability to use that client cert information as an authentication mechanism to enforce your authPredicate automatically. (When CommandBox's security system is unable to authorize a user, it stops the request before it ever even reaches CF!)

When authorizing based on client certs, you can have 4 levels of checks:

Any user with a cert is allowed. (Remember, the client cert must always be trusted by one of your configured trusted CA certs)
Subject Distinguished Name (DN) matches one or more complete or partial DNs you specify
Issuer Distinguished Name (DN) matches one or more complete or partial DNs you specify
Or disable the web.security.clientCert.enabled setting and allow all requests to reach CF where you can write your own checks.

CommandBox also supports SSL Renegotiation which allows you to not force the client cert right away until the user gets to a page on the site that kicks in the authPredicate and then their browser will prompt them then. This is a popular configuration since the user can hit your login page first and then be prompted for their cert once they login.

The configuration for all this looks like this:

{
  "web" : {
    "security" : {
      "realm" : "My Realm",
      "authPredicate" : "path-prefix( /admin )"
      "clientCert" : {
        "enable" : true,
        "SSLRenegotiationEnable":true,
        "subjectDNs" : "O=Ortus, OU=Marketing",
        "issuerDNs" : [
          "O=Verisign",
          "CN=Bob, O=Walmart",
          "CN=GeoTrust TLS RSA CA G1, O=DigiCert Inc, OU=www.digicert.com"
        ]
      }
    }
  }
}

Read more on Client Cert Auth security Here.

https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/security/client-cert-authentication

Task Runner `loadModules()`

As Task Runners become more popular and people combine them with more modules to perform their operations, you run into the need to load a list of modules all at the same time which may have interdependencies. There is now a new loadModules() method available to Task Runners which accepts an array of module paths. Each module is first registered, and then each module is activated.

loadModules(
    directoryList( path=resolvePath( 'modules/' ), type='dir' )
);

Release notes

What's New in 5.5.2

Release notes

Bug

COMMANDBOX-1475 Server shutdowns aren't always done cleanly

COMMANDBOX-1474 Don't prompt on already-running server when terminal isn't interactive

COMMANDBOX-1472 Globber copyTo() command mishandles *nix leading slash

COMMANDBOX-1470 preServerStart can no longer affect server.json env var replacements

COMMANDBOX-1467 Servers can no longer override rest mappings

COMMANDBOX-1465 Corruption in interactive job output

COMMANDBOX-1464 Can't set XNIO socket settings or Sequence types

COMMANDBOX-1463 Command chaining has a code path where "job" variable is not defined

COMMANDBOX-1462 cfpm breaks in single server mode

Improvement

COMMANDBOX-1473 Allow Undertow's resource manager file system watcher to be disabled

COMMANDBOX-1468 Customize Undertow's enabled SSL protocols

Task

COMMANDBOX-1476 Update to Lucee 5.3.9.141 stable

What's New in 5.5.1

ModCFML Support

ModCFML is a popular standard for running a CF server behind IIS or Apache web server and allowing your virtual hosts configured in the web servers to control the web root of the CF server so you can run more than one site on a single CF instance. CommandBox has historically only had a single web root per server, but now you can use a single CommandBox instance to power as many Adobe CF or Lucee Server sites as you like. CommandBox's ModCFML just needs to be enabled and can work with BonCode, mod_cfml or Nginx.

server.json

{
   "ModCFML":{
        "enable":"true",
        "sharedKey":"my-secret"
    }
}

Log4j 1.x is gone!

CommandBox's core is now 100% free of 1.x versions of the Log4j library. Note, if you start an older Lucee server or any Adobe ColdFusion server, they may still have Log4j 1.x bundled with them.

Library updates

Many of the java libraries have been updated

JRE-bundled version ships with Java 11.0.15+10
Undertow updated to 2.2.17.Final
Lucee updated to 5.3.9.133
JGit updated to 5.13.0.202109080827-r
JLine updated to 3.21.0
Runwar updated to 4.7.4
Log4j updated to 2.17.1

Set Java System Props directly in server.json

Does what it says. Looks like this:

server.json

{
  "jvm" : {
    "properties" : {
       "foo" : "bar baz"
       "java.awt.headless" : "true"
    }
}

JVM Args can be an array

JVM args and Runwar args can now be set an array of strings which prevents you from needing to escape or quote anything.

Old way (still works)

{
  "jvm" : {
    "args" : "-XX:+UseG1GC -XX:-CreateMinidumpOnCrash --add-opens=java.base/java.net=ALL-UNNAMED"
  }
}

New way

{
  "jvm" : {
    "args" : [
       "-XX:+UseG1GC",
       "-XX:-CreateMinidumpOnCrash",
       "--add-opens=java.base/java.net=ALL-UNNAMED"
    ]
  }
}

Request Dumper

There is now a handy little handler you can put in your server rules to view a console dump of all the header data related to your request and response.

server.json

{
  "web" : {
    "rules" : [
      "regex('(.*).cfm') -> dump-request()"
    ]
  }
}

OpenJDK Downloads

The java API has been moved from AdoptOpenJDK to the Eclipse Adoptium project. This is basically the same project, it just changed names.

assertFalse command

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

assertFalse false && echo "The inputs was false"

assertNotEqual command

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

assertNotEqual "foo" "bar" && echo "The inputs are not equal"

Better command chaining

You can have more than two chained commands, and the command chain will keep executing so long as the next part is compatible with the previous exit code. Ex:

assertTrue false && echo "it was true!" || echo "back on track";

cfpm improvements

We now set the JAVA_HOME for the cfpm command if it doesn't exist
An Adobe server no longer needs to be the default server for that web root
If cfpm is run as part of a package or server script, it will default to the using the server currently doing something

box.exe finds Java better on Windows

Previous versions of Launch4j only used the Windows registry to find the installed version of java. The following environment variables are now also checked in this order to attempt to find a JRE to use.

JAVA_HOME
JRE_HOME
JDK_HOME
PATH

head Command

Does the same basic thing as the tail command, but it reads from the top of the file or input.

cat file.txt | head lines=10

X-Forwarded-For support disabled by default

For better security, CommandBox servers will not automatically obey X-Forwarded-For HTTP headers unless you enable it.

server set web.useProxyForwardedIP=true

Only enable this setting if your CommandBox server is behind a trusted proxy which always sets this header. Otherwise, a malicious client could spoof a trusted IP an bypass IP access control.

Relaxed semantic version parsing

Both of these commands will now do the same thing. The second one used to error with version not found.

# technical correct
server start cfengine=lucee@5.3.9+133

# technical incorrect, but people still always tried it
server start cfengine=lucee@5.3.9.133

XML Love

XML formatting is now a first-class citizen of the print helper and the REPL. You can pass a parsed XML doc and they will be formatted upon display.

❯ repl  'xmlParse(\'<root><user name="brad"/></root>\')'
<root>
  <user name="brad"/>
</root>

Mac Tray Icon Disabled

Due to lack of Java 9+ support in the Java library that creates tray icons, we've disabled the tray icon by default on MacOS. If you want to brave the possibility of it not working or spilling errors in the console, you can re-enable it like so:

# for one server
server set trayEnable=true

# for all servers
config set server.defaults.trayEnable=true

Hopefully when the library gets updated, we'll be able to re-enable the tray icon by default.

Release Notes

Here is the complete list of all tickets closed in this release

What's New in 5.4.2

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

What's New in 5.4.0

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

What's New in 5.3.1

Updated bundled Java libraries

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

Recursive jar scanning libDirs

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

# 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

What's New in 5.3.0

Override Config Settings via Env Vars

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

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

What's New in 5.2.1

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

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

What's New in 5.2.0

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

Library Updates

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

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

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

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

Server Security Profiles

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

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

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

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

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

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

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

server set profile=production

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

server start profile=production

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

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

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

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

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

‌Read more about Server Profiles here:

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

What's New in 5.1.1

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

What's New in 5.0.0

Upgrade Compatibility

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

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

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

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

What's New?

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

New Libraries

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

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

New Features/Enhancements

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

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

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

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

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

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

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

server set web.maxRequests=200

Which gives you this in your server.json

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

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

server set runwar.undertowOptions.ALLOW_UNESCAPED_CHARACTERS_IN_URL=true

server set runwar.XNIOOptions.WORKER_NAME=myWorker

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

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

// Later directly from bash...

./startmebaby.sh

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

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

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

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

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

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

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

dir **.cfc | grep --count

dir | grep .*\.md --count

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

Release Notes

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

Sub-task

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

Bug

[COMMANDBOX-643] - Tray Icon not displaying on Debian8
[COMMANDBOX-711] - X Window Errors
[COMMANDBOX-812] - "Coldbox create resource" uses wrong paths on Windows
[COMMANDBOX-941] - urlrewrite.xml has file size of 0 on docker restart but not regular start
[COMMANDBOX-946] - CommandBox instances crashing because of TrayIcon rendering
[COMMANDBOX-975] - CommandBox always reads STDIN even when in non-interactive mode
[COMMANDBOX-980] - Using zsh exits out of CommandBox when running a binary command
[COMMANDBOX-992] - Shebang scripts no longer work without .cfm extension
[COMMANDBOX-1005] - If custom rewrite file is already in correct destination, runwar overwrites it as 0 bytes
[COMMANDBOX-1008] - worker-threads setting no longer has any affect
[COMMANDBOX-1009] - Tray icon not showing in Ubuntu 18.04
[COMMANDBOX-1013] - Undertow error output when starting server
[COMMANDBOX-1014] - [RUNWAR] Tray menu placeholders such as ${Setting: runwar.port not found} are not replaced in sub menus
[COMMANDBOX-1022] - regex string index out of bounds exception
[COMMANDBOX-1035] - URL Rewrites fire incorrect on URL containing a space
[COMMANDBOX-1036] - Browser doesn't open when server start
[COMMANDBOX-1037] - Host updater does not work
[COMMANDBOX-1038] - Server doesn't stop on Windows
[COMMANDBOX-1043] - ConcurrentModificationException with undertow?
[COMMANDBOX-1048] - Restrict /dumprunwarrequest to be used only on Unit Testing
[COMMANDBOX-1050] - Remove trailing slash from Adobe updates path
[COMMANDBOX-1054] - Default command parameters don't work on commands in namespaces
[COMMANDBOX-1061] - Command DSL has unexpected behavior with equals sign in positional tokens
[COMMANDBOX-1062] - Tab complete for negated flags isn't complete
[COMMANDBOX-1063] - box fails to open in vSphere Web Client console due to outdated JLine jar
[COMMANDBOX-1068] - Server start doesn't correctly expand relative Java Home directory
[COMMANDBOX-1070] - slashes into the servlet init param paths
[COMMANDBOX-1071] - Tray icon doesn't disappear on Windows when server stops from CLI
[COMMANDBOX-1076] - Install dependency from box.json with env var placeholder gets overwritten with actual value
[COMMANDBOX-1077] - coldbox create resource command ignores specsDirectory argument
[COMMANDBOX-1079] - foreach cannot be interrupted with Ctrl-C
[COMMANDBOX-1081] - validate non-numeric exit codes from the "exit" command
[COMMANDBOX-1089] - Task Runner's loadModule() fails on path with period
[COMMANDBOX-1090] - Tasks don't treat return 1 and setExitCode( 1 ) the same
[COMMANDBOX-1091] - When a task sets a failing exit code, no output is sent to console
[COMMANDBOX-1092] - Commands that set a failing exit code don't raise proper exception
[COMMANDBOX-1098] - foreach, grep, and sed only break on chr(10)

New Feature

[COMMANDBOX-148] - Ability to install/uninstall box server services
[COMMANDBOX-715] - Server command to explode server war but not start it
[COMMANDBOX-1007] - Set any valid XNIO option
[COMMANDBOX-1018] - Add generic feature to set any valid Undertow option
[COMMANDBOX-1028] - Allow no rest mappings to be supplied
[COMMANDBOX-1032] - Tab completion for task targets
[COMMANDBOX-1052] - New TestBox commands: generate visualizer and generate browser
[COMMANDBOX-1053] - Update ColdBox module templates for 5.0 standards
[COMMANDBOX-1067] - Expose Undertow worker-threads setting with first-class server.json property
[COMMANDBOX-1075] - Support HTTPS username/password auth
[COMMANDBOX-1083] - Option for server start to write file with full start args for direct Runwar call
[COMMANDBOX-1088] - Add lex endpoint for installing Lucee extensions
[COMMANDBOX-1096] - Add unique command to filter out duplicates rows of input
[COMMANDBOX-1097] - Add sort command to sort rows of input

Task

[COMMANDBOX-964] - Make sure the build works
[COMMANDBOX-965] - Document Setup in the Repo
[COMMANDBOX-995] - Vet all changes on Runwar since April 25, 2018.

Improvement

[COMMANDBOX-885] - Enhance Globber to take more than one pattern
[COMMANDBOX-886] - Enhance Globber to have exclude patterns
[COMMANDBOX-963] - Update CLI to Lucee 5.3 and test Java 11
[COMMANDBOX-1029] - Change CommandBox build to pull Ortus build of Runwar
[COMMANDBOX-1049] - Output Runwar version and jar path in "info" command output
[COMMANDBOX-1055] - Need Config for Max Thread Request at runwar
[COMMANDBOX-1057] - Enhance dir command with new Globber features
[COMMANDBOX-1058] - Optimize installation of packages with createPackageDirectory set to false
[COMMANDBOX-1059] - Improve performance of print buffer by using String Builder internally
[COMMANDBOX-1060] - Add --count flag to grep command
[COMMANDBOX-1065] - Update CommandBox to Runwar 4.0.0
[COMMANDBOX-1066] - Upgrade to JGit 5.5
[COMMANDBOX-1074] - Tie into FusionReactor to report transactions for tasks, commands, etc.
[COMMANDBOX-1086] - Default location to forgeboxStorage for package init command
[COMMANDBOX-1087] - Improve default package naming of jar endpoint
[COMMANDBOX-1093] - Add option to tray menu to open server home directory
[COMMANDBOX-1095] - Update to latest WireBox
[COMMANDBOX-1099] - Stop outputting extra line break for commands with no output

4.x Versions

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

Version 4.8.0 - Sept 2019
Version 4.7.0 - June 2019
Version 4.6.0 - Mar 2019
Version 4.5.0 - Dec 2018
Version 4.4.0 - Nov 2018
Version 4.3.0 - Oct 2018
Version 4.2.0 - Aug 2018
Version 4.1.0 - Jun 2018
Version 4.0.0 - Jun 2018

What's new in 4.8.0

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

What's New in 4.7.0

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

What's New in 4.6.0

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

What's New in 4.5.0

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

What's New in 4.4.0

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.

package show dependencies | foreach

https://commandbox.ortusbooks.com/usage/foreach-command#iterating-over-json

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.

watch()
    .onChange( function( paths ) {
        print
            .line( '#paths.added.len()# paths were added!' )
            .line( '#paths.removed.len()# paths were removed!' )
            .line( '#paths.changed.len()# paths were changed!' )            ;
    } )
    .start();

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.

package set reinitWatchPaths= "config/**.cfc,models/**.cfc,ModuleConfig.cfc"
coldbox watch-reinit

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.

install gist:b6cfe92a08c742bab78dd15fc2c1b2bb

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

4.4.0 Release Notes

Bug

[COMMANDBOX-876] - testbox watcher shows error when test fail
[COMMANDBOX-881] - Tab complete doesn't work on param values with spaces
[COMMANDBOX-882] - Long lines wrap in interactive jobs
[COMMANDBOX-887] - Exact versions don't update from ForgeBox when manually changed.
[COMMANDBOX-895] - Passing positional args to task errors with required param

New Feature

[COMMANDBOX-877] - Allow watcher access to files that were added, removed, updated
[COMMANDBOX-878] - coldbox watch-reinit command
[COMMANDBOX-879] - Color code JSON on console output by default

Improvement

[COMMANDBOX-698] - Refresh any salt values when deploying a new CF engine.
[COMMANDBOX-732] - Add Gist endpoint
[COMMANDBOX-880] - Change update behavior of GIT and URL endpoints to use semver in path if present
[COMMANDBOX-883] - Enhance foreach command to accept JSON
[COMMANDBOX-884] - ACF 11 should start without Secure Profile
[COMMANDBOX-890] - Enhance "forgebox search" command to break up versions like "forgebox show"
[COMMANDBOX-891] - Support versions like 0.5.2 in forgebox show/search output
[COMMANDBOX-892] - Speed up embedded server start

What's New in 4.3.0

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.

What's New in 4.2.0

Random Fixes

In no particular order...

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

Random New Features

Sorted by createUUID() DESC...

Custom commands have more control over their tab completion candidates.
Control how many levels deep package list displays
New versions of Lucee, JGit, JLine, and WireBox
More pack200 of the Lucee jar (and more improvements to come soon in the next version of Lucee)
Automatic detection for build servers like Travis-CI to hide progress bar animations.
Cloning Git repos during install has a nice new progress bar that plays well with
You can use the aforementioned progress bar for your own purposes in custom commands and Task Runners.

Improvements to Native Binaries

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

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

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

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

Better Exit Code handling

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

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

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

Command Chaining

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

&&

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

||

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

;

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

New Assertion Commands

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

pathExists

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

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

assertTrue

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

assertEqual

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

New S3 Endpoint for Installing Packages

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

There are several different authentications mechanisms available too:

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

The full docs are here:

Updated Server Tray Menus

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

Release Notes

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

Bug

New Feature

Improvement

What's New in 4.1.0

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

[COMMANDBOX-791] - server start on linux: "/bin/bash not found" message displays
[COMMANDBOX-799] - Improve port binding logic
[COMMANDBOX-802] - Task component metadata is not refreshed before each run
[COMMANDBOX-806] - Error when invalid UTF-8 characters are in servers.json

New Feature

[COMMANDBOX-669] - Localized CommandBox Modules
[COMMANDBOX-793] - Add new slugify function to the formatter utility
[COMMANDBOX-794] - When creating coldbox skeleton apps, clear out the basic name, slug, version, location and scripts so the user can configure them
[COMMANDBOX-797] - Added new bundles,labels,verbose,directory arguments to the testbox watch command to allow for granular executions
[COMMANDBOX-798] - Added verbose options to passthrough to the testbox runner so it true it can return the debug buffer

Improvement

[COMMANDBOX-792] - Remove legacy installColdbox, installColdboxBE, installTestbox arguments from create commands
[COMMANDBOX-796] - Added ability to visualize the exception stacktraces with a configurable depth.
[COMMANDBOX-800] - Add setting to force "non interactive" shell that disables fancypants progress output
[COMMANDBOX-803] - Change user agent on downloader to get around proxies like cloudflare
[COMMANDBOX-804] - Store less "result" text in CommandBox's servers.json
[COMMANDBOX-807] - Upgrade core Lucee engine to 5.2.7.63

What's New in 4.0.0

Major Areas of Development

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

Featured Enhancements

256 Color support

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

3.x Versions

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

Version 3.9.0 - Nov 2017
Version 3.8.0 - Aug 2017
Version 3.7.0 - Jul 2017
Version 3.6.0 - Mar 2017
Version 3.5.0 - Jan 2017
Version 3.4.0 - Nov 2016
Version 3.3.0 - Oct 2016
Version 3.2.0 - Jul 2016
Version 3.1.1 - Jul 2016
Version 3.0.1 - Feb 2016
Version 3.0.0 - Feb 2016

What's New in 3.9.0

UNC Network path support

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

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

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

Task Runner Improvements

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

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

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

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

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

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

CommandBox> package link

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

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

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

Everything Else (mostly)

The rest of the changes don't really need a dedicated section but they're worth mentioning, so I've put them in this tidy list :) If you'd like the ticket numbers, you can get them out of this full list of tickets in JIRA: https://ortussolutions.atlassian.net/secure/ReleaseNote.jspa?projectId=11000&version=20400

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

Bug

[COMMANDBOX-579] - --debug flag is eaten when running CommandBox from native OS
[COMMANDBOX-640] - Ensure clean install/update of packages
[COMMANDBOX-681] - Touching file in nonexistent directory errors instead of creating directory
[COMMANDBOX-682] - CommandDSL that errors out doesn't reset CWD
[COMMANDBOX-684] - positional task args don't work
[COMMANDBOX-686] - cp command doesn't work for folders
[COMMANDBOX-689] - CommandBox Modules customInterceptionPoints can't accept an array
[COMMANDBOX-690] - CommandBox has no `processState` method on the InterceptorService
[COMMANDBOX-691] - Flags aren't passed correctly to task runners
[COMMANDBOX-701] - CFML functions don't handle incoming JSON with pound signs

New Feature

[COMMANDBOX-653] - Expose Runwar AJP listener settings
[COMMANDBOX-663] - Update server list and server info to be able to show all the servers on a particular directory
[COMMANDBOX-668] - New package link and package unlink commands
[COMMANDBOX-680] - Add ad-hoc JVM props via an environment variable

Improvement

[COMMANDBOX-178] - Don't store text entered to "ask()" command in history
[COMMANDBOX-565] - Handle minor version updating a bit better
[COMMANDBOX-607] - Always store dependency install paths with forward slashes
[COMMANDBOX-609] - Have a setting to not show secrets when printing out the config
[COMMANDBOX-624] - Support UNC file paths on Windows
[COMMANDBOX-639] - JSON format for forgebox endpoints
[COMMANDBOX-659] - Ask user for required params to task runners
[COMMANDBOX-660] - Visually show if a package is private when listing or showing
[COMMANDBOX-661] - make package init create correct slug for private package
[COMMANDBOX-662] - Make default command parms work on aliases
[COMMANDBOX-670] - Box install failures to produce non-zero exit codes so build fails instead of continuing installation.
[COMMANDBOX-683] - Provide ANSI formatting for markdown package descriptions
[COMMANDBOX-685] - box.json template isn't proper JSON
[COMMANDBOX-687] - Remove background color from CommandBox ASCII art
[COMMANDBOX-688] - Default rewrite rules to ignore favicon.ico
[COMMANDBOX-694] - Disable Secure Profile on CFEngine WARs
[COMMANDBOX-696] - Leave space around URLs so some consoles will be clickable
[COMMANDBOX-697] - Improve performance of package install ignores
[COMMANDBOX-700] - Improve error message in ServerService.getRandomPort()
[COMMANDBOX-707] - Prevent unnecessary writes to box.json file when installing dependencies
[COMMANDBOX-708] - Improve formatting when asking for required param that has no hint
[COMMANDBOX-712] - Add Java 9 check to CommandBox until its supported

What's New in 3.8.0

Bug

[COMMANDBOX-665] - Relative SSL certFile or keyFile path in server.json isn't expanded
[COMMANDBOX-674] - propertyfile set errors if file doesn't exist

New Feature

[COMMANDBOX-675] - Allow relative property file paths in task runners

Improvement

[COMMANDBOX-666] - Allow custom tray contributions to have relative image path
[COMMANDBOX-667] - Improve coldbox create app --wizard
[COMMANDBOX-671] - Always run onServerInstall
[COMMANDBOX-672] - add getInstance() to base interceptor class
[COMMANDBOX-673] - Improve handling of loading a bad modules
[COMMANDBOX-678] - Command to normalize line endings for a batch of files
[COMMANDBOX-679] - Improve package parsing regex for private packages

What's New in 3.7.0

What's New

Task Runners - Run ad-hoc builds from the CLI written in CFML (Read more)
Manage System Packages - update, list, and uninstall system modules (Read more)
File Globbing - Use place holders like **.cfc for file operations to affect more than one file at a time. (Read more)
Command Aliases - Alias your favorite commands for easy access in the future (Read more)
Global Command Parameter Defaults - Set common parameters to have a given value at a global level (Read more)
System Settings - Utilize environment variables to make your package and servers more dynamic (Read more)
Testbox Run - Improved, minimalist output to the "testbox run" command (Read more)
TestBox Watchers - Watch a directory for file changes and run your unit tests (Read more)
Customize REST Servlets - Customize or disable the REST servlet paths on Lucee and Adobe servers (Read more)
Custom Java Versions - Start your CF servers with any version of Java you want (Read more)
Property files - New commands and helper libs for dealing with property files (Read more)
Basic Authentication - Enable basic security on your servers with unlimited users (Read more)
Custom URL to Open - Customize the browser URL that opens when you start a server (Read more)
Disable Tray Icon - Turn off the system tray icon for your servers entirely (Read more)
Show Proxy IP - Servers pass through the original user IP through proxies
Jar Endpoint - Install 3rd party jars into your projects (Read more)

Release Notes

Bug

[COMMANDBOX-176] - Server start tries to open HTTP URL even if it's disabled
[COMMANDBOX-474] - testbox run with runner urls that have a query string fail
[COMMANDBOX-525] - cf_scripts folder not working on Adobe 2016
[COMMANDBOX-600] - Catastrophic runner errors in testbox run don't fail tests
[COMMANDBOX-611] - errors if you start second CLI while first one is using the temp dir
[COMMANDBOX-616] - TestBox scaffolds are missing super calls for beforeAll/afterAll
[COMMANDBOX-621] - Prevent two servers from getting the same name
[COMMANDBOX-625] - Basic auth doesn't set cgi.remote_user
[COMMANDBOX-651] - unregister method in interceptor service doesn't work

New Feature

[COMMANDBOX-15] - Allow file globbing patterns in file/folder operations
[COMMANDBOX-50] - Create BaseTask
[COMMANDBOX-51] - Add "task" command to run tasks
[COMMANDBOX-54] - Create watchers
[COMMANDBOX-459] - Create the --system argument to all package commands for system wide packages
[COMMANDBOX-513] - Allow REST servlet to be configured
[COMMANDBOX-548] - Allow custom JRE version for server starts
[COMMANDBOX-560] - Support Basic Auth
[COMMANDBOX-564] - Allow placeholders in for env vars and system props
[COMMANDBOX-585] - Provide convenient command to do simple token replacements from the CLI
[COMMANDBOX-589] - Checksum Command
[COMMANDBOX-590] - Property files commands support
[COMMANDBOX-599] - Add MinHeapSize setting
[COMMANDBOX-608] - Support for viewing/installing private packages
[COMMANDBOX-610] - Finalize box.json testbox runner options
[COMMANDBOX-613] - Allow Command DSL to set working directory
[COMMANDBOX-614] - Implement "testbox watch" command
[COMMANDBOX-638] - Simple Jar endpoint
[COMMANDBOX-642] - Ability to disable tray icons
[COMMANDBOX-644] - Allow ad-hoc aliases to be created for commands
[COMMANDBOX-645] - Allow global defaults to be set for command parameters
[COMMANDBOX-647] - Automatic collection from parameter names containing a colon
[COMMANDBOX-648] - Implement the equiv of Tomcat's remoteIPValve
[COMMANDBOX-649] - Support missing Tuckey config settings
[COMMANDBOX-655] - Command to remove trailing whitespace from files
[COMMANDBOX-656] - Command to add final EOL to files

Task

[COMMANDBOX-568] - Better error message for invalid JSON in a server.json file

Improvement

[COMMANDBOX-429] - Update debian build signing to be higher than SHA-256
[COMMANDBOX-586] - If publishing but not logged into forgebox, prompt for login instead of just erroring
[COMMANDBOX-597] - Clean up SSL cert and key file parameters for server start
[COMMANDBOX-601] - Improve HTML to ANSI conversion on larger strings
[COMMANDBOX-602] - Refactor JSON formatter to separate lib for reuse
[COMMANDBOX-606] - Add trace flag for starting server
[COMMANDBOX-612] - Improve output of "testbox run" command
[COMMANDBOX-617] - Remove deprecated and unused properties from box.json with init
[COMMANDBOX-618] - Don't try to output binary data in REPL
[COMMANDBOX-622] - Show "last started" datetime for servers
[COMMANDBOX-623] - Customize URL that opens when starting server
[COMMANDBOX-626] - Allow commandbox-modules to register endpoints
[COMMANDBOX-646] - Enhance parser to allow quoted spaces in parameter names
[COMMANDBOX-650] - WireBox injection DSL allow to drill down into Config Settings
[COMMANDBOX-652] - Command to remove trailing spaces from code files
[COMMANDBOX-657] - Allow console flag to be stored in server.json like every other setting
[COMMANDBOX-658] - Allow publishing of private packages

What's New in 3.6.0

Improve OS binary execution

You've been able to run OS binaries from the CommandBox interactive shell for a while now which is great for adding native CLI calls to your recipes.

CommandBox> !git push

The biggest problem with this though was that no output shows on the screen until the OS command is completely finished and if your OS command blocks for interactivity or just never ends, the CommandBox shell will just "hang" with no output. All that is a thing of the past now. The standard input and output of the OS process is now bound to the standard input and output of your CommandBox shell. That means that you see output as soon as the binary outputs it and if it stops to ask you for input, you can provide it. This opens up a world of possibilities.

You can ping an address and watch the output stream as the packets return.
You can do a Git commit and interact with the VI window that appears to capture your commit message.
You can actually open a bash/DOS shell right inside of CommandBox and then "exit" back to box when you're done.
Run native commands that collect input from you to continue like a sudo password.

CommandBox> !ping -c 4 google.com
CommandBox> !git commit
CommandBox> !bash
CommandBox> !sudo command

This has been tested and works pretty well on Mac and Windows. Note, we've seen some issues on Linux where output is streamed, but input is not captured.

New interceptor points

preServerForget - Always fires before attempting to forget a server whether or not the forgetting is actually successful
postServerForget - Fires after a successful server forget. If the forget fails, this will not fire.

Allow spaces in user home directory

This was supported in CommandBox 3.4.0, but we had a regression in 3.5.0 that caused issues for users who have a space in their path to CommandBox's home dir. This has been fixed along with some related issues with the FusionReactor module. Make sure you have the latest Fusion Reactor module once you upgrade to CommandBox 3.6.0.

CommandBox> install commandbox-fusionreactor

New Lucee version

The core version of Lucee that the CLI runs on has been updated to 4.5.5.006. Please note this means the default version of Lucee that starts up for your server when you don't specify otherwise will change. If you have settings like datasources and such that you want to keep, make sure you lock in your exact version of Lucee or check into our new CFConfig project for exporting/importing your server settings.

Incorrect exit code from "testbox run"

The testbox run command would return an exit code of 0 when your tests had in fact failed. This has been fixed so you can trust a proper exit code from the process when running your tests inside a Jenkins or Travis CI build.

$> box testbox run runner=http://localhost:8080/tests/runner.cfm

Global default for HTTP port in config settings

Previously, you couldn't set a global default HTTP port for all your servers. This was on purpose since it didn't really make sense since one one server can use a port at a time. Now, with the introduction of Chris Schmitz's host updater module, you can more easily run each server on a dedicated host name which is added to your host file for you and bound to a unique port. This allows you to run all your local servers on port 80 which is great for cleaning up your local dev. As such, we've added the ability to set the global HTTP port now in your config setting's server defaults.

CommandBox> config set server.defaults.web.http.port=80

Release Notes

Here's the full release notes for the 3.6.0 release.

Bug

[COMMANDBOX-553] - Windows CommandBox upgrades fail silently if servers are left running
[COMMANDBOX-554] - Box start error
[COMMANDBOX-555] - All semicolons removed in REPL which breaks some code
[COMMANDBOX-558] - Can't start server when space is in user home dir
[COMMANDBOX-559] - server list --verbose produces an error
[COMMANDBOX-567] - package list sometimes shows incorrect version of 1.0.0
[COMMANDBOX-572] - Running server info on non-server folder creates empty server details
[COMMANDBOX-575] - CommandBox fails to start if a 3rd party module fails to load
[COMMANDBOX-582] - NPE on some URLs occasionally
[COMMANDBOX-587] - testbox run doesn't always return correct exit code on failure

Improvement

[COMMANDBOX-502] - improve execution of OS binaries in "run"
[COMMANDBOX-556] - Add xxxServerForget interceptors to the Server lifecycle
[COMMANDBOX-570] - Improve port binding detection
[COMMANDBOX-571] - Allow port to be defaulted in config settings
[COMMANDBOX-576] - Improve CommandBox module installations
[COMMANDBOX-578] - Bump Lucee version to 4.5.5.006

What's New in 3.5.0

CLI Shell

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

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

We also made the following improvements to the CLI shell environment

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

Tail Command

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

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

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

Package Management

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

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

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

Server Starting

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

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

Server Welcome Files

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

Better SES URLs

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

Server Configuration

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

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

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

Custom Server Home

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

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

A Few Changes

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

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

Release Notes

Bug

New Feature

Improvement

What's New in 3.4.0

Bug Fixes

This release fixes an issue where Adobe CF servers will not start if you're machine is offline and also fixes a bug where the previous version of CommandBox didn't correctly remove old versions of jar files on upgrade.

Enhancements

Git tags when bumping a package command can have a custom prefix now. Tab completion options are also alphabetized. Ctrl-C is also handled better on Unix and actually works in Windows! Also, the timestamp on your sever.json file won't be updated unless the contents of the file actually changed.

Release Notes

Here is the full list of everything that changed in the CommandBox 3.4.0 release.

Bug

[] - Adobe Servers won't start offline
[] - start serverConfigFile=myServer.json doesn't load json settings
[] - Adobe web.xml Flex config path is wrong after first engine start
[] - Error checking whether server is running
[] - cflib-coldbox endpoint creates invalid CFML for Adobe
[] - write history before command finishes
[] - Coldbox create interceptor doesn't create test with proper CFC mapping
[] - war path not stored in server.json as relative path
[] - CFML upgrades don't delete removed files
[] - Forgetting a named server deletes the 'default' server.json too

New Feature

Improvement

What's New in 3.3.0

Server Enhancements

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

Fusion Reactor Module

The more people begin to use CommandBox for local development, the more interested they became in being able to run FusionReactor on their dev servers to help trouble shoot their code. That's why we created a CommandBox FusionReactor module. It's not part of the core, but can be installed in a single command and will attach FusionReactor's server monitor to every server you start. You'll need to have a FusionReactor license or sign up for a trial to use it.

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

Web Aliases

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

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

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

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

server set web.aliases./foo = bar

Custom Error Pages

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

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

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

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

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

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

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

Pre/Post package scripts

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

preFoo
foo
postFoo

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

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

forgebox whoami

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

forgebox use myUser

onRelease interceptor/package script

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

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

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

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

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

bump --minor
publish

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

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

onInstall interceptor/package script

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

CLI Engine Update

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

start cfengine=lucee@4.5.2+018

Release Notes

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

Bug

[COMMANDBOX-187] - error when updating forgebox when slugname changes
[COMMANDBOX-422] - Empty command CFCs with no functions throw an error starting box
[COMMANDBOX-423] - Error "key [FUNCTIONS] doesn't exist" thrown when trying to start command box
[COMMANDBOX-426] - server name completion errors on server open command
[COMMANDBOX-434] - Document the resolvePath() differing behaviour on OSX vs Windows
[COMMANDBOX-435] - artifacts clean fails on OSX when there's .DS_Store files
[COMMANDBOX-437] - appSkeleton in the coldbox create app wizard needs to comply to IDs instead of local disk
[COMMANDBOX-449] - "server open" always opens localhost
[COMMANDBOX-451] - The trayicon in server.json does not work with relative paths
[COMMANDBOX-464] - update command doesn't respect original install path
[COMMANDBOX-465] - custom url rewrite location doesn't respect starting server by name in different location
[COMMANDBOX-466] - coldbox create crud doesn't work on Windows

New Feature

[COMMANDBOX-316] - Add Fusion Reactor support for server
[COMMANDBOX-399] - Starting server in web root with WEB-INF treats CWD as war
[COMMANDBOX-416] - Add "open" flag to touch/new command.
[COMMANDBOX-430] - forgebox whoami command to show what user your API key is set to
[COMMANDBOX-431] - Update the storage of the APIkey in the commandbox settings to include multiple keys
[COMMANDBOX-432] - Have a forgebox use {username} command to switch the current api key
[COMMANDBOX-445] - Allow aliases (virtual directory) in web server
[COMMANDBOX-458] - Provide custom 40x and 50x error pages for servers

Improvement

[COMMANDBOX-398] - Catch error scenario when user tries to start a server with a WEB-INF
[COMMANDBOX-410] - Upgrade to latest Runwar with several bug fixes
[COMMANDBOX-412] - Refactor string similarity to use external library
[COMMANDBOX-413] - Refactor semver CFC to be separate lib
[COMMANDBOX-414] - Refactor path pattern matcher CFC to be separate lib
[COMMANDBOX-419] - coldbox create app command does not list all templates
[COMMANDBOX-420] - Run pre/post package scripts by convention
[COMMANDBOX-421] - Add onRelease interception point/package script
[COMMANDBOX-424] - Serious performance issue with formatting large JSON strings
[COMMANDBOX-425] - Better handle syntax errors in a module's config
[COMMANDBOX-427] - Move onServerStart interception announcement to have server home dir
[COMMANDBOX-428] - Allow tray options to be customized
[COMMANDBOX-433] - Add onInstall interception point
[COMMANDBOX-436] - Incorrect custom model path in the unit test
[COMMANDBOX-440] - Exit REPL multi-line with extra enter stroke
[COMMANDBOX-442] - Don't use in-use port specified in start params or server.json
[COMMANDBOX-443] - Wait for full debug output when starting server with debug=true
[COMMANDBOX-444] - Append JVM args and runwar args to server defaults
[COMMANDBOX-454] - Update to Runwar 3.4.10
[COMMANDBOX-457] - Improve server status detections
[COMMANDBOX-460] - Show tag stack when executing .cfm files
[COMMANDBOX-461] - Improve tab completion of forgebox slugs
[COMMANDBOX-467] - Allow custom images inside tray menu plus disabled items
[COMMANDBOX-468] - Add overwrite confirmations to all coldbox create commands
[COMMANDBOX-469] - Improve version output in "forgebox show" command
[COMMANDBOX-470] - Upgrade engine to Lucee 4.5.3.020

What's New in 3.2.0

Offline Server Starts

One of the biggest pieces of feedback we got from the CommandBox 3.1 release was that it requires an Internet connection to start a server. Since you can specify the version of the server you want to start, including semver ranges like 5.x, this required a trip to ForgeBox to check and see what the best version match was since it might have changed since the last time you started the server.

CommandBox> start cfengine=lucee@5.x

Now, if you provide an exact CF engine version number (meaning you give us a major, minor, AND patch version) CommandBox will skip phoning home to ForgeBox and will just continue with that version.

CommandBox> start cfengine=lucee@5.0.0

Remember that the version "5" de-sugars to "5.x.x" so you need to have all three numbers even if they're "0"

Failsafe Server Starts

We even went a step further. Sometimes ForgeBox may be down for maintenance or due to an outage and it was preventing people from being able to start their servers. If ForgeBox can't be reached for some reason while starting the server, we'll try again by comparing the version range you provided with the CF Engines already cached in your local artifacts cache. If we can find a version that satisfies what you asked for, we'll use it to start the server. That means you might not be getting the latest version of the engine from ForgeBox, but at least your server will start with that is has downloaded already.

Unpublish Packages

Unpublishing a package should be something you rarely need to do since once a package is published, someone else may be depending it for their app to run. However, we now have an unpublish command you can run from the CLI to remove a specific version of a package, or the entire package itself from ForgeBox.

CommandBox> unpublish
CommandBox> unpublish 1.2.3

New Server Updates

We've also included the latest versions of Adobe ColdFusion 10, 11, and 2016 on ForgeBox. This is something we can update separately from our CommandBox releases, but they came at the same time so I bundled the announcements together :) Here are the latest Adobe versions available:

Adobe CF 10.0.20+299202
Adobe CF 11.0.09+299201
Adobe CF 2016.0.02+299200

Bug Fixes

We also fixed a few bugs too. For example, targeting a Git tag stopped working in version 3.1 due to a library update, plus CommandBox's proxy settings weren't being used for all HTTP requests.

Release Notes

Here's the full list of everything in version 3.2.0 of CommandBox. Click on the ticket numbers for more details in JIRA.

Bugs

[COMMANDBOX-400] - Box install throws exception on git endpoint with commit-ish syntax
[COMMANDBOX-406] - Starting server from diff directory by name uses wrong web root
[COMMANDBOX-407] - semver isExactVersion returns true for 3 and 3.4
[COMMANDBOX-408] - Proxy server not used in ForgeBox calls

New Features

[COMMANDBOX-397] - Unpublish command
[COMMANDBOX-402] - Show package URL location after publish, some consoles allow you to click and visit
[COMMANDBOX-403] - Show number of packages in forgebox types
[COMMANDBOX-404] - Add ForgeBox URL to show command as some consoles allow you to visit
[COMMANDBOX-405] - Add ForgeBox URL to search command so consoles can click and open

Tasks

[COMMANDBOX-409] - Add new patches for Adobe CF 10, 11, and 2016 to forgebox

Improvements

[COMMANDBOX-391] - Add Offline Ability for cfengine Server Start
[COMMANDBOX-401] - Add box.json data to pre/post publishing interceptors

What's New in 3.1.1

Multi-Server

Now CommandBox will not only start up Lucee 4 servers with a single command, but you can start up Adobe ColdFusion, Railo, and even Luce 5 servers all at the same time. Now it's easier than ever to test your code across multiple platforms. CommandBox's embedded server makes for a fast and easy development machine too regardless of what CF engine you need.

ForgeBox 2.0 API

We'v released a brand new site with a new UI, fresh features, and a shiny new API. CommandBox 3.1.1 is now powered by the new ForgeBox site and API which includes features like having more than one version for a package.

Semantic Versioning support

Create user from CLI

Publish packages from the CLI

You no longer need to visit the ForgeBox web site to publish new or updated packages to ForgeBox. This is all available from the CLI once you've logged in. This means you can even automate the process of publishing to cut down on the number of manual steps it takes you to update your projects and share those changes with the community.

Interceptor-based CLI scripts

You can now run commands of your choosing automatically when certain events in the CLI happen (like publishing a package, or starting a server). You can also create ad-hoc collections of commands to run whenever you want to help automate things like building your projects or publishing to ForgeBox.

Have Fun

Release Notes

Bug

New Feature

Task

Improvement

What's New in 3.0.1

Properties weren't being read correctly from the server.json file. If you have been using server.json, please double check the format of the file here in our docs:

This fix will make this functionality work as expected:

Upgrading

If you already have 3.0.0 then this fix only affects the CFML bits and is very easy for you to install. Simply run this command:

If you're still on CommandBox 2.x, check out our to see the cool new stuff.

What's New in 3.0.0

Config Settings

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

Modules

This is perhaps the most radical thing we've done in CommandBox to date and it is huge. We've introduced modules (just like ColdBox) into the actual CLI itself. A module is a unit of code re-use that allows you to take a folder of code that follows a few simple conventions and drop it into a module-aware application for instant extension. This means that we've broken out all the internal commands into system modules for organization. What's more, you can write your own CommandBox modules that hook into the internal workings with interceptors, register their own custom commands, or help manage settings or servers. Modules can be placed on and installed by your friends in seconds to extend the core of CommandBox. The benefits here can't be understated. Check out and go through the quick, easy steps to create your first CommandBox module.

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

Interceptors

CommandBox interceptors, like modules, work the same way that ColdBox interceptors do. They give you hooks that you can register to listen to events broadcast by the CommandBox core, or custom events of your own design that you announce. These are very powerful for being able to extend and modify how the core CLI works to build upon it. Interceptors are bundled inside modules so they install quickly and easily. Distribute them on as well. I've already created a that uses the onCLIStart interceptor to modify the ASCII art banner that appears when you start CommandBox.

Here's some of the core interception points:

onCLIStart
onCLIExit
preCommand
postCommand
onServerStart
onServerStop
onException
preInstall
postInstall

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

Standardized Command Packaging

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

Server.json

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

Shortcut for Native OS Binaries

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

Shortcut for CFML Functions via REPL

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

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

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

Expressions in Command Parameters

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

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

Command DSL

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

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

New WireBox Injection DSLs

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

Release Notes

Bug

New Feature

Task

Improvement

2.x Versions

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

- Nov 2015
- Aug 2015
- Aug 2015
- June 2015

What's New in 2.2.0

Release Notes

Bug

[] - Execute command doesn't work in interactive shell
[] - Testbox create commands break if testname includes package
[] - installpaths not added when not creating package directory
[] - Git endpoint psses java.io.File instead of string
[] - HTTP Endpoint package name guessing doesn't account for periods in file name
[] - When you do an 'update' command, it updates the modules but does not update the box.json with the latest version
[] - SQL Server JDBC driver doesn't work
[] - Sign Debian packages

New Feature

[] - Update the status command to output the results in json
[] - Update coldbox model generator to allow the creation of accessors
[] - Add ability to generate properties on coldbox model generations
[] - Update all BDD tests to fail by default to promote refactoring and process
[] - CFLib endpoint
[] - RIAForge Endpoint

Improvement

What's New in 2.1.1

This fixes a bug in the "update" and "outdated" commands that caused them to error after you had installed packages from an endpoint other than ForgeBox. Note, packages installed from HTTP(S) and Git endpoints will always show as outdated and will always update since those endpoints don't provide a way to know what version they're hosting without downloading the entire package anyway.

We also included a small enhancement to the Git endpoint to allow for authentication via public/private SSH keys. As long as you have a public key configured on your Git server and the private key is stored in ~/.ssh/ using a standard name, SSH-based clones should automatically authenticate. Please see for more info.

As always, the is located here:

Release Notes

Bug

[] - update command erroring

New Feature

[] - Git SSH endpoint private key support

Improvement

[] - Standardize parameter names for install command

What's New in 2.1.0

Specifying a max heap size for your embedded server

And finally, the ability to install packages from a Git repo is here!

And this nice shortcut for installing from GitHub:

If you've not used CommandBox yet, check out our getting started guide here:

You can download CommandBox 2.1.0 here on our product page:

Release Notes

Bug

[] - Piping content to box repl
[] - Lucee default error template is broken in CLI
[] - OWASP jars corrupt
[] - REPLParser doesn't allow // in strings (like in URLs)
[] - commandbox.properties isn't picked up when box.exe is in a folder with spaces

Improvement

New Feature

What's New in 2.0.0

We Love Lucee

The biggest feature is the switch-over from Railo to Lucee as the underlying CLI engine that powers the REPL and commands. The embedded server now also runs Lucee 4.5 as well. If you require a Railo embedded server, you will need to stay on CommandBox 1.1.1 for now.

Endpoint Support

Another major new feature is support for different endpoints when installing packages in addition to ForgeBox. Now packages can be installed from the following locations:

Local zip file
Local folder
HTTP/HTTPS URL that points to a package zip
ForgeBox (default)

The ForgeBox endpoint now also has rudimentary support for targeting a specific version. If you request a specific version of a package to be installed, and it is in your artifacts cache, no network calls will be made. This allows completely offline installations! Here are some examples:

We also have a nice collection of bug fixes. Below are the full release notes for CommandBox 2.0.0.

Release Notes - CommandBox - Version 2.0.0

Bug

New Feature

1.x Versions

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

- Feb 2015

What's in 1.0.0

After almost a year in development, we are so excited to finally announce the release of . This has been definitely one of the most challenging and fun projects we have overtaken here at Ortus. We had a vision of how we could accelerate not only development, tools and ultimately the ColdFusion (CFML) landscape by building a tool that could put us up to par with many other technologies. I am glad to say we have now a great foundation to move forward. CommandBox brings CFML to any Operating System and even embedded systems like the Raspberry and Banana Pi. It also gives ColdFusion (CFML) developers a much better workflow to work with their projects and a sense of community we lovingly call .

With anything we do here at Ortus, it is fully documented using our new book formats. So head on over to to download or read the entire CommandBox documentation. In the next coming weeks we will begin our CommandBox 5-week roadshow that will include weekly blogging tutorials and video presentations, so stay tuned as each week progresses. So without further ado, I present to you project Gideon: CommandBox CLI!

CommandBox

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

Package Management

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

REPL: Read-Evaluate-Print-Loop

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

Application Scaffolding

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

Extensible

Automation

Embedded Server

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

Auto Updates

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

Stable : Stable releases
Bleeding Edge : Bleeding edge releases

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

Future RoadMap

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

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

What's New in 5.1.0

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

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

What's New in 5.8.0

Bundled System Modules

To be more useful, CommandBox now bundles the following system modules

They will be automatically installed (or updated) when you start the CLI for the first time. You can still update or uninstall them, just like any system module. Note: If you have any of these modules currently linked into the CommandBox core, any uncommitted changes will be overwritten when you upgrade box. Please unlink the repos first before upgrading.

The CommandBox Update Check modules can be disabled if you don't like it via

config set modules.commandbox-update-check.enable=false

It will also automatically obey the offlineMode Config Setting.

Custom MIME Types

CommandBox will automatically set the content type in the HTTP response for common static file types. If you come across a file extension that doesn't have the correct type, you can set it like so in your server.json:

server set web.mimeTypes.log=text/plain

Which creates the following

{                            
    "web":{                             
        "mimeTypes":{                  
            "log":"text/plain"      
        }
    }
}

In the above example, hitting a file such as foo.log would come back with a text/plain content type header.

This setting will override any <mime-mapping> tag in your web.xml file.

More Info: https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/mime-types

Config and Module Sync

If you are authenticated to ForgeBox in the CLI, you can synchronize your config settings to and from your ForgeBox account. This is a great way to get up and running on a new PC or keep multiple CommandBox installs in sync. In addition to synchronizing your Config Settings, this feature will also track your installed system modules, such as CFConfig, etc.

config sync push

This command will push your local settings and modules up to your ForgeBox account.

config sync push

By default, the settings are "merged" so new local settings will be added to ForgeBox, but nothing will be removed. To remove config that only exists on ForgeBox, you can use the --overwrite flag to force a full sync.

config sync pull

This command will pull your settings and modules from your ForgeBox account and set/install them locally.

config sync pull

By default, the settings are "merged" so missing settings will be added locally, and missing system modules will be installed, but nothing will be removed. To remove config and modules that only exist locally, you can use the --overwrite flag to force a full sync. This will remove local config settings and uninstall local system modules which were not on ForgeBox.

config sync diff

This command will not change anything, but gives you a full report of all settings which are different between your local CommandBox CLI and ForgeBox. It will show you "Remote Only," "Local Only," and "Changed" settings and modules. Use this to see what you're about to change before pushing or pulling.

config sync diff

onServerInitialInstall interceptor

This is the same as onServerInstall, but it only runs the VERY FIRST time a CF engine is installed. This is helpful if you want to install Lucee extensions or ACF modules and only need to do it the first time. This interceptor is easier than using onServerInstall and inspecting the installDetails.initialInstall flag.

Case Sensitivity of Web Server

This has been an experimental feature of CommandBox servers for a while, but we've finalized the feature and added a proper setting to enable it in server.json. By default, the web server in CommandBox will follow the case sensitivity of the underlying file system. So, when on Windows /FiLe.TxT will still load an actual file called /file.txt. But on Linux, the case in the browser would need to match that of the file system. CommandBox allows you to force case sensitivity to be ON or OFF for a server, overriding the server's file system.

Forcing Case sensitivity

To force CommandBox's web server to be case sensitive, even on operating systems like Windows, use the following setting. There is a nominal performance benefit in doing this, and it can allow a Windows CommandBox server to mimic a Linux server for testing.

server set web.caseSensitivePaths=true

Forcing Case Insensitivity

To force CommandBox's web server to be case insensitive, even on operating systems like Linux, use the following setting. There is a nominal performance overhead in doing this, and it can allow a Linux CommandBox server to mimic a Windows IIS server. In this mode, CommandBox will use an internal cache of file system lookups to improve performance. If there are two files of the same name using different case, then you will get whatever file is found first.

server set web.caseSensitivePaths=false

Support for PFX cert files

If using CommandBox's SSL, you can now use a PFX file (PKCS #8 format) which contains the public and private key in one file.

More Info: https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/ssl-certs

Case Insensitive Server Rule Predicates

Most of the Server Rule predicates are case-sensitive, which poses a problem when using them for security on Windows since they will only match one specific spelling of a folder or file. We have added "-nocase" versions of several popular predicates which perform case-insensitive checks.

regex-nocase()
path-suffix-nocase()
path-prefix-nocase()
path-nocase()
equals-nocase()
contains-nocase()

Server Rule Reverse Proxy handler supports SSL

Undertow's reverse-proxy() handler would not connect to a back-end server using SSL. We've given up on RedHat fixing this any time soon, and added a new load-balanced-proxy() handler which works with SSL.

load-balanced-proxy({'https://reports1.mydomain.com','https://reports2.mydomain.com'})

REPL Improvements

Due to long-standing bugs in the Lucee evaluate() function that seem like they'll never get fixed, we've finally put a workaround in the REPL, which captures the return value of member functions chained to literals and expressions using closures. Ex:

CFSCRIPT-REPL: "test".len()
4
CFSCRIPT-REPL: [1,2,3].each( (i)=>echo(i) )
123

Per-Server Preferred Browser Setting

There is already a Config Setting for the preferred browser when opening up sites. You can now customize this on a per-server basis with this server.json setting

server set preferredBrowser=firefox
server open

New Server Console Log Layouts

You can now control the Log4j appender layout for CommandBox servers, which includes formats such as JSON, which allows your server logs to be automatically imported into Elastic Search

server set runwar.console.appenderLayout=JSONTemplateLayout

New forgebox version-debug command

There is a helpful command called forgebox version-debug which will show you what version of a package will be installed without actually installing it. It can also be useful to test a semver range and see what packages it matches.

Release Notes

Bug

COMMANDBOX-1537 Experimental feature force insensitive web server has stopped working in some cases

COMMANDBOX-1541 Hide Felix error messages in console on startup

COMMANDBOX-1542 Custom tray options calling box with space in path fail

COMMANDBOX-1550 Add load-balanced-proxy() handler to replace Undertow's broken reverse-proxy() because they refuse to fix it

COMMANDBOX-1551 Capture return value from some REPL expressions because Lucee refuses to fix evaluate()'s parser

COMMANDBOX-1552 Two instance of CLI cause class loading issues from OSGI bundles

COMMANDBOX-1559 server start port check doesn't take web.http.enable into accout

New Feature

COMMANDBOX-1434 CommandBox settings sync feature

COMMANDBOX-1539 Add onServerInitialInstall package/server script

COMMANDBOX-1540 Add `.webp` as a default mime type for CommandBox to support this new image format

COMMANDBOX-1543 Formalize setting for case sensitivity of web server

COMMANDBOX-1549 Add "nocase" versions of regex(), path-suffix(), path-prefix(), equals(), contains(), and path() predicates

COMMANDBOX-1555 Improve forgebox whoami command

COMMANDBOX-1556 Allow CommandBox to customize console appender Layout

COMMANDBOX-1562 New "forgebox version-debug" command

COMMANDBOX-1566 Bundle super helpful modules in box core

COMMANDBOX-1567 onConfigSettingSave and onEndpointLogin interception announcements

Improvement

COMMANDBOX-1034 Ability to pass file name to "more" command

COMMANDBOX-1345 Add a method in server.json to add MIME type mappings to Undertow

COMMANDBOX-1393 Improve message when starting second server with single server mode enabled

COMMANDBOX-1538 system setting serverinfo namespace use interceptdata if running inside of server script

COMMANDBOX-1544 Allow `web.webroot` to be changed in single server mode

COMMANDBOX-1545 Authentication failures don't send custom error pages

COMMANDBOX-1547 Add directory param to coldbox watch-reinit command

COMMANDBOX-1548 Support PKCS #8 format private keys

COMMANDBOX-1554 Allow preferredBrowser to be set on a per-server basis

COMMANDBOX-1557 Add file and directory completion to the ID param of the install command

COMMANDBOX-1558 Add installExtension() for commands and task runners to install Lucee extensions on the fly to the CLI

COMMANDBOX-1560 Update Lucee to 5.3.10.120 in CLI core

COMMANDBOX-1561 Improve upgrade command

COMMANDBOX-1564 Load libdirs in system classloader

COMMANDBOX-1565 Check for default branch of "main" in Git endpoint

Task

COMMANDBOX-1357 Try removing JAX API classes from runwar

COMMANDBOX-1546 Update to Undertow 2.2.22-Final

COMMANDBOX-1553 Update bundled JRE to jdk-11.0.18+10

COMMANDBOX-1563 Remove stopgap for COMMANDBOX-1459

Release History

6.x Versions

What's New in 6.0.0

Multi-Site Servers

Enhanced Server Bindings

SSL SNI Support

Rewrite Maps

Publish command directly uploads to S3

Add a proxy server rule alias

Specify Package and Server scripts as an array

ColdBox, TestBox and ContentBox commands are now modules

Adobe CF Script Alias

CommandBox Pro Config settings auto-sync

Release Notes

Bug

New Feature

Improvement

Task

5.x Versions

What's New in 5.9.0

Java 17 Support

Library Updates

Override package install paths

ls --tree

Tree Print Helper

Column Print Helper

unansi Command

clipboard Command

Release Notes

What's New in 5.7.0

Check Out The New Stuff

New Feature

COMMANDBOX-1535 update coldbox resources to support api resources

COMMANDBOX-1536 artifacts prune command

Bug

COMMANDBOX-1507 Use user.home instead of user.dir to test case sensitivity

COMMANDBOX-1510 Cursor position get's off-track when using a multiselect with content that exceeds the terminal size

COMMANDBOX-1511 ModCFML doesn't save actual Lucee webConfigDir

COMMANDBOX-1513 Runwar server's regex path info filter doesn't take servlet context into account

COMMANDBOX-1517 Two servers get same name when moving folder

COMMANDBOX-1518 Can't pass Windows drive letter to "open" command

COMMANDBOX-1519 Error passing empty version to "java search" command

COMMANDBOX-1524 Interactive job logs don't obey terminal width config setting

COMMANDBOX-1525 REPL errors when representing some Java objects

COMMANDBOX-1527 recipe file validation fails

COMMANDBOX-1528 Java integration doesn't recognize ARM CPUs

COMMANDBOX-1533 coldbox resources command failing on relative models directory not found

Improvement

COMMANDBOX-1378 make "upgrade" command handle new jars

COMMANDBOX-1499 Support pfx format for server certs

COMMANDBOX-1512 Have fileAppend (>>) and fileWrite (>) commands create missing parent directories

COMMANDBOX-1514 REPL obey verboseErrors config setting

COMMANDBOX-1516 cfpm doesn't find Adobe server with different web root

COMMANDBOX-1520 Make client cert CGI vars available immediately after SSL renegotiation

COMMANDBOX-1521 Add --json to artifacts list

COMMANDBOX-1523 Touch artifacts on use so we can prune unused ones easier

COMMANDBOX-1534 Update coldbox resources command to latest version

Task

COMMANDBOX-1526 Update bundled JRE to 11.0.17+8

COMMANDBOX-1529 Update Undertow lib in Runwar

COMMANDBOX-1530 Update json-smart-mini and Lucee libs

What's New in 5.6.0

Library Updates

Lots of Bug Fixes

New Server Security System

Basic Auth Security

Client Cert Security

Task Runner loadModules()

Release notes

What's New in 5.5.2

Release notes

Bug

Improvement

Task

What's New in 5.5.1

ModCFML Support

Log4j 1.x is gone!

Library updates

Set Java System Props directly in server.json

JVM Args can be an array

Task Runner `loadModules()`