We've been hard at work on the latest version of CommandBox which brings bug fixes, improvements, and new options for deploying and starting servers.  We think it's ready for the general public to give it a good testing before we release it so today we're announcing the CommandBox 3.5.0-rc (release candidate) for you to give a spin.  This should be a painless switch so we encourage you to take a look and provide us with feedback.  We are also pleased to have several features and fixes in this release that were provided by community members as part of our first 1000 open source pulls.

How Do I Get It?

Since this is a pre-release version, you can grab it off of our integration server at the following URL.  Choose the correct download for your OS.  You may notice these downloads are larger than normal.  That's because we turned off the super-compression for our non-stable builds to speed them up.  The final version of 3.5 will be "normal" sized (about 38MB)

http://integration.stg.ortussolutions.com/artifacts/ortussolutions/commandbox/3.5.0-rc/

If you need a reminder of what that URL is later, just run this command:

CommandBox> upgrade --latest

If you're using HomeBrew on a Mac, or apt-get/yum on Linux, you can also follow the instructions here.

https://ortus.gitbooks.io/commandbox-documentation/content/setup/installation.html

Simply stop CommandBox, replace the old binary, and re-start the CLI to complete the upgrade.

Where Are The Docs?

You can read the bleeding edge API docs here for any commands that changed:
http://integration.stg.ortussolutions.com/artifacts/ortussolutions/commandbox/be-apidocs/

The new 3.5 docs are also written and available here at this "development" GitBook URL.

https://commandbox.ortusbooks.com/content/v/development/

What Changed?

There are over 50 completed tickets in this release.  You can review the full release notes here.

https://ortussolutions.atlassian.net/secure/ReleaseNote.jspa?projectId=11000&version=17700

For the main highlights, keep reading.  Please read all the way to the end to see a list of small internal changes that might affect your current server setups.

CLI Shell

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

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

We also made the following improvements to the CLI shell environment

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

Tail Command

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

CommandBox> forgebox search | tail lines=50

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

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

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

CommandBox> server log --follow

Package Management

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

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

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

CommandBox> install myPackage@1.2.3-snapshot

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

Server Starting

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

CommandBox> server start --debug

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

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

Server Welcome Files

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

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

Better SES URLs

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

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

We've added just a dash of servlet fairy dust that now makes this possible.  Note, if you want to hide the index.cfm with URL rewrites, you'll need a custom rewrite config for it to work in a subfolder.

Server Configuration

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

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

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

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

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

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

Combining these allows you to do some nice one-liners like scripting out the copying of config settings when the server starts up.  Hint: Use an onServerInstall or onServerStart package script!

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

Read more about this here:

https://commandbox.ortusbooks.com/content/v/development/embedded_server/copy-configs.html

Custom Server Home

Until now you've had to live with the special directory that CommandBox uses to install your servers into.  Now you can get full control over where the server goes which is perfect for creating a folder "seeded" with config files that you want the server to use when it first starts.  This trick (with some clever Git ignores) will also allow you to commit changes to your config files back to the repo while ignoring the rest of the engine.

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

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

Read more about this here.

https://commandbox.ortusbooks.com/content/v/development/embedded_server/custom-server-home.html

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