After 6 months of development, we are pleased to announce that CommandBox 4.0.0-RC.2 is available for your testing.  In case you're wondering, RC.1 was released at Into The Box last month, but I was super busy at the time and on the road for 2 solid weeks and didn't have the docs fully updated, so I didn't have a chance to blog it then.  A huge thanks goes out to everyone who help contribute ideas, pull requests, and testing for CommandBox 4.  This is truly a group effort.

The first round of testing has came in which resulted in some fixes and a cut of RC.2.  The final release will be very soon so please give this a test now and make sure it's good and solid.  There are some very major changes in CommandBox 4.  It's very nearly backwards compatible, but has had an overhaul of pretty much every underlying Java library it uses so there's lots of potential for accidental changes. See the very bottom of this post for a list of known backwards compat issues.

Download

To get the latest RC.2 build, you can go download it here from our integration server:

http://integration.stg.ortussolutions.com/artifacts/ortussolutions/commandbox/4.0.0-RC.2/

Just swap out your box.exe binary and CommandBox will upgrade itself on first run.  It's a one way street, so feel free to backup the .CommandBox folder in your user home first.  

Everything talked about below (and more) is documented here in our official CommandBox docs:

https://commandbox.ortusbooks.com/

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

There are currently 69 tickets that are part of the 4.0 release.  You can view them all over in JIRA if you filter based on a fixVersion of 4.0.0.  Here's an overview of some of the cooler new features, in no particular order.

256 Color support

This is dependant on your terminal, but the CLI now can look a lot prettier. For Mac users, this will probably work out of the box.  For Windows users, cmd won't cut it.  We recommend checking out ConEMU as a sweet, tabbed terminal replacement.   To see what kind of punch your terminal packs, run this new command:

system-colors

CLI Improvements

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

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

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

Shell History

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

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

CommandBox Bullet Train

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

install commandbox-bullet-train

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

https://www.forgebox.io/view/commandbox-bullet-train

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

CommandBox has a new way to interact with users and give them a list of pre-defined options that doesn't require typing a free text response.  You'll see it if you try to start the same server twice in a row.  This is fully documented and available for you to use in Task Runners and custom commands as well.

Interactive Jobs

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

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

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

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

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

Docs:

https://commandbox.ortusbooks.com/task-runners/interactive-jobs

Example:

job.start( 'Starting server' );
  job.addLog( 'This is the server name' );
  job.addWarnLog( 'Hey, don''t touch that dial' );
​
    job.start( 'Installing CF Engine first' );
      job.addLog( 'This was the version used' );
      job.addLog( 'Yeah, we''re done' );
    job.complete();
​
  job.addLog( 'Aaand, we''re back!.' );
  job.addErrorLog( 'I think we''re going to crash' );
​
job.error( 'Didn''t see that coming' );

Which looks like this when it's done:

Server Logs

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

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

server start --rewritesEnable --console --debug

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

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

server log
server log --follow

Access Logs

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

server set web.accessLogEnable=true

You can view and tail this log file like so:

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

URL Rewrite Logs

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

server set web.rewrites.logEnable=true

You can view and tail this log file like so:

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

Automatic Log Rotation

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

Version Checks on Startup

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

install commandbox-update-check

Pipe output of native OS binaries

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

!java -ver | #ucase

Task DSL

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

https://commandbox.ortusbooks.com/task-runners/running-other-tasks

Example:

task( 'build' )
    .run();

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

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

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

Docs:

https://commandbox.ortusbooks.com/usage/interactive-shell-features#ctrl-c-and-ctrl-d

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:

https://commandbox.ortusbooks.com/task-runners/loading-ad-hoc-jars

Examples:

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

Task Scaffolding

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

task create --open
task run

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

https://commandbox.ortusbooks.com/task-runners/task-anatomy

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.
• You no longer can use \t and \n to escape tab and line breaks in command parameters. This caused a lot of confusion in Windows paths and there are other ways to do it right in your terminal.  Check out the docs on it.
• The waitForKey() method in Task Runners and custom commands no longer returns the ASCII code, but the actual character pressed OR a special string representing the key press like "key_up" or "key_down".  Check out the docs here.
• 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.  

Please let me know if I've missed anything from this list.