Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Here are some common issues starting up CommandBox and troubleshooting help.
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.
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.
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.
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.
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.
If you already have the latest version installed, but you still want to force an upgrade, use the force parameter.
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.
If you have used Hombrew to install CommandBox you must use Homebrew for any upgrade, minor or major. To upgrade CommandBox with Homebrew:
(Debian)
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.
Windows XP+
Mac OS
Linux
256MB+ RAM
250MB+ free hard drive space
Multi-core CPU recommended
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.
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 versions of CommandBox can be downloaded from the downloads section of our product page. http://www.ortussolutions.com/products/commandbox#download
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.
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.
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.
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:
The CommandBox home can also be a path relative to the location of the commandbox.properties file.
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.exewhile you are in any folder (not just the one where you placed it), by simply adding the exe's location to the WindowsPATHsystem environment variable. See
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.
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:
To stay with current bleeding edge releases use the following:
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:
If you are using a tap, and want to revert back to the current stable version
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:
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.
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/bindirectory so it can be available system-wide via theboxcommand in any terminal window.
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-devpackage in order to have the tray icon working correctly.
Run the following series of commands to add the Ortus signing key, register our Debian repo, and install CommandBox.
( This first install routine also works for the Raspberry Pi. )
If you do not have Java installed you can install it with the following command.
Then run the box binary to begin the one-time unpacking process.
Add the following to: /etc/yum.repos.d/commandbox.repo
Then run:
After you have downloaded the commandbox.deb file, install it using the dpkg command.
Run the box binary to begin the one-time unpacking process.
After you have downloaded the commandbox.rpm file, install it using the rpm 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:
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 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.
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.
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)
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.
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.
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 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 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:
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
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
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.
