Luis Fernando Majano Lainez

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

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

Luis has a passion for Jesus, tennis, golf, volleyball and anything electronic. Random Author Facts:

• He played volleyball in the Salvadorean National Team at the tender age of 17

• The Lord of the Rings and The Hobbit is something he reads every 5 years. (Geek!)

• His first ever computer was a Texas Instrument TI-86 that his parents gave him in 1986. After some time digesting his very first BASIC book, he had written his own tic-tac-toe game at the age of 9. (Extra geek!)

Keep Jesus number one in your life and in your heart. I did and it changed my life from desolation, defeat and failure to an abundant life full of love, thankfulness, joy and overwhelming peace. As this world breathes failure and fear upon any life, Jesus brings power, love and a sound mind to everybody!

“Trust in the LORD with all your heart, and do not lean on your own understanding.” – Proverbs 3:5

Brad Wood

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

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

Brad's CommandBox Snake high score is 141.

Contributors

• Jorge Reyes - ColdBox Aficionado

CommandBox Manual - Version 6.2.0

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

Versioning

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

And constructed with the following guidelines:

• Breaking backward compatibility bumps the major (and resets the minor and patch)

• New additions without breaking backward compatibility bumps the minor (and resets the patch)

• Bug fixes and misc changes bumps the patch

License

CommandBox is open source and bound to the

• Copyright by Ortus Solutions, Corp

• CommandBox is a registered trademark by Ortus Solutions, Corp

Info The CommandBox Websites, Documentation, logo and content have a separate license and they are a separate entity.

Discussion & Help

The CommandBox help and discussion group can be found here:

Reporting a Bug

We all make mistakes from time to time :) so why not let us know about it and help us out. We also love pull requests, so please star us and fork us:

Professional Open Source

CommandBox is professional open source software backed by offering services like:

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

Resources

• Official Site:

• Source Code:

• Ortus Community Forum:

• Bug Tracker:

HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, it's not for you.

"Therefore being justified by **faith**, we have peace with God through our Lord Jesus Christ: By whom also we have access by **faith** into this **grace** wherein we stand, and rejoice in hope of the glory of God." Romans 5:5

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

• The majority of code examples in this book are done in cfscript.

External Trademarks & Copyrights

Flash, Flex, ColdFusion, and Adobe are registered trademarks and copyrights of Adobe Systems, Inc. Railo is a trademark and copyright of Railo Technologies, GmbH. Lucee is a trademark and copyright of Lucee Association Switzerland.

Notice of Liability

The information in this book is distributed “as is”, without warranty. The author and Ortus Solutions, Corp shall not have any liability to any person or entity with respect to loss or damage caused or alleged to be caused directly or indirectly by the content of this training book, software and resources described in it.

Contributing

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

Charitable Proceeds

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

Shalom Children's Home

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

Shalom now cares for over 80 children in El Salvador, from newborns to 18 years old. They receive shelter, clothing, food, medical care, education and life skills training in a Christian environment. The home is supported by a child sponsorship program.

We have personally supported Shalom since 2006; it is a place of blessing for many children in El Salvador that either have no families or have been abandoned. This is good earth to seed and plant.

CommandBox is a Java-based executable that will run on most recent desktop operating systems (Linux, Mac OS X, Windows). Since it is a command line tool that uses a shell interface, it does not even require an operating system using a GUI. CommandBox can be used as a development aid and automation tool alongside your favorite CFML engine and IDE, but neither of those are requirements for installation of CommandBox.

CommandBox is a standalone, native Command Line Interface (CLI), Package Manager, Embedded CFML Server and Read Eval Print Loop (REPL) aimed to help ColdFusion (CFML) developers become more productive through automation, dependency management, command line-based tools, and ASCII snake games.

Features at a Glance

CommandBox is an amalgamation of many different tools and borrows concepts from NPM, Grunt/Gulp, Maven, Bower, and Node. Features include:

• Command Line for ColdFusion (CFML)

• Operating System integration for executing commands

• Ability to create and execute commands built using ColdFusion (CFML)

• ForgeBox integration for cloud package management and installations

• ColdBox Platform, TestBox, and ContentBox CMS Integrations

• Integrated servlet server with rewrite capabilities

• Ability to create command recipes and execution

• REPL (Read-Evaluate-Print-Loop) console for immediate ColdFusion

  (CFML) interaction

• Ability to interact with user via CLI and create workflows and

  installers

• Ability to execute workflows and tasks

• Built-in Help system

This release contains 9 tickets-- several bug fixes and a couple nice new features.

Jakarta Servlet support

Adobe CF 2025, Lucee 7, and BoxLang 1.0 are all using the Jakarta servlet spec now. CommandBox will now detect that and automatically download a Jakarta version of Runwar to start the server on first start.

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

• - February 2024

• - November 2024

• - March 2025

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:

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

• - Feb 2015

Here are the requirements for installing and using CommandBox on your system. Notice some of these such as RAM and disk space depend on how many features you will plan on using. For instance, the shell only allocates about 256MB of RAM to run, but if you plan on starting embedded servers, that will spawn additional threads-- each of which will consume their own memory.

Operating System

• Windows XP+

• Mac OS

• Linux

Hardware

• 256MB+ RAM

• 250MB+ free hard drive space

• Multi-core CPU recommended

Software

A Java JRE is listed as a software requirement, but if you have a brand new PC with no JRE we have a download option that contains the Java Runtime bundled with it.

It is recommend to use Java 11, but there is preliminary support for Java 17. Keep in mind, not all CF engines support Java 17, so if you use it for the CLI, you may want to set your default server JRE to use Java 11.

Even though you can run CommandBox from your favorite terminal window, there are a number of nice IDE integrations out there that are designed to allow you to run command line utilities from inside your favorite editor. Here's a few that we're aware of and how to use them. If you have more, please let us know!

Do you also always type certain parameters every time you run a command, like always typing --force after rm? Any command parameter can be defaulted at a global level so you don't have to type it every time. These defaults will always be overridden if you actually supply the parameter when running the command.

config set command.defaults.rm.force=true
rm myFile.txt

The above example is the same as running rm myFile.txt --force since we've defaulted the force parameter to always be true when not otherwise specified. If you wanted to override your default, you could do so by actually specifying the parameter from the CLI like this:

rm myFile.txt --NoForce

We believe all work and no play makes you a dull boy (or girl!). You'll notice the interactive shell has a handful of quotes and tips that show up when the shell starts. If you have ideas or suggestions for new ones, please send pull requests or let us know.

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're not familiar with how to view these, you want to "diverge" your eyes. This is what happens when you look at something far away and it's the opposite of crossing your eyes. Start with your face closer to the monitor and looking square on. Relax your vision and look past the monitor until the image starts to overlap itself (that's your eyes diverging) until the repeated elements match up again (like the clouds above). Different parts of the image will appear to be different distances away from you.

If you can't see it right away, don't worry. Practice makes perfect and the more you do it, the easier it is. You'll get the hang of it, we promise!

This is a very small release with two changes.

• Update to Lucee 5.4.3.2

• Update bundled JRE to 11.0.20+8

Note Lucee 5.4.3.2 contains critical security patches which are outlined here:

https://dev.lucee.org/t/lucee-critical-security-alert-august-15th-2023-cve-2023-38693/12893

The new Lucee version affects the core CLI runtime as well as the default server you get when running "server start" with no cfengine specified. Possible compatibility issues related to the major bump in Lucee version:

• This Lucee version does not include Hibernate, so the Ortus Hibernate extension is installed. We will stop doing this in 6.0

• This Lucee version has strict XML parsing settings on by default which may affect any servers you start which parse XML containing DTDs.

If you do run into XML errors, this code may help you in your Application.cfc, which allows DTDs, but still disallows XML external entities (XEE).

Release notes

Task

• Update bundled JRE to 11.0.20+8

• Update to Lucee 5.4.3.2

Release notes

Bug

COMMANDBOX-1475 Server shutdowns aren't always done cleanly

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

Globber copyTo() command mishandles *nix leading slash

preServerStart can no longer affect server.json env var replacements

Servers can no longer override rest mappings

Corruption in interactive job output

Can't set XNIO socket settings or Sequence types

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

cfpm breaks in single server mode

Improvement

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

Customize Undertow's enabled SSL protocols

Task

Update to Lucee 5.3.9.141 stable

Release Notes

Bug

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

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

Improvement

Support excludePaths in watcher DSL and watch command

Ensure Adobe wars have a seeds.properties file

Add tab complete for "env clear" command

Ignore empty startScript on server start

CommandBox's true power comes from it's command-based architecture, but we also support just running plain-jane .cfm files as well.

Running plain CFML files

Take the following file for example:

test.cfm

<cfoutput>#now()#</cfoutput>

We can execute this file directly from our native OS prompt by simply passing the filename straight into the box binary.

C:\> box test.cfm
{ts '2015-02-19 20:14:13'}

Or, I can run it from within the CommandBox interactive shell using the execute command:

#! Goodness

Now, you people on Unix-based operating systems like Mac and Linux get a special treat. You can actually create natively executable shell scripts that contain CFML! Check out this file that has the special hash bang at top:

test

All we need to do is make it executable

And then just run it like any other shell script!

CFML Engine

The underlying engine used to execute your files will be the version of Lucee Server that the CLI is currently running on. Note, this can change between releases, and you can see the current version by running the info command. If you want to try to use the <cfadmin> tag to do things like create datasources, the default password for the Lucee server context is commandbox.

Hopefully this gives you a lot of ideas of how to start using CFML on your next automation task. And if you want even more control like print objects, object oriented code, and fancy parameters, look into making custom .

When a command has an argument with a type of Globber for a file path, that means you can use file globbing patterns to affect more than one file at a time. Globbing patterns are common in Bash as well as places like your .gitignore file. They use common wildcard patterns to provide a partial path that can match zero or hundreds of files all at the same time.

"?" matches a single character

If a globbing pattern contains a question mark, that will match any single character. So a pattern of ca?.txt would match car.txt, and cat.txt, but not cart.txt. You can use a wildcard more than once. p?p?.cf? would match files named papa.cfm and pipe.cfc.

"*" matches any number of characters within name

If a globbing pattern contains a single asterisks, that will match zero or more characters inside a filename or folder name. So d*o matches doodoo, dao, and just do. The wildcard only counts inside a file or folder name, so models/*.cfc will only match cfc files in the root of the models folder.

"**" matches any number of characters across all directories

To extend the previous example, if we did models/**.cfc that would match any cfc file in any subdirectory, no matter how deep.

Globbing examples

Here's some examples of what file globbing might look like:

Here's some more examples of how the wildcards work

Since the Globber library can handle more than one globbing pattern, any command that uses a Globber type can accept a comma-delimited list of patterns. The following will list any .cfm AND .md files in the directory.

CommandBox is a Java-based tool that involves several pieces including native Java classes, CFML code, and the embedded Railo CLI. However, most changes are confined to the CFML code managed by WireBox. To determine what version you have installed, use the version command.

The auto-upgrade commands shown below will not upgrade the main CommandBox Java Binary. If there are any major upgrades to this binary, you will see a message that you will need to download the new Java binary and replace your current one.

Stable

To upgrade to the last stable version of the shell and commands, use the upgrade command.

This command will connect to our server to determine the last stable build. If there is an upgrade, it will be downloaded and installed for you.

Bleeding Edge

To upgrade to the bleeding edge version of the shell and commands, use the latest flag.

This command will connect to our server to determine the latest build. If there is an upgrade, it will be downloaded and installed for you.

Use The Force

If you already have the latest version installed, but you still want to force an upgrade, use the force parameter.

Brute Force

Note, if you delete your {user}/.CommandBox folder and re-run the executable, the version of CommandBox in the executable will be unpacked regardless of any upgrades you may have installed in the mean time. On that note, another way to force an upgrade is to simply download the new executable, wipe the .CommandBox folder in your user directory and re-run. This will also erase any saved command history, embedded servers, or installed user commands.

Mac/ *Unix

If you have used Hombrew to install CommandBox you must use Homebrew for any upgrade, minor or major. To upgrade CommandBox with Homebrew:

Linux Update

(Debian)

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

• - Feb 2016 - Nov 2017

• - June 2015 - Nov 2015

• - Feb 2015

When you run box without any parameters, you get the CommandBox interactive shell. We use a library called JLine for this interaction and it has a number of bash-like behaviors to make you more productive. CommandBox also bundles several bash-like commands to give you a consistent shell regardless of whether you're on Windows or Linux.

Ctrl-C & Ctrl-D

Pressing Ctrl-C will send an interrupt signal to the terminal which will end any currently executing command and exit you back to the shell's prompt. Pressing Ctrl-C if you're already at the prompt won't do anything at all.

Pressing Ctrl-D from a prompt sends an OEF signal and will exit out of the shell entirely, just like if you had run the exit command.

History Search

CommandBox allows you to re-run items from your command and/or REPL history by pressing the up arrow to cycle through previous commands. You can type a partial command like cd and then hit up arrow and the history items will be filtered to items starting with that. You can also use what's commonly known 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 through the results. Press Ctrl-Shift-S to cycle backwards through the results.

Change to Previous Directory

Like Powershell or Bash, you can type the following to switch back to the previous working directory:

If you run this same command more than once, you will keep toggling between the same two directories (bash behavior)

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

• - Dec 2018

• - Nov 2018

• - Oct 2018

• - Aug 2018

• - Jun 2018

• - Jun 2018

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

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

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

• [] - writedump failing in Lucee

Improvement

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

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

• Version 2.2.0 - Nov 2015

• Version 2.1.1 - Aug 2015

• Version 2.1.0 - Aug 2015

• - June 2015

Never miss an update again by installing the CommandBox update check module for ForgeBox. It will check for new versions of the core CommandBox CLI as well as any of your installed system modules once a day when the CLI starts up in interactive mode. Internet connection required.

Since CommandBox is a command line tool, it requires no GUI. If you are using an OS with a GUI (like Windows) and you run the box executable, the CommandBox interactive shell will open in a new window. CommandBox looks and behaves like a Bash or DOS window, but the command prompt is not your native OS-- it's CommandBox running INSIDE your native shell and interpreting what you type.

Interactive Shell

As such, operating system commands won't execute (unless we've implemented a similar one in CommandBox). However, we also have a command called run

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

• - August 2023

• - May 2023

• - April 2023

If you are just installing CommandBox to use on your PC as a local development tool, the standard version of the box binary should be fine. It contains a full version of Lucee with all its default extensions pre-installed. However, if you are creating an automation or a distributable such as a Docker container you may want to look into one of these alternative box binaries.

CommandBox Light

CommandBox Light does not include the full version of Lucee, but rather Lucee Light which only comes with the Compress extension (because CommandBox requires this extension to run). The CommandBox Light binary is roughly half the size of the normal version. The on-disk size of the CommandBox home is about 1/3rd of the size. This can be handy for places where disk size is very important.

Starting a default web server in CommandBox will give you a Lucee Light server, which may not run your app since it lacks extensions such as JBDC drivers and the admin. You can still ask for a specific version of Lucee with the

Bug

• [] - Relative SSL certFile or keyFile path in server.json isn't expanded

• [

Commands

CommandBox uses its own command parser that should be similar to what you're used to in other shells. Commands are not case-sensitive and don't contain any special characters except an occasional dash (-). Each command and its parameters will be entered on a single line. Press enter when you are done typing to execute that command. If you ever need to include a line break in a parameter value, quote the value and use the escape sequence.

For a full list of all the commands that ship with CommandBox as well as all their parameters and samples, please visit our which are auto-generated each build.

You can already execute CFML functions in the REPL command to play in a sandbox, but sometimes you want to go further and actually use CFML directly in the CLI. This is where the cfml command comes in handy. The following runs the now() function. It is the equivalent to repl now().

#function

As a handy shortcut, you can invoke the cfml command by simply typing the name of the CFML function, preceded by a

Here are some common issues starting up CommandBox and troubleshooting help.

Could not load library. Reasons: [no jansi in java.library.path ... Access is denied]

If you have a Windows machine which has been locked down to not allow DLL files in the user's appData folder, you may receive a message similar to this when attempting to start CommandBox.

If you don't have the option of changing the security controls on your PC, then you can try changing your Windows environment variables of TMP

Many commands accept parameters to control how they function. Parameters are entered on the same line as the command and separated by a space and can be provided as named OR positional, similar to how CFML functions can be called. You cannot mix named and positional parameters in the same command though or an error will be thrown. There is also a concept of "flag" for boolean parameters that can be combined with named or positional parameters for brevity and readability.

Named Parameters

Named parameters can be specified in any order and follow the format name=value. Multiple named parameters are separated by a space.

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:

Do you ever get tired of typing some built in commands and you'd like to just alias them as something simpler? You can create arbitrary alises now that reduce the amount of typing you do.

In the above example, it's the same thing as typing coldbox create app myApp.

Aliases are treated as in-place shell expansions so you can alias anything including default parameters as well as multiple commands chained together.

In the above example, typing foobar is the same as running the giant command string that's being set into the alias.

If you create an alias that matches an existing command name, your alias will take precedence since aliases are expanded before commands are resolved.

Here we can change the name of a common command like echo that we really wish had been named print

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

There is a sql command which will accept any sort of data as JSON, marshal 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.

Parameters

• data - The JSON to process

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 powerful construct allows you to perform basic loops from the CLI over arbitrary input. Most of the examples show file listings, but any input can be used that you want to iterate over.

This example will use the echo command to output each filename returned by ls. The echo is called once for every line of output being piped in.

The default command is "echo" but you can perform an action against the incoming list of items. This example will use "cat" to output the contents of each file in the incoming list.

You can customize the delimiter. This example passes a hard-coded input and spits it on commas. So here, the install command is run three times, once for each package. A contrived, but effective example.

If you want a more complex command, you can choose exactly where you wish to use the incoming item by referencing the default system setting expansion of

Help is integrated at every level in CommandBox. You can help global help, namespace help, or command help at any time.

Global Help

To get an overall list of all the commands you have available to run, simply type help at the shell.

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

You can change CommandBox's default tab completion to be an inline list that follows your cursor. This setting requires you to close and re-open the shell to take affect.

Read more here:

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

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

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

Read more here:

Release Notes

Here are the release notes for the 5.2.1 release.

Bug

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

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

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

New Feature

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

• [] - forgebox logout command

Improvement

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

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

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

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

• [] - CommandBox caches .cfm files between executions

• [] - Lucee version leaves tons of old jars on upgrade

• [] - Script repl confused on paranthesis or quotes

New Feature

• [] - Switch CommandBox core to Lucee

• [] - Multi Endpoint support

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

Improvement

• [] - Add a directory argument for the REPL

• [] - REPL's handling of functions that output content

• [] - Optimize JVM Memory Arguments to Prevent PermGen and Java.lang.outOfMemory errors

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:

http://commandbox.ortusbooks.com/content/getting_started_guide.html

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

• [

Improvement

• [] - Improve parameter escaping when running commands from native OS

• [] - Make ColdBox skeleton hints dynamic by reading folder instead of hard-coded values

• [] - Increase the size/resolution of the icon

New Feature

• [] - Additional install endpoints

• [] - Git endpoint

• [] - Update all tray icons to CommandBox latest icons

• [

Many Commands accept a path to a folder or file on your hard drive. You can specify a fully qualified path that starts at your drive root, or a relative path that starts in your current working directory. To find your current working directory, use the pwd command (Print Working Directory). To change your current working directory, use the cd command.

Absolute

Here are examples of fully qualified paths in Windows and *nix-based:

Windows:

Info Note that if you start a path with a single leading slash in Windows, it will be an absolute path using the drive letter of the current working directory.

*nix:

Relative

For a relative path, do not begin with a slash.

File system paths will be canonicalized automatically which means the following is also valid:

UNC Server paths

If you are on Windows, CommandBox supports UNC server shares bu accessing the name of the server or the IP address. Note, you can use forward or backslashes in Windows, but a UNC path MUST start with two backslashes.

Backslashes need to be escaped from the command line and in JSON, so most usage of UNC server paths will require you to type four slashes like \\\\ which will properly escape to \\

You cannot directly list the contents of a server like \\webdev01 as that is not a true directory. You always need to access a specific share like \\webdev01/webroot.

Permissions

By default, CommandBox will access UNC paths using the same permissions of the user that the box process was started with. There's no way to specify a user, so if you need to use a custom user, you'll need to run native NET USE command from the CLI first to change how it is authenticating. Unfortunately, this is a limitation of how Java accesses UNC paths so CommandBox has little control over it.

If a value is a single word with no special characters, you don't need to escape anything. Certain characters are reserved as special characters though for parameters since they demarcate the beginning and end of the actual parameter and you'll need to escape them properly. These rules apply the same to named and positional parameters.

Spaces

If a parameter has any white space in it, you'll need to wrap the value in single or double quotes. It doesn't matter which kind you use and it can vary from one parameter to another as long as they match properly.

Quotes

Quotes are actually allowed unescaped in a value, so long as they don't appear at the start of the string.

However, if the parameter contains white space and is surrounded by quotes, you'll need to escape them with a backslash.

Hint Only like quotes need to be escaped. Single quotes can exist inside of double and vice versa without issue. These examples below are perfectly valid.

Backticks

Backticks are used in parameter values to demarcate an expression to be parsed. Escape them with a backslash. All backticks need escaped regardless of whether they are encased on single or double quotes.

Equals Signs

If you have an equals sign in your value, you'll need to escape it with a backslash unless you've quoted the entire string.

Line Breaks

Line breaks can't be escaped directly as of Commandbox 4.0. Instead, most terminals let you enter a carriage return by pressing Ctrl-V and pressing enter. To enter a line feed, press Ctrl-V followed by Ctrl-J.

On ConEMU, which performs a paste operation with Ctrl-V, use Ctrl-Shift-V instead.

Tabs

A tab character can't be escaped directly as of CommandBox 4.0. Instead, most terminals let you enter a tab char by pressing Ctrl-V followed by tab. In ConEMU which allows pasting via Ctrl-V, you can use Ctrl-Shift-V and then press tab.

Backslash

Since the backslash is used as our escape character you'll need to escape any legitimate backslash that happens to precede a single quote, double quote, equals sign, or letter n.

This will print foo\=bar

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

• - Mar 2017

• - Jan 2017

• - Nov 2016

• - Oct 2016

• - Jul 2016

• - Jul 2016

• - Feb 2016

• - Feb 2016

The CommandBox interactive shell already allows for a command to pipe data into another Command.

cat myfile.txt | grep "find me"

Since CommandBox commands don't have a "standard input", the output of the previous command is passed into the second command as its first parameter. In this instance, the grep command's first parameter is called input so it receives the value returned by the cat command. The "find me" text becomes the second parameter-- in this case, expression.

Examples

There is nothing special about a parameter that can received piped input. In fact, any command can receive piped input for its first parameter. The following commands all accomplish the same thing.

This allows you to get creative by combining commands together like so:

This takes a package name and replaces some text on output. One benefit is that Windows users don't have a native sed command in their OS, but those commands inside a CommandBox Recipe will execute consistently on any machine.

Piping From The OS

What if you aren't using the interactive shell and you want to pipe into CommandBox from your OS's native shell? This is also supported, and as long as there is a command specified, the piped input will become the first parameter as before.

If you pipe text directly into the box executable with no command specified in the parameters, each line of your piped text will be read from the standard input as a command.

CommandBox has support for 256 colors in the console, but this is limited by the terminal in use. For instance, SSHing into a Linux server with PutTTY only supports 8 colors. Windows cmd only supports 16 colors. Most Mac terminals seem to support 256 colors by default.

For Windows users, we recommend using an add-on terminal like ConEMU which has good 256 color support out of the box. To find out how many colors your terminal supports, you can run this command:

system-colors

This will show you at the top how many colors are supported. It will also output a sample of each of the 256 colors. Terminals that support less than 256 colors will "round" down and show the next closest color automatically. Some darker colors might turn to black. Note, some advanced terminals allow the user to choose color themes which will also change the default colors. CommandBox has no control over how colors show up for you.

Color Names

The names and numbers of each color are unique and important if you want to do any Task Runners, custom commands that make use of these colors. Modules like Bullet Train also allow you to customize their colors. You can specify a color by its name like LightGoldenrod5 or its number (221).

In a Task Runner or custom command, the print helper would look like this:

Here's an example of customizing your Bullet Train module to use fancy colors. (Color 21 is Blue1)

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.

Release Highlights

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

• Updated CLI engine (and default server) version to

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 not recognizing implicit folder endpoint

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.

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.

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

CommandBox contains a REPL command which is a powerful tool to execute ad-hoc CFML code from the command line. A REPL reads user input, evaluates it, prints the result, and then repeats the process. The CommandBox REPL supports the inline execution of both CF script or tags.

Script REPL

The default mode of the REPL command is to accept script. You can enter most any CF Script into the prompt for execution. If the script is an expression that returns a value, or sets a variable, that value/variable will be output. Variables that you set will be available to you until you exit the REPL command.

CommandBox has a helper for printing ASCII Art tables in your custom commands and task runners called print.table(). We've taken this a step further and wrapped the table printer utility in a new command so you can use it from the CLI directly. The printTable command will accept ANY data in as JSON and it will marshal 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.

Parameters

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

The following environment variables will be available to your command

• watcher_added - A JSON array of relative paths added in the watch directory

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

This module will customize your CommandBox prompt while in the interactive shell. It has multiple "cars" that are part of the train and each car can contribute some output to the prompt that is working directory-aware.

THIS MODULE REQUIRES COMMANDBOX 4.0.0!

This project is based on the Zsh Bullet Train theme which is based on the Powerline shell prompt. The goal is to add in additional information to your prompt that is specific to the current working directory, or the last command you ran.

Installation

If you already have a Java JRE installed level 1.8 or higher (and set in your environment variables) you can the non-JRE version for your Operating System. If you don't have a JRE installed or aren't sure, we would recommend you the version with a JRE included. Below you will find the way to get the latest stable and bleeding edge releases. Please also note that in our page you will find much more detail information on how to install CommandBox with modern Operating System package managers as well.

Info The non-JRE versions are all around 80MB in size, while the embedded JRE versions will go up to 120MB in size.

Below you can see an image of the available downloads from the Ortus Solutions page:

One common question is how to access the database from one of these scripts. Your code is executed on Lucee Server (version 4.5 at the time of this writing) which is the version of Lucee that the core CLI runs on. The CLI has the full power of a Lucee server running under the covers, but there's no web-based administrator for you to acess to do things like adding datasources for your scripts to use. It would considered poor form anyway since standalone scripts are best if they're self-contained and don't have external dependencies like server settings necessary to run.

Lucee allows datasource to be a struct

So the easiest way to accomplish this is simply to exploit a little known but very cool feature of Lucee that allows the datasource attribute of most tags to be not only a string which contains the name of the datasource, but also a struct that contains the _definition_ of the datasource. This will create an on-the-fly connection to your database without any server config being necessary which is perfect for a stand-alone script. Here is what that looks like. Note, I'm using queryExecute(), but it would work just as well in a cfquery tag.

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.

Any valid command can be used as an expression, including calls to native OS binaries, CFML functions, or REPL one-liners. Note that any text that a command immediately flushes to the console during its execution (like a download progress bar) will not be returned by the expression, though it will display on the console.

Entire Parameter

Take for instance, this simple command that prints out the contents of a file:

It can be used as a dynamic parameter like so:

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

update coldbox resources to support api resources

artifacts prune command

Bug

Use user.home instead of user.dir to test case sensitivity

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

ModCFML doesn't save actual Lucee webConfigDir

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

Two servers get same name when moving folder

Can't pass Windows drive letter to "open" command

Error passing empty version to "java search" command

Interactive job logs don't obey terminal width config setting

REPL errors when representing some Java objects

recipe file validation fails

Java integration doesn't recognize ARM CPUs

coldbox resources command failing on relative models directory not found

Improvement

make "upgrade" command handle new jars

Support pfx format for server certs

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

REPL obey verboseErrors config setting

cfpm doesn't find Adobe server with different web root

Make client cert CGI vars available immediately after SSL renegotiation

Add --json to artifacts list

Touch artifacts on use so we can prune unused ones easier

Update coldbox resources command to latest version

Task

Update bundled JRE to 11.0.17+8

Update Undertow lib in Runwar

Update json-smart-mini and Lucee libs

Here's an overview of the notable changes in this release.

Install Lucee core/lex files

The install command will automatically find a local Lucee Server when installing a package that is a Lex file. There is also now a command called server lucee-deploy to help with installing Lex files (Lucee Extensions) and LCO files (Lucee Core).

It will accept an absolute or relative local file path:

or an HTTP URL to download

You can also override the name of the CommandBox server to install into, regardless of what working directory the shell is in:

The command will copy the lex or lco file to the deploy folder of the chosen Lucee server

More info here:

Package Management binary hash verification

CommandBox now has the capability to verify the MD5 hash of a binary upon installation. When publishing packages to ForgeBox using ForgeBox's built-in S3 storage, the binary hash will be auto-calculated and stored in ForgeBox along with the package details and automatically checked on every future download.

More info here:

WebSocket Support

CommandBox supports WebSockets natively via our . The WebSocket server in CommandBox is not really a separate "server" per se, since it’s on the same port. It’s just an upgrade listener which will upgrade any WS requests.

This websocket integration will work for Lucee, Adobe, and BoxLang alike as it passes incoming messages to the app via an "internal" HTTP request to /WebSocket.cfc?method=onProcess where the CF/BL code can handle it. The incoming request will have all cookies, headers, hostname, etc that the original websocket connection was started with, so normal CGI variables and session scopes should work fine.

You need to create a custom /WebSocket.cfc class should extend one of the classes described below in this library which provides the base functionality.

More info here:

And here:

Library Updates

We've bumped the versions of several internal libraries including

• Lucee (5.4.6.9)

• JBoss Undertow (2.2.37.Final)

• Bundled JRE (11.0.25+9)

Release Notes

Here is the full list of tickets closed in the 6.1.0 release.

New Feature

Updates to run BoxLang

Add command to deploy Lucee lex or lco files

Check if an entry has a hash associated to it and validate it

Create a hash of the binary when storing the zip and return it to ForgeBox

WebSocket Server

Improvement

Sort by date last started when finding a server by web root

Make semantic version prerelease identifiers not case sensitive

default servlet pass predicate include Boxlang files

Bug

Legacy SSL config doesn't respect enable = false

Static web server no longer works

second level dependencies inside of a top level dependency's box.json always install latest stable version

"Java search" returns no results

framework rewrites double-encode path info

CommandBox 6 not putting trailing slashes in URL

SES paths return false from is-file predicate for value files with a path info

backslash in JSON object keys not escaped when printing JSON

forgebox version-debug errors

Task

Update to Undertow 2.2.33.Final

Update to Lucee 5.4.6.9

Update bundled JRE to 11.0.23+9

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.

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.

New "coldbox watch-reinit" command

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

Color all the JSONs

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

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

• json.ansiColors.constant

• json.ansiColors.key

• json.ansiColors.number

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

New Gist endpoint

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

4.4.0 Release Notes

Bug

• [] - testbox watcher shows error when test fail

• [] - Tab complete doesn't work on param values with spaces

• [] - Long lines wrap in interactive jobs

New Feature

• [] - Allow watcher access to files that were added, removed, updated

• [] - coldbox watch-reinit command

• [] - Color code JSON on console output by default

Improvement

• [] - Refresh any salt values when deploying a new CF engine.

• [] - Add Gist endpoint

• [] - Change update behavior of GIT and URL endpoints to use semver in path if present

CommandBox follows the standard system of exit codes. In Bash or DOS, every process has an exit code that is available to the shell after execution is complete. The are as follows:

• 0 - Success

• Any other number - Failure

This slightly counterintuitive to CFML developers since we are used to positive numbers as being truthy and zero as being falsely, but it is the industry standard for shells. It makes more sense if you think of it in terms of what Windows calls it-- %errorlevel%. if the error level is 0 there was no error!

Command Exit Codes

Every command that executes has an exit code. Usually the exit code is 0 if the command ran as expected. If an error of any kind was encountered, then the exit code will be a non-zero number. Often times 1. You can easily see this if you install the module as it shows you the exit code of the last command to run. Commands such as testbox run will return a failing exit code if the tests being run didn't all pass.

You can access the last exit code from CommandBox in a called exitCode.

Shell Exit Code

The CommandBox shell also keeps track of exit code of the last command. When the shell exits, it will report that last exit code to the OS. When running a one-off command from your native shell, the exit code of that command will be passed straight through to your native shell. This means that running something like

from a Travis-CI build will automatically fail the build if the tests don't pass.

Manual Exit Code

You can manually return an exit code from the shell passing the desired number to the exit command and the native OS will receive that code from the box binary.

Command Chaining

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 semi colon (;) to separate commands and each command will run regardless of the success or failure of the previous command.

Chaining Commands

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:

Assertions

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. In this example, we only run the package show command if the box.json file 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

assertFalse

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

assertEqual

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

assertNotEqual

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

Cached HTTP Downloads

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

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:

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

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!

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.

Release Notes

Here are the full release notes for CommandBox 4.8.0:

Bug

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

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

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

New Feature

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

• [] - Output binary objects in REPL

• [] - Add support for "cd -"

Improvement

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

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

• [] - Expand log output of failed job steps

Release Notes

Bug

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

• [] - List artifacts alphabetically.

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

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

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

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

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

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

New Feature

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

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

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

Improvement

• [] - Enforce correct casing conventions on scaffolding commands

• [] - Update propertyFile core module

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

In the past, 99% of people used the Oracle (previously SUN) version of Java for all their Java needs. As of January 2019, the license is changing on Oracle Java which makes it no longer free for commercial use as well as the end of updates for Java 8. This has led to many people looking at alternatives to Oracle. Java itself is open source, so it will always be free and there are several other organizations offering their own builds of Java. If you want support, it matters which provider you get Java from.

This page is a work in progress to track the non-Oracle JREs and how to use them. Please send pull requests to this page with any additional information you have as this is a changing landscape right now.

You can read more about Oracle's changes in this post:

Amazon Corretto

Corretto is a build of OpenJDK maintained by Amazon. It is free and will have long term support. Initial tests show that Corretto 1.8 works with CommandBox and ACF 11.

OpenJDK

OpenJDK is Oracle's free version of Java. it comes with a 6 month support window. CommandBox has received a fair amount of testing on OpenJDK and everything seems to work.

Azul Zulu

Zulu is free and offers long term support. Zulu provides supported builds of OpenJDK. Initial tests show that Corretto 1.8 works with CommandBox and ACF 11.

Installing on Windows

When running box.exe on Windows, the registry is used to determine the current versions of java that are installed. If you install a some non-Oracle JRE such as Corretto, you will not currently have the necessary registry entries created for box to find Java.

• Oracle - No manual action needed

• Azul - No manual action needed

• OpenJDK - Manual creation of registry keys required

• Corretto

You can manually create the needed keys by modifying and running the following registry entries. (Contributed by Jim Pickering)

Installing on *nix

The box binary on *nix uses your OS environment variables to locate Java. In the absence of an env var called JAVA_HOME, box will look for java in the default system path.

• Oracle - No manual action needed

• Azul - No manual action needed

• OpenJDK - Manual creation of JAVA_HOME required

To manually configure the JAVA_HOME env var on a *nix system, edit your /etc/profile file to have these lines. Adjust the path as necessary based on your installation.

The JRE Folder

And as always, on any operating system and with any JRE provider, you can override what version of java is used by creating a folder called JRE in the same directory as the box or box.exe binary that contains the JRE you wish CommandBox to use. This will bypass all registry and env var checks above.

For macOS users who have installed CommandBox via HomeBrew, the installer creates a box alias in /usr/local/bin/ which points to the box binary in the /usr/local/Cellar/commandbox/<version>/bin/ directory. If you want CommandBox to use a particular version of the JRE then put the jre folder in the /usr/local/bin/ directory. If you want CommandBox to have , place your commandbox.properties file in the /usr/local/Cellar/commandbox/<version>/bin/libexec/bin/ directory.

If you want to debug what JRE is being used by the CommandBox CLI, use the -clidebug flag when starting CommandBox and the first few lines will tell you what version of Java is being used, and where on disk it lives.

The main features of CommandBox 4.5.0 are:

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

• Environment Variables in the shell ()

• Support for Forgebox Enterprise (TBA soon)

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!

If you want to execute a native binary from inside the interactive shell or as part of a CommandBox recipe, we allow this via the run command. You can read the API docs for run .

Hint This behavior is dependent on your operating system.

Now that we're starting to use CommandBox in a lot of cloud scenarios like Docker, we're looking for more and more ways to have dynamic configuration. The most common way to do this is via Java system properties and environment variables. We've wrapped up those two into a new concept called System Settings. Now any time you use ${mySetting} in a command parameter, a box.json property, server.json property, or a Config Setting, that place holder will be replaced with a matching JVM property or env var (in that order) at runtime. This is great for setting things like ports, default directories, or passwords and other secrets as an env variable so it can be different per server and not part of your code.

CommandBox allows you to access Java System Properties from the CLI and environment variables from your operating system via the ${name_here} mechanism. But CommandBox also gives you the ability to create variables of your own directly in the shell. The scope (life) of these environment variables depends on how and where they are declared.

Shell Environment Variables (Global)

Every shell instance has its own set of environment variables you can set and read. These live for the duration of the shell and have the same lifespan as Java system properties in the CLI. There is an env namespace of commands for dealing with environment variables.

One of the most productive features of the shell is tab completion. This means you can type a partial command and hit the tab key on your keyboard to be prompted with suggestions that match what you've typed so far. If there is only one match, it will be finished for you. This can save a lot of typing and will be a familiar concept to those already living in a CLI environment.

When "tab" is pressed, the text you've entered so far is run through the CommandBox command parser to see if it can match a namespace, command, or parameters. If you press tab at an empty prompt, all top level commands and namespaces will display. Since tab completion is run through the standard command parser, that means it works on command aliases as well.

The tab completion options are broken up into groups to visualize the commands, parameters, flags, etc. As you type, the list of available options will auto-filter for you. You can keep hitting tab to toggle through the available options and you can press enter to select the one you want.