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.

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.

Regardless of where you place the box binary, the first time you execute it, a .CommandBox folder will be created in your user's home directory and CommandBox will be extracted into that location. If you delete this directory, it will be replaced the next time the CommandBox executable is run.

You can specify a different install location by adding -commandbox_home=E:\CommandBox when you run the box binary.

To avoid specifying the commandbox_home variable every time you can create a file called commandbox.properties (case sensitive) in the same directory as the binary, and fill it with this line:

commandbox_home=E:\\CommandBox

The CommandBox home can also be a path relative to the location of the commandbox.properties file.

commandbox_home=../boxHome

Windows

Extract the executable box.exe from the downloaded zip file, placing it anywhere you prefer where you can then execute it when needed, such as from the Windows command line/terminal. You can also run it directly Windows File Explorer, where you would just double click on the exe,which will open the CommandBox shell in a new terminal window.

Warning On Windows 10 and above, the first time you try to run via Windows File Explorer an exe that you've downloaded, Windows Defender Smartscreen will popup with a warning that "Windows protected your PC". You will need to choose the offered "More info" link and then the offered "Run anyway" button, to proceed.

Hint When running from the Windows command line/terminal, you can make it so that you can run box.exe while you are in any folder (not just the one where you placed it), by simply adding the exe's location to the Windows PATH system environment variable. See http://www.computerhope.com/issues/ch000549.htm

When you are finished running commands in the CommandBox shell, type exit. Or if you ran the box.exe from within Windows File Explorer, you can just close the terminal window which that opened.

Mac/ *Unix

Homebrew (Mac)

Homebrew is a great Mac package manager, it can easily install and keep your CommandBox installation up to date (even binary releases), just run the following for stable releases:

brew install commandbox

To stay with current bleeding edge releases use the following:

brew tap ortus-solutions/homebrew-boxtap
brew install --head ortus-solutions/homebrew-boxtap/commandbox

Then run the box binary to begin the one-time unpacking process.

Versions will be installed in /opt/homebrew/Cellar/commandbox. To switch between versions, you will need to install the new version - either using the bleeding edge tap or the main repo. For example to switch to a (very) old version:

brew install [email protected]
brew unlink commandbox
brew link [email protected]

If you are using a tap, and want to revert back to the current stable version

brew uninstall ortus-solutions/homebrew-boxtap/commandbox
brew install commandbox

If you want to use a commandbox.properties file as mentioned above, even though the symlink is added in /usr/local/bin, your box binary file will be in the /opt/homebrew/Cellar/commandbox/<version>/libexec/bin/ directory where you should place your commandbox.properties file. There will also be a box binary in the /opt/homebrew/Cellar/commandbox/<version>/bin/ directory where you should place the jre if you want CommandBox to use a version of Java that is different from your default version reported by java -version.

When using Homebrew to install CommandBox you must use Homebrew for any upgrade, minor or major. To upgrade CommandBox with Homebrew:

brew upgrade commandbox

NOTE: If you use Homebrew to upgrade your version of CommandBox it will erase your /opt/homebrew/Cellar/commandbox/<current_version>/ folder. So before upgrading, take a copy of your /opt/homebrew/Cellar/commandbox/<current_version>/libexec/bin/commandbox.properties file to drop back into /opt/homebrew/Cellar/commandbox/<new_version>/libexec/bin/ before running box for the first time after upgrading.

Manual Installation

Unzip the binary box and just double click on it to open the shell terminal. When you are finished running commands, you can just close the window, or type exit.

Hint You can place the binary in your /usr/local/bin directory so it can be available system-wide via the box command in any terminal window.

Linux apt-get

Please note that if you are running Ubuntu 18.04 or greater, or Debian 8 (Jessie) or greater, it's necessary to have the libappindicator-dev package in order to have the tray icon working correctly.

sudo apt install libappindicator-dev

Run the following series of commands to add the Ortus signing key, register our Debian repo, and install CommandBox.

Stable

( This first install routine also works for the Raspberry Pi. )

curl -fsSl https://downloads.ortussolutions.com/debs/gpg | gpg --dearmor | sudo tee /usr/share/keyrings/ortussolutions.gpg > /dev/null

echo "deb [signed-by=/usr/share/keyrings/ortussolutions.gpg] https://downloads.ortussolutions.com/debs/noarch /" | sudo tee /etc/apt/sources.list.d/commandbox.list

sudo apt-get update && sudo apt-get install apt-transport-https commandbox

If you do not have Java installed you can install it with the following command.

sudo apt install openjdk-11-jdk

Then run the box binary to begin the one-time unpacking process.

Linux yum

Stable

Add the following to: /etc/yum.repos.d/commandbox.repo

[CommandBox]
name=CommandBox $releasever - $basearch
baseurl=https://downloads.ortussolutions.com/RPMS/noarch
enabled=1
metadata_expire=7d
gpgcheck=0

Then run:

sudo yum update
sudo yum install commandbox

Debian Linux manual install

After you have downloaded the commandbox.deb file, install it using the dpkg command.

sudo dpkg -i commandbox-debian-1.2.3.deb

Run the box binary to begin the one-time unpacking process.

Redhat Linux manual install

After you have downloaded the commandbox.rpm file, install it using the rpm command.

rpm -ivh commandbox-rpm-1.2.3.rpm

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.

box version

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.

box upgrade

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.

box upgrade --latest

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.

upgrade --force
upgrade --latest --force

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:

brew upgrade commandbox

Linux Update

(Debian)

> sudo apt update

> sudo apt upgrade commandbox

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 cfengine parameter. If you delete the engine folder from a CommandBox Light installation, Lucee will not be able to work since the Lucee.jar file in CommandBox Light has had it's core.lco file removed to make it smaller. Deleting the entire .CommandBox folder will work however.

Any Task Runners or CLI automations in CommandBox light will also not be able to use things like JDBC drivers unless you install the extensions. Extensions can be installed by placing them in the CLI's server context deploy folder and waiting a minute:

~/.CommandBox/engine/cfml/cli/lucee-server/deploy

You can download the CommandBox Light binary directly from our S3 artifacts repo:

• box-light - Mac/Linux

• box-light.exe - Windows

• box-light.jar - Executable jar

CommandBox Thin

The CommandBox Thin binary cannot be used by itself as it contains nothing inside of it but the Java bootstrap. It does not contain any of the other libraries, jars, or Lucee versions that CommandBox needs to load. it is only 300KB in size. The way that the 'thin" binary is to be used is to first download and run the normal CommandBox or CommandBox Light binary which will extract itself into the CommandBox Home. Once this has been completed, you can delete that box binary and replace it with the box-thin binary (renamed to box ). The new thin binary will take up less disk space and will simply use the existing CommandBox home that has been extracted.

The thin binary does not care whether the CommandBox home was extracted with a full or "light" version. This can create additional disk savings in an environment like Docker, but would not serve much of a purpose on your local development PC. If you delete your .CommandBox folder, the CommandBox thin binary will not be able to recreate it.

You can download the CommandBox Light binary directly from our S3 artifacts repo:

• box-thin - Mac/Linux

• box-thin.exe - Windows

• box-thin.jar - Executable jar

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 and TEMP to repoint to another folder which does not have this restriction.

/usr/bin/box: 87: exec: java: not found

If you receive a message like the one above, which was taken from a Linux machine, when starting CommandBox, this means that you do not have Java installed. You can solve this in three ways: 1. Download the JRE-included CommandBox install which comes with a folder called jre 2. Download your own jre and place it in a folder called jre in the same folder as the box binary. 3. install Java onto your machine and ensure the correct JAVA_HOME and JRE_HOME environment variables are set.

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 - Manual creation of registry keys required

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

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft]

[HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Development Kit]
"CurrentVersion"="8.0.192"

[HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Development Kit\8.0.192]
"JavaHome"="C:\\Program Files\\Amazon Corretto\\jre8"
"RuntimeLib"="C:\\Program Files\\Amazon Corretto\\jre8\\bin\\server\\jvm.dll"

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

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

export JAVA_HOME=/opt/ibm/java-x86_64-60/
export PATH=$JAVA_HOME/bin:$PATH

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 a different home .CommandBox directory, 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.

If you already have a Java JRE installed level 1.8 or higher (and set in your environment variables) you can download the non-JRE version for your Operating System. If you don't have a JRE installed or aren't sure, we would recommend you download 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 installation 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 download page:

Stable Release

Stable versions of CommandBox can be downloaded from the downloads section of our product page. http://www.ortussolutions.com/products/commandbox#download

Bleeding Edge

We use a Jenkins integration server to automate our builds. You can download a bleeding-edge version of CommandBox directly from our integration server here: https://downloads.ortussolutions.com/#/ortussolutions/commandbox/

Info Keep in mind, bleeding edge builds may contain experimental features that are likely to change or bugs.

Auto Updates

Another way to get the bleeding edge version of CommandBox is to install the stable version and run our upgrade command using the latest flag. Upgrade API docs.

upgrade --latest

Info Please note that the upgrade command will not update the main CommandBox binary. If there are major updates or you get a message about updating the binary, you will need to download the latest binary and re-install it.