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.

Congratulations on your choice of CommandBox, the next generation of CFML productivity tooling! We're pleased you've chosen this product and we can't wait to help you get started with it. Setup is easy and painless. We'll walk you through the steps you need to become the jealous rage of your peers with the class of a Java guru, the hipster appeal of a Rubyist, and the ASCII art fetish of a Node.js developer.

Your CommandBox download was quality checked and shipped from our integration server with the following items. You'll want to check the contents of the package to ensure you received everthing.

• CLI

• Package Manager

• Embedded CFML Server

• REPL

• Built-in Help

• ASCII Art

1. Download

If you don't already have CommandBox in hand, download it from the product page on the Ortus Solutions site:

• http://www.ortussolutions.com/products/commandbox

If you already have Java 1.8 or higher installed on your PC, choose the No JRE Included download for your operating system. Otherwise, you can grab the With JRE Included for a single-download solution.

You're well on your way now. While you wait for arrival you might want to secure any loose hair or shirt sleeves and clear a clean space to work on your desktop. Safety first!

2. Unzip & First Run

Your CommandBox is sent to you via a zip archive. Decompress the archive to a location of your choice. The No JRE Included download will only have one file in it named box. For Windows users, this will be an exe file. For unix-based users, it will be an executable binary. The With JRE Included version will have a jre folder. You can move box.exe, but keep the jre folder in the same relative location as the executable so it can be found.

Now just double click the file from your GUI, or execute it via a console window. This will start a short, quick, one-time process of unpacking CommandBox into your user's home directory. Congratulations, CommandBox is now installed! You'll still run the same executable binary every time you want to use the CLI, but the extraction process won't need to happen again.

The green CommandBox> prompt is what we call the interactive shell. Type exit to close the window or be returned to your OS's native shell.

3. Setup & Usage

To open up the interactive shell at any time, just double click on the box executable. If you prefer to stay in your OS's native shell, then just place the box file in your system path and add it before any CommandBox commands like so:

C:\ > box version
CommandBox 1.2.3.00000
C:\ > _

The rest of this guide, however, will assume you're sitting at the interactive shell, where you can enjoy cross-platform command consistency, custom history, and tab completion.

The first command you'll want to try out is help. Type it after a command, or even a partial command to get context-specific assistance. Check out the help for the version command and then run it to see what you get.

CommandBox> version help

Now, let's see if your installation is up to date with the upgrade command:

CommandBox> upgrade

Looking good. Let's try a bit of CFML code from the REPL, shall we? Type the repl command to be dropped into the REPL prompt.

CommandBox> repl
Enter any valid CFML code in the following prompt in order to evaluate it and print out any results (if any)
Type 'quit' or 'q' to exit!
CFSCRIPT-REPL: _

Type these lines one at a time and press enter to see what you get.

fruits = [ 'apples', 'oranges' ]
fruits.append( 'bananas' )

( fruits.len() ? 'Start eating!' : 'Time to run to the store' )

for( fruit in fruits ) {
  echo( fruit & chr(10) )
}

When you're done, just type quit to exit the REPL. How does it feel to master CFML from the command line?

Package Manager

It's about time we did something useful. CommandBox allows you to install stuff and it makes it really easy. You now have ForgeBox on speed dial. Let's create a little playground to experiment in. Adjust these paths accordingly for Unix-based OS's.

CommandBox> mkdir C:\playground
CommandBox> cd C:\playground

I wonder how many projects Luis Majano has posted on ForgeBox. We can look with the forgebox search command: Hint, try pressing tab while typing a command for auto-completion.

CommandBox> forgebox search Luis

Wow, that Luis guy is busy! Let's install the the ColdBox MVC Platform. Don't worry, this won't hurt a bit.

CommandBox> install coldbox

We can create a skeleton ColdBox app really easy with the ColdBox generator commands. Let's give them a try:

CommandBox> coldbox create app MyApp

Embedded Server

Now that we have a nifty little test app, let's give it a spin. Wait, you don't need to install a CF server, CommandBox has one built in! You can start up an ad-hoc server in any folder on your hard drive simply by typing start. It really couldn't be any simpler.

CommandBox> start

In a few seconds, a browser window will appear with your running application. This is a full server with access to the web administrator where you can add data sources, mappings, or adjust the server settings. Notice the handy icon added to your system tray as well. You can even edit the files in your new site from the command line:

CommandBox> edit views/main/index.cfm

When you're done playing, just shutdown your server with the stop command. It will save all of its settings for the next time you start it. Feel free to delete the playground directory at any time. It won't break a thing.

CommandBox> stop
CommandBox> cd ../
CommandBox> rm playground --recurse --force

Next Steps

You're well on your way to becoming a more productive you. Experiment with CommandBox to see what else you can do with it. This rest of this documentation book is a good place to start. Also, we have full documentation of every command in our Command API Docs.

If you run into issues or just have questions, please jump on our CommandBox Google Group and ask away.

CommandBox is Professional Open Source under the LGPL license. We'd love to have your help with the product. Commands are actually implemented in CFML which means you can write your own and share them on ForgeBox. See if you can figure out how to find and install the "Chuck Norris" or "Image To ASCII" commands. Also, the snake game is a good way to cure boredom. These should give you some ideas of how you can contribute.

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.

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

Windows

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

Hint You can make the box.exe available in any Windows terminal by adding its location to the PATH system environment variable. See http://www.computerhope.com/issues/ch000549.htm

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/boxtap
brew install --devel ortus-solutions/boxtap/commandbox

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

Versions will be installed in /usr/local/Cellar/commandbox. To switch between versions, simply use brew switch commandbox [version number]

If you want to use a commandbox.properties file as mentioned above, your box binary file will be in the /usr/local/Cellar/commandbox/<version>/bin/ directory where you should place your commandbox.properties file. There will also be a box alias in the /usr/local/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 commandbox.properties file.

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

curl -fsSl https://downloads.ortussolutions.com/debs/gpg | sudo apt-key add -
echo "deb https://downloads.ortussolutions.com/debs/noarch /" | sudo tee -a /etc/apt/sources.list.d/commandbox.list
sudo apt-get update && sudo apt-get install apt-transport-https commandbox

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
failovermethod=priority
baseurl=http://downloads.ortussolutions.com/RPMS/noarch
enabled=1
metadata_expire=7d
gpgcheck=0

Then run:

sudo yum update && 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

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.

Could not load library. Reasons: [no jansi in java.library.path, C:\Users\some.user\AppData\Local\Temp\1\jansi-64-9170657940034638384.dll: Access is denied]
        at org.fusesource.hawtjni.runtime.Library.doLoad(Library.java:182):182
        at org.fusesource.hawtjni.runtime.Library.load(Library.java:140):140
        at org.fusesource.jansi.internal.CLibrary.<clinit>(CLibrary.java:42):42
        at org.fusesource.jansi.AnsiConsole.wrapOutputStream(AnsiConsole.java:48):48
        at org.fusesource.jansi.AnsiConsole.<clinit>(AnsiConsole.java:38):38
        at jline.AnsiWindowsTerminal.detectAnsiSupport(AnsiWindowsTerminal.java:57):57
        at jline.AnsiWindowsTerminal.<init>(AnsiWindowsTerminal.java:27):27
        at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method):-2
        at sun.reflect.NativeConstructorAccessorImpl.newInstance(Unknown Source):-1
        at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(Unknown Source):-1
        at java.lang.reflect.Constructor.newInstance(Unknown Source):-1
        at java.lang.Class.newInstance(Unknown Source):-1
        at jline.TerminalFactory.getFlavor(TerminalFactory.java:211):211
        at jline.TerminalFactory.create(TerminalFactory.java:102):102
        at jline.TerminalFactory.get(TerminalFactory.java:186):186
        at jline.TerminalFactory.get(TerminalFactory.java:192):192
        at jline.console.ConsoleReader.<init>(ConsoleReader.java:243):243
        at jline.console.ConsoleReader.<init>(ConsoleReader.java:235):235
        at jline.console.ConsoleReader.<init>(ConsoleReader.java:227):227
        at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method):-2
        at sun.reflect.NativeConstructorAccessorImpl.newInstance(Unknown Source):-1
        at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(Unknown Source):-1
        at java.lang.reflect.Constructor.newInstance(Unknown Source):-1
        at lucee.runtime.reflection.pairs.ConstructorInstance.invoke(ConstructorInstance.java:52):52
        at lucee.runtime.reflection.Reflector.callConstructor(Reflector.java:809):809
        at lucee.runtime.java.JavaObject.init(JavaObject.java:295):295
        at lucee.runtime.java.JavaObject.call(JavaObject.java:222):222
        at lucee.runtime.java.JavaObject.call(JavaObject.java:259):259
        at lucee.runtime.util.VariableUtilImpl.callFunctionWithoutNamedValues(VariableUtilImpl.java:743):743
        at lucee.runtime.PageContextImpl.getFunction(PageContextImpl.java:1599):1599
        at system.util.readerfactory_cfc$cf.udfCall(/commandbox/system/util/ReaderFactory.cfc:38):38

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.

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!)

• He has a geek love for circuits, microcontrollers and overall embedded systems.

• He has of late (during old age) become a fan of running and bike riding with his family.

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 MidAmerica Nazarene University (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 for 12+ years 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 (http://www.codersrevolution.com) and likes to work on solder-at-home digital and analog circuits with his daughter as well as building projects with Arduino-based microcontrollers.

Brad's CommandBox Snake high score is 141.

Contributors

• Jorge Reyes - ColdBox Aficionado

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

There are two ways to run commands via CommandBox: inside the CommandBox interactive shell, or one-at-a-time commands from your native shell.

Multiple Commands

If you open the interactive shell, you will see the CommandBox splash screen (ASCII art) and then you'll be presented with the CommandBox> prompt. You can enter as many commands as you wish in order and after each command is finished executing, you will be returned to the CommandBox prompt. If you have multiple commands you want to execute manually, this is the fastest method since CommandBox only loads once. This is also the only way to make use of features like tab complete and command history.

This example show running the box.exe executable from a Windows DOS prompt, executing the version, pwd, and echo commands, and then exiting back to DOS.

C:\>box.exe

   _____                                          _ ____            
  / ____|                                        | |  _ \           
 | |     ___  _ __ ___  _ __ ___   __ _ _ __   __| | |_) | _____  __
 | |    / _ \| '_ ` _ \| '_ ` _ \ / _` | '_ \ / _` |  _ < / _ \ \/ /
 | |___| (_) | | | | | | | | | | | (_| | | | | (_| | |_) | (_) >  < 
  \_____\___/|_| |_| |_|_| |_| |_|\__,_|_| |_|\__,_|____/ \___/_/\_\  v1.2.3.00000

Welcome to CommandBox!
Type "help" for help, or "help [command]" to be more specific.
CommandBox> version
CommandBox 1.2.3.00000
CommandBox> pwd
C:\
CommandBox> echo "Hello World!"
Hello World!
CommandBox> exit

C:\>

One-Off Commands

You can also spin up CommandBox from your native shell to execute a single command inline. You can do this if you only have one command to run, or you want to automate a command from a Unix shell script or Windows batch file. This mode will not show the ASCII splash screen, but keep in mind it still loads CommandBox up and unloads it in the background. Any output from the command will be left on your screen, and you will be returned to your native OS prompt.

Here is an example of running the version command from a Windows DOS screen. Note, you'll need to either do this from the directory that holds the box executable, or add the executable to your default command path so it is found.

C:\>box version
CommandBox 1.2.3.00000

C:\>

The box text is calling the CommandBox binary, and the version bit is passed along to the CommandBox shell to execute once it loads.

Debug Mode

You can also activate CommandBox in debug mode by passing the -clidebug flag in the command line. This will give you much more verbose information about the running CommandBox environment. This only one-off commands

box -clidebug

Output

Output from commands will be ANSI-formatted text which, by default, streams directly to the console. When in the interactive shell, you can capture the output of commands and manipulate it, search it, or write it to a file. Use a pipe (|) to pass the output of one command into another command as its first input. Output can be piped between more than one command. Use a right bracket (>) and double right bracket (>>) to redirect output to the file system.

Search

Pipe output into the grep command to apply a regex upon it. grep will only emit lines matching the regex.

cat myLogFile.txt | grep "variable .* undefined"

Pagination

Pipe output into the more command to output it line-by-line or page-by-page. Press the spacebar to advance one line at a time. Press the Enter key to advance one page at a time. Press ESC or “q” to abort output.

forgebox show | more

Redirection

Redirect output into a file, overwriting if it exits like so:

dir > fileList.txt

API Docs for fileWrite.

Use the double arrows to append to an existing file.

echo "Step 3 complete" >> log.txt

API Docs for fileAppend.

Tail files

You can pipe a large amount of text or a file name into the tail command to only output the few lines of the text/file. Adding the --follow flag when tailing a file will live-stream changes to the file to your console until you press Ctrl-C to stop.

forgebox search luis | tail
system-log | tail lines=50
tail myLogFile.txt --follow

Ad-hoc Java properties for the CLI

If you want to add ad-hoc Java Properties to the actual CLI process, you can set an environment variable in your OS called BOX_JAVA_PROPS in this format:

BOX_JAVA_PROPS="foo=bar;brad=wood"

That would create a property called foo and a property called brad with the values bar and wood respectively. This environment variable works the same on all operating systems.

Ad-hoc JVM args for the CLI

Similar to above, you may want to add ad-hoc JVM args to the java process that powers the CLI. The steps differ per operating system. For *nix (Linux, Mac), set an environment variable called BOX_JAVA_ARGS in the environment that box will run in.

BOX_JAVA_ARGS="-Xms1024m -Xmx2048m -Dfoo=bar"
box

For Windows, create a file called box.l4j.ini in the same directory as the box.exe file and place a JVM arg on each line. Escape any backslashes with an additional backslash like a properties file format.

-Xms1024m
-Xmx2048m
-Dfoo=bar

Both of those examples would set the min/max heap size of the CLI process and also set a Java System Property called "foo" equal to "bar". There is no effective difference between setting system properties this way as opposed to using BOX_JAVA_PROPS as shown in the previous section, but actual JVM -X settings must be set as described in this section.

Noninteractive Mode

If you are using CommandBox in a continuous integration server such as Jenkins or Travis-CI, you may find that features like the progress bar which redraw the screen many times create hundreds of lines of output in the console log for your builds. You can enable a non interactive mode that will bypass the output from interactive jobs and the download progress bar.

config set nonInteractiveShell=true

If there is no nonInteractiveShell setting, CommandBox will automatically default it to true if there is an environment variable named CI present, which is standard for many build servers such as Travis-CI.

Custom working directory

CommandBox will start its current working directory in the same folder that you started the box process from. Once you are in the interactive shell, you can always change the current working directory with the cd command. If you want to change the default working directory or just want to run a one-off command in another folder, you can use the -cliworkingDir flag to the box binary when you start it.

box -cliworkingDir=C:/my/path/here/
# This works too
box -cliworkingDir C:/my/path/here/
# And can be coupled with a command to run
box -cliworkingDir C:/my/path/here/ install

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

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 (See API Docs) which can be used to run native commands from within CommandBox. Command input parameters and flags won't necessarily match your OS's native shell. CommandBox uses its own parser and commands/parameters will be formatted as documented here.

Selecting and copy/paste may differ based on your operating system and how it treats command windows. CommandBox uses some color and formatting in its output. This uses ANSI escape codes and will only work correctly if you're using an ANSI-compatible shell to run CommandBox from.

Starting and Stopping

If you have launched the CommandBox executable from your OS's GUI, it will run inside of a native shell window. When finished running commands, you can simply close the window, or type exit an the window will close for you. If you have a series of commands to run, this is the recommended approach.

If you manually open your native shell and execute the box executable, it will take over the screen and the prompt will now become a CommandBox prompt. When you type exit the CommandBox program will drop you back at your native OS shell.

One-Off Commands

You can also leverage CommandBox as another operating system binary if you want to execute one-off commands without having the need to go into the interactive shell. This is useful if you are integrating CommandBox with other system binaries, task runners, ANT, or you just want to execute a CFML template or CommandBox recipe.

$ box version
$ box install coldbox-be
$ box upgrade

Info Executing one-off commands might have a delay when executing as the CommandBox environment needs to load first.

So let's go a little deeper into CommandBox execution.

Special Path Expansions

On Windows, / or \ will be treated as the current drive root based on the current working directory. This is the same as DOS.

cd /windows/system32

On all OS's, ~ will expand to the current user's home directory.

cd ~
ls ~/.ssh

Ingredients

Think of a recipe as a simple batch file for Windows or a shell script for Unix. It's just a text file where you place one command on each line and they are executed in order. Enter the commands exactly as you would from the interactive shell.

buildSite.boxr

Get Cooking

Execute your recipe with the recipe command, giving it the path to the recipe file.

If any commands in the recipe stop and ask for input, the recipe will pause until you supply that input. All commands that have confirmations, etc should have a --force flag for this purpose so you can run them headlessly without requiring your input. See the rm command above for an example.

Spice It Up

You can also bind the recipe with arguments that will be replaced inside of your recipe at run time. Pass any arguments as additional parameters to the recipe command and they will be passed along to the commands in your recipe.

Named arguments

If you use named arguments to the recipe command, they will be accessible via environment variables inside the recipe as ${arg1Name}, ${arg2Name}, etc.

Consider the following recipe:

notifyWinner.boxr

You would call it like so:

Output:

Note, all parameters to the recipe command needed to be named, including the recipeFile.

Positional Parameters

Now let's look at the same recipe set up to receive positional parameters.

You would call it like so:

Output:

Missing Args

If an argument is not passed, you can use the default value mechanism:

Is there an echo in here?

You can use echo on and echo off in recipes to control whether the commands output to the console as they are executed. This can be useful for debugging or confirming the success of commands with no output. Echo is on by default.

Note, echo off doesn't suppress the output of the commands, just the printing of the command and its arguments prior to execution. This does not use the actual echo command and is a feature that only applies during the execution of recipes.

Output:

Exiting a recipe

You can use the exit command in a recipe and instead of leaving the entire shell, the recipe will simply stop execution right there. If an exit code is passed, it will because the exit code of the recipe command as well as the entire shell.

Any command that errors or returns a non-0 exit code will end the recipe immediately and the recipe command will inherit that exit code. This line in a recipe will stop the recipe if there is not a foobar property in your box.json, but not before outputting a message.

On The Fly Commands

In addition to passing a file path to the recipe command for execution, you can also pipe the contents of a file directly into the command. if the input does not match a file path, it is assumed to be executable commands.

This can also give you some interesting ability to do dynamic evaluation of command strings.

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

http://apidocs.ortussolutions.com/commandbox/current/index.html?commandbox/system/modules/system-commands/commands/run.html

Hint This behavior is dependent on your operating system.

Using run binary

Execute an operation system level command using the native shell. For Windows users, cmd.exe is used. For Unix, /bin/bash is used. Command will wait for the OS command to finish.

The binary must be in the PATH, or you can specify the full path to it. Your keyboard will pass through to the standard input stream of the process if it blocks for input and the standard output and error streams of the process will be bound to your terminal so you see output as soon as it is flushed by the process.

run myApp.exe
run /path/to/myApp

Using !binary

A shortcut for running OS binaries is to prefix the binary with !. In this mode, any other params need to be positional. There is no CommandBox parsing applied to the command's arguments. They are passed straight to the native shell. As such, you don't need to escape any of the parameters for CommandBox when using this syntax.

!myApp.exe
!/path/to/myApp
!dir
!netstat -pan
!npm ll
!ipconfig
!ping google.com -c 4
!java -jar myLib.jar

Current Working Directory Aware

OS Commands you run are executed in the same working directory as CommandBox. This means you can seamlessly invoke other CLIs without ever leaving the interactive shell.

!git init
touch index.cfm
!git add .
!git commit -m "Initial Commit"

Building On

The output of native calls can be used in expressions or piped into other commands. Here's a Unix example that uses CFML functions from the command line to parse the parent folder from the current working directory:

#listlast `!pwd` /

Parsing Rules

When passing a command string for native execution, ALL REMAINING TEXT in the line will be "eaten" by the native execution and passed to the OS for processing. This is so the CommandBox parser doesn't "'screw up" any special syntax that your OS command processor is expecting. That means any use of piping or && will get passed straight to the OS. On Windows, the following string will run the ver command twice in Windows.

!ver && ver

In the event you want to pipe the result of an OS binary to another CommandBox command or chain another CommandBox command on the end, you can workaround this by echoing out the string and then piping that to the run command. This example will run the Windows ver command followed by the CommandBox ver command.

echo "ver" | run && ver

Additionally, any expansions you put in your command string with backticks or System Setting placeholders will not be processed by CommandBox, but will be passed to the native OS directly. This Windows example won't do what you might think since the backticks are passed, untouched to the OS (so the OS can expand them if it needs):

!git status | find "'package show name'"

Instead, you can pass the command text through echo to have CommandBox process the backtick expansions first before sending it off to the OS for processing.

echo 'git status | find "`package show name`"' | run

In the above example, written for Windows, the output of the echo command has the package show name expression expanded into the string and then the ENTIRE string is piped to run where the pipe and the find command are processed by Windows. Note, there is no need for preceding the command with ! when passing to run since ! is just an alias for run.

Debugging

If you're having issues getting a native binary to run, you can turn on a config setting that will echo out the exact native command being run including the call to your OS's command interpreter.

config set debugNativeExecution=true

Setting the Native Shell

You can override the default native shell from /bin/bash to any shell of your choosing, like zsh. This will let you use shell specific aliases. You can set your native shell property using the config set command (i.e., config set nativeShell=/bin/zsh)

Exit Codes

If the native binary errors, the exit code returned will become the exit code of the run command itself and will be available via the usual mechanisms such as ${exitCode}.

CLI Environment Variables

Any environment variables you set in the CommandBox shell will be available to the native process that your OS binary runs in. Here's a Windows and *nix example of setting an env var in CommandBox and then using it from the native shell.

set name=brad
!echo %name%

set name=brad
!echo $name

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.

coldbox create app name=myApp skeleton=AdvancedScript directory=myDir init=true

Positional Parameters

Positional parameters omit the name= part and only use the value. They must be supplied in the order shown in the Command API docs or help command. We try to place the most common parameters at the beginning so you can use named parameters easily. Here is the equivalent of the named command above:

coldbox create app myApp AdvancedScript myDir true

Of course, only the required parameters must be specified. I'm only including all of them here for the completeness of the example.

Required Parameters

If you do not provide a parameter that is required for the command execution, the shell will stop and ask you for each of the missing parameters before the command will execute.

CommandBox> mkdir
Enter directory (The directory to create) : myDir
Created C:\myDir
CommandBox>

Info It is not necessary to escape special characters in parameter values that are collected in this manner since the shell doesn't need to parse them. The exact value you enter is used.

Flags

Any parameter that is a boolean type can be specified as a flag in the format --name. Flags can be mixed with named or positional parameters and can appear anywhere in the list. Putting the flag in the parameter list sets that parameter to true. This can be very handy if you want to use positional parameters on a command with a large amount of optional parameters, but you don't want to specify all the in-between ones.

coldbox create app myApp --init --installColdBox

You can also negate a flag by putting an exclamation point or the word "no" before the name in the format --no{paramName}. This sets the parameter to false which can be handy to turn off features that default to true.

coldbox create app myApp --noInit

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.

echo 'Hello World'
echo "Good Morning Vietnam"

Quotes

Quotes are actually allowed unescaped in a value like so:

echo O'reilly

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

echo 'O\'reilly Auto Parts'
echo "Luis \"The Dev\" Majano"

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.

echo "O'reilly Auto Parts"
echo 'Luis "The Dev" Majano'

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.

echo "Nothing to \`see\` here"

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.

echo 2+2\=4
echo "2+2=4"

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.

echo foo\\\=bar

This will print foo\=bar

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 CommandBox Bullet Train 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 System Setting called exitCode.

> !git status
fatal: not a git repository (or any of the parent directories): .git
Command returned failing exit code [128]
​
> echo ${exitCode}
128

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

$> box testbox run

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.

exit 123

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.

mkdir foo && cd foo

||

You can use || to run the second command only if the previous one failed.

mkdir foo || echo "I couldn't create the directory"

;

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.

mkdir foo; echo "I always run"

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.

pathExists box.json && package show

You can specify if the path needs to be a file or a folder.

pathExists --file server.json && server show
pathExists --directory foo || mkdir foo

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

assertTrue `package show private` && run-script foo
assertTrue ${ENABLE_DOOM} && run-doom
assertTrue `#fileExists foo.txt` && echo "it's there!"

assertEqual

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

assertEqual `package show name` "My Package" || package set name="My Package"
assertEqual ${ENVIRONMENT} production && install --production

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:

In the example above, the contents of the defaultServer.txt file will be passed in as the value of the "name" parameter to the "server start" command. If the contents of the file was the text myServer, the equivalent final command would be:

Inside Parameters

There can be more than one expression in a single parameter value. Expressions can also be combined with static text and they will all be evaluated in the order they appear:

That would output something similar to:

If you need to use an actual backtick in a parameter value, escape it with a backslash.

Which outputs

Express Yourself

This unlocks a new world of scripting potential when combined with other abilities like native OS binary execution and CFML functions from the CLI. Here's some examples to get your gears turning:

Set a package property in box.json equal to the current date passed through a CFML date mask

Set properties based on manipulations of previous values:

Perform CFML operations on local files:

Execute environment-aware install scripts based on local files. (isProduction.txt would contain the text true or false in this ex.)

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

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

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

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.

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 Azul Zulu 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)

Installing on *nix

The box binary on *nix uses your OS environment variables to locate Java. In the absense 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.

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.

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.

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.

To set a new variable, you can run this:

env set foo=bar

# or just
set foo=bar

You can view the contents of that variable from anywhere in the same shell session like so:

env show foo

# or provide a default value
env show foo myDefault

# Or via System Setting expansions
echo ${foo:myDefault}

Clear out an environment variable like so:

env clear foo

Per-Command Environment Variables

In addition to the global shell environment, each executing command receives its own set of environment variables that go away when the command finishes executing. Unlike Bash, the parent variables are not copied into each command, but a hierarchy is maintained and when a variable is not found, the parent command is checked and so on until the global shell variables. After that, the Java system properties and then OS's actual environment is checked.

Here is a contrived example of an echo command that run a sub command as part of a command expression (backtick expansion). The sub command sets an environment variable and then outputs it.

echo `set myVar=cheese && echo \${myVar}`
env show myVar myDefault

The first line will output the text "Cheese" but the second line will output the default value of "myDefaul" since the variable only existed in the inner context of the expression and isn't visible to the outer shell.

Recipes

Recipes behave like a subshell and any variables set in a recipe will live for the duration of that recipe but will be gone once the recipe exits.

Viewing Variables

To view the environment variable for the current command context, run:

> env set color=red
> env set number=2
> env show
{
    "number":"2",
    "color":"red"
}

The output is a JSON serialized struct, which makes it suitable for programmatically accessing.

> env show | foreach "echo 'The var \${item} is set to \${value}'"
The var number is set to 2
The var color is set to red

There is a command to help you debug what variables are set in each command context as well as the global shell. Here we pipe some commands into a recipe for execution. The context for the env debug command has no variables, the recipe command has a variable called inRecipe and the global shell as the 2 variables from the example above.

> echo "set inrecipe=true; env debug" | recipe
[
    {
        "environment":{},
        "context":"env debug"
    },
    {
        "environment":{
            "inRecipe":"true"
        },
        "context":"recipe"
    },
    {
        "environment":{
            "number":"2",
            "color":"red"
        },
        "context":"Global Shell"
    }
]

Native Binaries

Any environment variables you set in the CommandBox shell will be available to the native process that your OS binary runs in. Here's a Windows and *nix example of setting an env var in CommandBox and then using it from the native shell.

set name=brad
!echo %name%

set name=brad
!echo $name

Passing Environment Variables to Servers

Any ComandBox environment variables present in the shell will automatically be passed to the environment of the server process. This means, given an example like this:

set foo=bar
server start

The CFML code running that server process will be able to "see" the foo environment variable.

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.

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.

Namespace Help

Next, drill down and get help on a specific namespace like server.

Command Help

And finally, get help on a single command such as server stop. We can see the command is also aliased as just stop as well as all the possible parameters and their types along with a few sample ways to call the command.

HTML Command API Docs

For a full list of all the commands that ship with CommandBox as well as all their paramaters and samples, please visit our Command API docs which are auto-generated each build. This is the same information available to you via the help command, but in a searchable format you can browse outside of the CLI.

• http://apidocs.ortussolutions.com/commandbox/current

System Logs

Sometimes, you need to view the CommandBox log file. Maybe it is to debug a command you are writing or to submit a crash report. The system-log command outputs the path to the CommandBox log file. You can use it creatively by piping its output in to other commands:

CommandBox> system-log | open
CommandBox> system-log | cat
CommandBox> system-log | tail

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.

Let's take it a step further and alias the alias!

Running cout brad is the same as running print brad which is the same as running echo brad. Try not to get dizzy when doing this, please.

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.

Using system settings from the CLI

You can test it out easily by outputting your system path like so:

Default values

If a system setting can't be found in a Java property or an environment variable, an empty string will be returned. You can provide a default value like so.

This does assume that your default value will never contain a colon!

Lookup Order

System settings are looked up in the following order. If the same variable exists in more than one place, the first one found will be used:

1. Environment variables for the currently executing command

2. Environment variables for the parent (calling) command (if applicable)

3. Global shell environment variables

4. JVM System Properties in the CLI process

5. Environment Variables from your actual operating system

For example, if you run the following it will output the contents of your OS's PATH environment variable.

However, if you set a shell environment variable from inside CommandBox called path and then output it, you will see the contents of your variable since it overrides.

Using system settings in JSON files

When box.json or server.json files are read, they automatically have all system setting setting placeholders swapped out. For instance, you can specify the port for your server in your server.json like so:

Note, we escaped the system setting by putting a backslash (\) in front of it. That's because we wanted to insert the actual text into the file and not the value of it! The resultant server.json is this. Note the system setting needs to be encased in quotes so it's just a string for the JSON.

Now, if your server has an environment variable called WEB_PORT, it will be used as the port for your server.

System settings can also be used in object key names as well in your JSON files. Here is an example of a .cfconfig.json file with a dynamic datasource name.

Note if there are duplicate key names after the system settings are expanded, the last one expanded will win.

In the REPL

You can use system settings and environment variables in the REPL using the same syntax as the CLI

Manual system setting replacements

If you're writing a custom command or task runner that reads a JSON file of your own making, you can do easy system setting replacements on the file.

In a complex data structure

In a string

The expandDeepSystemSettings() method will recursively crawl the struct and find any strings with system setting placeholders inside them. Be careful not to write back out the same struct after you've done replacements on it. Otherwise, you'll overwrite the placeholders with the current values!

You can also manually replace system setting placeholders in a single string like so:

Programmatic access

The SystemSettings service also gives you programmatic access to individual system settings in your custom commands and task runners.

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.

Commands

If your text matches only command, namespace, or alias, it will be auto-filled in for you. For instance, if you type the following and press tab...

Parameters

If the parser finds a complete command, it will move on to parameter completion which is slightly more complicated since at first, there is no way to tell if you are going to named parameters, positional parameters, and/or flag. Based on what parameters you've typed so far, if any, CommandBox will do it's best to give you only relevant options. If it is unsure, it will provide you with every possibility it can think of. Don't be afraid to try pressing tab while typing parameters, you may be surprised how often we can guess where you're going!

Named

If you have started typing named parameters, CommandBox will only suggest unused named parameters and flags.

If you are using named parameters, and you have typed the name of a parameter followed by an equals sign and no space, CommandBox will attempt to prompt valid values. This includes but is not limited to booleans and file system paths.

Here, true and false are offered as possible values for the force parameter.

Positional

Tab completion for positional parameters works the same as the "value" portion of named parameters. Parameter names will also show up when you hit tab even when using positional parameters. This is on purpose to remind you of what options you have, but you obviously won't type them.

Flags

Tab completion will always work for flags if your command has any boolean parameters. Here we type -- in the delete command and we are prompted with --force and --recurse.

Custom

Commands have the ability to give hints in the form of a static list or a runtime function with dynamic output.

REPL

When writing code inside the REPL, you can also press tab to get completion on

• CFML function names

• Member function names like .append()

• Variable names you have created as part of your REPL session

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 ${item}. Remember to escape the expansion in your command so it's resolution is deferred until the forEach runs it internally. Here we echo each file name followed by the contents of the file.

You may also choose a custom placeholder name for readability.

Here's an example that has several things going on. It takes a list of globbing patterns to get all CFC and CFM files recursively in a directory, then it loops over each file path, outputting it preceded by the current working directory, with backslashes replaced with forward slashes.

Iterating over JSON

The forEach can also iterate over JSON representations of objects or arrays. This means you can pipe in JSON from a file, a command such as package show or any REPL operation that returns complex data. The delimiter parameter is ignored for JSON input.

If iterating over an array, each item in the array will be available as ${item}. If iterating over a object, the object keys will be in ${item} and the values will be in ${value}.

You can customize the system setting name for value with the valueName parameter to forEach.

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)

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.

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.

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:

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!

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!

These settings affect how CommandBox loads modules.

ModulesExternalLocation

array

You can store CommandBox modules outside of the default installation directory. This may be useful to point to modules you are developing or to keep custom modules around even if CommandBox gets uninstalled.

config set ModulesExternalLocation=[\"/var/my/external/modules\"]
config show ModulesExternalLocation

modulesInclude

array

An array of module names to load. Be careful of using this setting as once you set it, no other modules will be loaded which includes all of CommandBox's core modules.

config set modulesInclude=[\"moduleName\",\"anotherModuleName\"]
config show modulesInclude

ModulesExclude

array

An array of module names NOT to load. This can be useful when you have an installed module that's erroring on load and preventing CommandBox from starting up.

config set ModulesExclude=[\"moduleName\",\"anotherModuleName\"]
config show ModulesExclude

modules.*

struct

When you install a CommandBox module, it may contain settings that affect how it works. Don't edit the CFML code in the module, instead use the config set command to create config settings that will override the module's defaults. The pattern is modules.moduleName.settingName.

config set modules.TestModule.mySetting=overridden
config set modules.TestModule.somethingEnabled=false

When a module is loaded, the config settings (that exist) for that module are loaded as well. Any time you set a new module setting, that setting will be loaded into memory immediately for that module.

You can easily see what settings are set for our TestModule like so:

config show modules.TestModule

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

cfml now

#function

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

#now

Function parameters

When you pass parameters into this command, they will be passed directly along to the CFML function. The following commands are the equivalent of hash( 'mypass' ) and reverse( 'abc' ).

#hash mypass
#reverse abc

Piping them together

This really gets useful when you start piping input into CFML functions. Like other CFML commands, piped input will get passed as the first parameter to the function. This allows you to chain CFML functions from the command line like so. (Outputs "OOF")

#listGetAt www.foo.com 2 . | #ucase | #reverse

By piping commands together, you can use CFML functions to transform output and input on the fly to generate very powerful one-liners that draw on the many CFML functions already out there that operate on simple values.

Complex Values

Since this command defers to the REPL for execution, complex return values such as arrays or structs will be serialized as JSON on output. As a convenience, if the first input to an array or struct function looks like JSON, it will be passed directly as a literal instead of a string.

The first example averages an array. The second outputs an array of dependency names in your app by manipulating the JSON object that comes back from the package list command.

#arrayAvg [1,2,3]
package list --JSON | #structFind dependencies | #structKeyArray

The sky is the limit with the mashups you can create. This example runs your native java binary, uses CFML functions to strip out the first line, and then grabs a portion of that string via regex in the sed command.

echo "java -version" | run  | #listToArray `#chr 10` | #arrayFirst | sed 's/java version "(.*)"/\1/'

Named Parameters

You must use positional parameters if you are piping data to a CFML function, but you do have the option to use named parameters otherwise. Those names will be passed along directly to the CFML function, so use the CF docs to make sure you're using the correct parameter name.

#directoryList path=D:\\ listInfo=name

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

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 GitHub repository 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 - http://www.harvesting.org/. 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 (http://www.harvesting.org/) 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.

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.

ds = {
  class: 'org.gjt.mm.mysql.Driver',
  connectionString: 'jdbc:mysql://localhost:3306/bradwood?useUnicode=true&characterEncoding=UTF-8&useLegacyDatetimeCode=true',
  username: 'root',
  password: 'encrypted:bc8acb440320591185aa10611303520fe97b9aa92290cf56c43f0f9f0992d88ba92923e215d5dfd98e632a27c0cceec1091d152cbcf5c31d'
};

var qry = queryExecute( sql='select * from cb_role', options={ datasource : ds } );

for( var row in qry ) {
  echo( row.role & chr( 10 ) );
}

So, the first block simply declares a struct that represents a datasource connection. Then I use that struct as my datasource. You might be thinking, "where the heck did he get that struct??". Glad you asked. Start up a Lucee 4 server, edit a datasource that has the connection properties you want and then at the bottom of the edit page you'll see a code sample you can just copy and paste from. This is the code for an `Application.cfc`, but you can re-use the same struct here.

Another method

There are a couple tags inside Lucee that don't support this just yet. `<CFDBInfo>` is one of them. [Ticket Here] In this case, you need a "proper" datasource defined that you can reference by name. Lucee has some more tricks up its sleeve for this. You can simulate the same thing that happens when you add a datasource to your `Application.cfc` with the following code. This will define a datasource for the duration of the time the CLI is running in memory, but it will be gone the next time you start the CLI.

appSettings = getApplicationSettings();
dsources = appSettings.datasources ?: {};

dsources[ 'myNewDS' ] = {
    class: 'org.gjt.mm.mysql.Driver',
    connectionString: 'jdbc:mysql://localhost:3306/bradwood?useUnicode=true&characterEncoding=UTF-8&useLegacyDatetimeCode=true',
    username: 'root',
    password: 'encrypted:bc8acb440320591185aa10611303520fe97b9aa92290cf56c43f0f9f0992d88ba92923e215d5dfd98e632a27c0cceec1091d152cbcf5c31d'
};
application action='update' datasources=dsources;

var qry = queryExecute( sql='select * from cb_author', options={ datasource : 'myNewDS' } );

for( var row in qry ) {
    echo( row.firstName & chr( 10 ) );
}

So let's break this down real quick. First we get the current settings of the CLI Lucee context and the list of current databases (may be null). Then we simply add the same datasource definition as above to the struct with the name we wish to use to reference this datasource. And finally we `update` the application with the new struct of datasources. Now we can use this datasource name just we would in a "normal" web application.

Notes

The internal CLI of CommandBox still runs on Luce 4.5 so make sure you copy the data source definitions from a Lucee 4.5 server, and not a 5.0 server. Also, you'll note I used encrypted passwords above. You can also just put the plain text password in. Just omit the `encrypted:` text like so:

username: 'root',
password: 'clear text password'

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

Install the module like so:

Fonts

This module uses some special Unicode characters to draw the prompt that may not be in your default terminal. You can turn off all Uniode chars and live with an uglier shell like so:

Or try a font like Consolas, DejaVu Sans Mono, or Fira Code. The best way to get all the characters to work is to install a "Powerline patched" font and set your terminal to use it. This may differ based on your operating system.

Here is a guide for setting a new font up to be used with the Windows cmd terminal:

For Windows users, we also recommend using ConEMU as your terminal.

Usage

You don't need to do anything special. Just continue to use the CommandBox interactive shell like you always do. You'll notice that the prompt is spanned across two lines and contains additional information. Cars that do not apply to the current directory will simply not be displayed. Familiarize yourself with what each bullet train "car" represents and soon you'll be using the data in the prompt without even thinking about it!

Customize it!

You can customize the cars that show, change the colors of existing cars and even create your own custom additions to Bullet Train. Read all about it in the readme of the Module homepage on ForgeBox.

You can specify the CFML engine via the command line arguments:

This will start an Adobe ColdFusion 9 server in your webroot. That's it!

By default, CommandBox uses the cfengine slug to search for the engine on ForgeBox. The format is slug@version where the version is optional. Ortus Solutions maintains the versions of the engines available on ForgeBox.

Supported engines are:

• Adobe ColdFusion 9 **

• Adobe ColdFusion 10

• Adobe ColdFusion 11

• Adobe ColdFusion 2016

• Adobe ColdFusion 2018

• Railo 4.2

• Lucee 4.5

• Lucee 5

Here are some examples:

Engines are downloaded and stored in your CommandBox artifacts folder. You can view your engines and clear them using the standard artifacts commands:

ColdFusion Admin settings

While Lucee asks for a password the first time running the admin, ColdFusion requires a username and password when CommandBox sets it up. The default username and password for the Adobe ColdFusion servers used are:

• Username: admin

• Password: commandbox

WAR Support

Additionally, CommandBox can start any WAR given to it using the WARPath argument.

If you run a regular start command inside of a folder that has a /WEB-INF/web.xml file, CommandBox will treat that folder as a WAR.

Custom Engines

The cfengine parameter can accept any valid CommandBox endpoint ID. That means it can be an HTTP URL, a Git repo, a local folder path to your company's network share, or a custom ForgeBox entry you've created. As long as that endpoint resolves to a package that contains these files, you're good:

1. box.json

2. Engine.[zip|war] (file name doesn't matter)

CommandBox will download the package, unzip it and use the WAR/zip file as the engine for your app.

Normally, the artifacts cache isn't used for non-ForgeBox packages, but CommandBox will only download the engine once per server and then assume the file hasn't changed. You will need to forget the server to trigger a new download.

Here's an example of starting up a web server using a direct download link to a package containing a WAR file:

server.json Configuration

You can set the cfengine and other related configuration options in your server.json to use them every time you start your app.

These commands would create the following server.json

Just a reminder that starting a server with any command line arguments will save the arguments to your server.json by default.

This command would add adobe@9 to your server.json. If this is not what you want, you can append saveSettings=false or even --!saveSettings when you start your server and CommandBox will not save the arguments you specify to your server.json.

Quickstart

Installation

via PackageControl

Just type cmd-shift-p/ctrl-shift-p to bring up the command pallete and pick Package Control: Install Package from the dropdown, search and select the CommandBox package there and you're all set.

Manually

You can clone the repo in your /Packages (Preferences -> Browse Packages...) folder and start using/hacking it.

Troubleshooting

Usage

Running a Commandbox Command

You may select pre-configured commands from Menu -> Commandbox, including the ability enter a custom command.

Keyboard Shortcuts:

• Ctrl+Shift+B - Run Commandbox Command: A prompt input will open for you to enter your command

• Ctrl+Shift+T - Start the Embedded Server: Your Commandbox cwd is always the root of your Sublime Project so any box.json configuration will be honored

• Ctrl+Shift+P - Stop the Embedded Server

• Alt+P - Show the Commandbox Output Panel ( also available in the View -> Commandbox menu )

• Alt+[Command|Windows]+P - Hide the Commandbox Output Panel ( also available in the View -> Commandbox menu )

Settings

The file Commandbox.sublime-settings is used for configuration, you can change your user settings in Preferences -> Package Settings -> Commandbox -> Settings - User.

The defaults are:

exec_args

You may override your PATH environment variable as follows:

box installed locally

If box is installed locally in the project, you have to specify the path to the box executable. Threfore, adjust the path to /bin:/usr/bin:/usr/local/bin:node_modules/.bin

results_in_new_tab

If set to true, a new tab will be used instead of a panel to output the results.

results_autoclose_timeout_in_milliseconds

Defines the delay used to autoclose the panel or tab that holds the Commandbox results.

show_silent_errors

log_erros

Toggles the creation of sublime-commandbox.log if any error occurs.

syntax

Syntax file for highlighting the box results. You can pick it from from the command panel as Set Syntax: Commandbox results.

Set the setting to false if you don't want any colors (you may need to restart Sublime if you're removing the syntax).

nonblocking

When enabled, the package will read the streams from the task process using two threads, one for stdout and another for stderr. This allows all the output to be piped to Sublime live without having to wait for the task to finish.

If set to false, it will read first from stdout and then from stderr.

Bind Your Own Keyboard Shortcuts

You can use a shortcut for running a specific task like this:

Sometimes you may wish to start a server on a computer that doesn't have access to the Internet. However, you may notice that running a command such as the following will throw an error trying to connect to ForgeBox:

That is because 5.x is a semver range and not a specific version. CommandBox must connect to ForgeBox to see what versions of the CF engine lucee can be found to use the latest one.

Be More Specific

If you know that a CF engine is already downloaded in your server's artifacts directory, start your server with a specific major, minor, and patch version to skip the ForgeBox check.

NOTE: If this fails, check the location of the folder structure below the artifacts folder for it's exact path. e.g. /artifacts/lucee/5.0.0+252/lucee.zip - The box command for this would be: start cfengine=lucee@5.0.0+252 This follows the pattern: /artifacts/[server-type]/[server-version]/[server-type].zip Useful if you've manually downloaded the file from forgebox and need to rename it.

Fail Safe

If CommandBox needs to connect to ForgeBox to resolve a version number and ForgeBox is unavailable, it will look in your local artifacts cache to try and find a cached version of that CF engine that satisfies your semver range. This means you may not get the latest version of that CF Engine, but at least your server will start up.

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 \n escape sequence.

Namespaces

Hint the text artifacts itself is not a command and you will receive an error if you hit enter after just typing that text. Context-specific help is available for all namespaces by typing help after the namespace.

Aliases

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 Manual - Version 5.1.0

Versioning

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

• 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

Reporting a Bug

Professional Open Source

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

Resources

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

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.

Multi-line

Multi-line statements are also allowed. If you have typed a starting { without an ending }, the REPL will keep accepting lines until it has determined the statement to be finished. The prompt changes to ... until the statement is finished.

If you would like to abort a multi-line statement, simply type exit at the prompt.

Tag REPL

You can also enter tags at the REPL. Switch to this mode by setting the script flag to false.

Any output from the tags will be returned to the console.

Multi-line statements are not currently supported in the tag REPL.

History

The script and tag REPL have their only history. Use the up and down arrows to access previous things you typed. Your REPL history can be viewed and managed by the history command (once you exit the REPL).

Tab completion is currently not supported in either of the REPLs.

Environment Variable Expansions

You can use environment variable expansions in the REPL with the same syntax that works in the CLI and JSON files. Consider this example which sets an environment variable in the shell and then enters the REPL command and references the variable. Note, the variable is expanded in-place, so you still need to wrap it in quotes so the resulting CFML code is valid.

Escapes work the same way in the REPL

You may want to start up a local server that does not have a CF Engine such as Lucee or Adobe ColdFusion installed. You can do this as of CommandBox 5.1.0 by setting the cfengine parameter to none like so:

server start cfengine=none

Or in your server.json like this

server set app.cfengine=none
server start

This server will support everything that you are used to including the server.json file, heap settings, ports, and virtual directories. The only difference is it will server everything as static files. (.cfm or .cfc files will not be processed)

It's important to note that each server you start opens a new Java process on your host operating system. This allows each server to have it's own settings and configuration independent of any other server. Start as many as you need and simply stop them when you're done. Just keep in mind each server gets its own heap space so keep an eye on your available RAM.

Server Runs Independant of CLI

The embedded server instances are also a separate process from the actual CommandBox CLI process, which also runs on Java. This means you can open the interactive shell, start a few servers, then quit the shell, yet the servers will still continue to run. You can use the CLI to issue a stop command in the servers web root, or just right click on the tray icon.

There is currently no way to have servers start automatically when your computer boots, though there's nothing preventing you from setting up a local script to run the start commands for you.

WEB-INF

You may be used to having your server's WEB-INF folder living in your web root. The CommandBox embedded server still has a dedicated WEB-INF folder for each server you start, but it lives under the main CommandBox installation directory in your user folder. Changes you make to the WEB-INF such as adding jars or new tas will be persisted until you issue a server forget command.

CommandBox stores information about each of the servers you've ever started inside ~/.CommandBox/servers.json so it can remember settings from one run to the next.

List your server

You can see an overview of your servers and what state they're in with the server list command.

server list

site1 (starting)
  https://127.0.0.1:8081
  C:\site1

site1 (running)
  https://127.0.0.1:8082
  C:\site2

site3 (stopped)
  https://127.0.0.1:8083
  C:\site3

If you have many servers, you can provide parameters to help filter the results from server list

# All servers containing the word "foo"
server list foo

# Running servers
server list --running

To list only the servers that have been started in a given directory, use the --local flag.

server list --local

You can take a quick look at the what's been happening with the server log command or use the server status command to see more detailed information including the arguments used previously to start/stop the server.

Multiple Servers

Servers are uniquely identified by their full path, but they also have a short name which defaults to the immediate folder containing their web root. The stop, start, etc commands can be run in the web root for a server, or in any working directory as long as you reference the server's short name.

start site1
start site2
restart site3
stop site2
stop --all

Another handy shortcut is the server cd command that will change the current working directory of the interactive shell to the web root of a named server.

server cd site1
start
server cd site2
install myPackage
restart

Info Server name is the first parameter to all server commands and tab completion works too, making it as easy as possible for you.

Get Server Information

You can get information about a server using the server info command. Add the --JSON flag to get the data back in a JSON format. The property parameter will allow you to retrieve a single value for scripting mashups.

server info
server info --JSON
server info property=serverHomeDirectory
server info property=consoleLogPath

Forgetting Servers

If you want to wipe all configuration, logs, and WEB-INF files for a server, use the server forget command. This will also remove any administrator settings you may have saved including data sources, mail servers, and server mappings.

server forget

You can forget all your servers at once too if you want to start with a clean slate. This command will stop and forget all servers.

server stop --all --forget

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:

mkdir C:/sites/test
mkdir /sites/test
mkdir \\server/share/test

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:

mkdir /opt/var/sites/test

Relative

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

mkdir test

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

mkdir ../../sites/test

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.

\\server/share/sites/test
\\10.10.1.205/webroot/logs

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

cd \\\\server/share/sites/test
mkdir \\\\10.10.1.205/webroot/logs

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.

CommandBox has a global configuration file that stores user settings. It is located in ~/.CommandBox/CommandBox.json and can be used to customize core CommandBox behaviors as well as overriding module settings. Config settings are managed by the config set, config show, and config clear commands.

Set Config Settings

config set name=mySetting

Nested attributes may be set by specifying dot-delimited names or using array notation. If the set value is JSON, it will be stored as a complex value in the commandbox.json.

Set module setting

config set modules.myModule.mySetting=foo

Set item in an array

config set myArraySetting[1]="value"

Set multiple params at once

config set setting1=value1 setting2=value2 setting3=value3

Override a complex value as JSON

config set myArraySeting="[ 'test@test.com', 'me@example.com' ]"

Structs and arrays can be appended to using the "append" parameter. Add an additional settings to the existing list. This only works if the property and incoming value are both of the same complex type.

config set myArraySetting="[ 'another value' ]" --append

Show Config Settings

Output a setting:

config show settingName

Nested attributes may be accessed by specifying dot-delimited names or using array notation. If the accessed property is a complex value, the JSON representation will be displayed

config show modules.myModule.settingName
config show mySettingArray[1]

Clear Config Setting

To Remove a setting out of the CommandBox.json use the config clear command. Nested attributes may be set by specifying dot-delimited names or using array notation.

config clear description

Your CF engine (Lucee, Adobe, etc) or Java app may have application logs of its own and their locations will vary based on what you have running. In any case, they will most likely be located under the server home directory.

CF App server logs

You can find out where your server home is by running:

server info property=serverHomeDirectory

You can also get the full path to your servlet's "out" log with this command:

server info property=consolelogPath

This log file is the equivalent of your catalina.out file on a typical Lucee/Tomcat install or the equivalent of your coldfusion-out.log file on a typical ColdFusion install.

The Servlet's "out" log can be tailed with this command:

server log --follow
server log myServerName --follow

Your console "out" log will auto-rotate every 10MB to keep it from getting too big. Don't use the --debug or --trace flag on a production server or you'll get a lot of logging information! Without those flags, the "out" log doesn't log anything for each request. With debug enabled, you'll get basic information for each request that comes in as well as whether a rewrite rule fired, and with trace, you'll get a ton of information about every request as well as every local path resolution by the path resource manager.

Lucee Server's Log Files

There are many log files for Lucee. For the guide below, I'm assuming you haven't set a custom serverConfigDir or webConfigDir for your servers. If you have, adjust the paths for the server and web context to be whatever it is you've configured. Here are the three locations you'll find log file and is pretty much the same for Lucee 4 and Lucee 5.

1. Lucee's server context log files - The server context is located under the server home which you can find with the command server info property=serverHomeDirectory. Open that directory and then navigate to WEB-INF/lucee-server/context/logs/.

2. Lucee's web context log files - The web context is also located under the server home. Open that directory and then navigate to WEB-INF/lucee-web/logs/.

So, to give real examples-- a Lucee server I just looked at on my machine has the three folders of log files I just covered above in these locations:

C:/users/brad/.CommandBox/server/{hash}-cfconfig/lucee-4.5.5.006/logs/server.out.txt

C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/application.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/datasource.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/deploy.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/gateway.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/mapping.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/memory.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/orm.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/remoteclient.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/rest.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/scope.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/search.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-server/context/logs/thread.log

C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/application.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/datasource.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/deploy.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/gateway.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/mapping.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/memory.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/orm.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/remoteclient.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/rest.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/scope.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/search.log
C:/users/brad/.CommandBox/server/{hash}cfconfig/lucee-4.5.5.006/WEB-INF/lucee-web/logs/thread.log

Adobe ColdFusion's Log Files

Since Adobe doesn't have the separation of server and web contexts, it only has two log locations which are as follows on all versions.

1. ColdFusion server log files - The remaining log files are located under the server home which you can find with the command server info property=serverHomeDirectory. Open that directory and then navigate to WEB-INF\cfusion\logs/.

So, to give real examples-- a ColdFusion server I just looked at on my machine has the two folders of log files I just covered above in these locations:

C:/users/brad/.CommandBox/server/{hash}-testSite/adobe-2016.0.03.300466/logs/server.out.txt

C:/users/brad/.CommandBox/server/{hash}-testSite/adobe-2016.0.03.300466/WEB-INF/cfusion/logs/application.log
C:/users/brad/.CommandBox/server/{hash}-testSite/adobe-2016.0.03.300466/WEB-INF/cfusion/logs/audit.log
C:/users/brad/.CommandBox/server/{hash}-testSite/adobe-2016.0.03.300466/WEB-INF/cfusion/logs/eventgateway.log
C:/users/brad/.CommandBox/server/{hash}-testSite/adobe-2016.0.03.300466/WEB-INF/cfusion/logs/exception.log
C:/users/brad/.CommandBox/server/{hash}-testSite/adobe-2016.0.03.300466/WEB-INF/cfusion/logs/monitor.log
C:/users/brad/.CommandBox/server/{hash}-testSite/adobe-2016.0.03.300466/WEB-INF/cfusion/logs/scheduler.log
C:/users/brad/.CommandBox/server/{hash}-testSite/adobe-2016.0.03.300466/WEB-INF/cfusion/logs/server.log
C:/users/brad/.CommandBox/server/{hash}-testSite/adobe-2016.0.03.300466/WEB-INF/cfusion/logs/websocket.log

Access Log

CommandBox servers use a powerful Java-based web server which we've tested to have throughput just as good as Apache or IIS. You can enable "access" logs which output one line for each HTTP request (even for static assets like JS or image files) in the same "common" format that Apache web server uses.

server set web.accessLogEnable=true

View the location of this log or tail the log contents like so:

server info property=accessLogPath
server log --follow --access
server log myServername --follow --access

Your access log will be auto-rotated every day.

Rewrite Log

CommandBox servers use the java-based Tuckey rewrite engine for easy URL rewriting. There's a lot of good debugging information available to help figure out why your rewrites aren't working. You can enable a separate rewrite log to view this information. Keep in mind this can generate a lot of logging output.

server set web.rewrites.logEnable=true

View the location of this log or tail the log contents like so:

server info property=rewritesLogPath
server log --follow --rewrites
server log myServername --follow --rewrites

Your rewrites log will be auto-rotated every 10MB. The amount of information that appears in the rewrites log will be affected by the --debug and --trace flags when you start the server.

CommandBox allows you full control over the servers you start. This includes the port and host, custom JVM args, URL rewriting, web aliases, custom error pages, and custom welcome files.

Ways to provide configuration

Configuration can be set at several different levels:

1. Passed as parameters to the server start command

2. Stored in a server.json file for that server

3. Global defaults in the server.defaults config setting

4. Internal defaults from the ServerService

Settings will be used in that order. Also, any parameters passed to the start command will automatically be saved to your server.json file unless you pass the --noSaveSettings flag.

File path handling

A lot of settings used to start a server involve file paths. Paths starting with a drive letter like C:/, a UNC network path like \\, or a leading slash like / are considered absolute paths and will not be expanded. Try to avoid absolute paths if you want to make your server config portable.

Paths that start with a file/folder name like foo/bar.jar or ../../lib/my.jar are relative and the root folder that they are relative to depends on where there are specified.

• If the path is passed as a parameter to the start command, the path is relative to the current working directory

• If the path is in the server.json file, it is relative to the folder containing the JSON file. (Remember the server.json doesn't have to be in the web root!)

• If the path is in a global server.defaults config setting, it is relative to the web root of the server.

Here are suggestions for using VSC (Visual Studio Code) for developing in CFML.

What do you want to do with VSC?

1. Install it?

2. Key Extensions?

3. Working with the shell/terminal

4. Git Extensions?

Installing VSCode

This IDE has it's own domain. ( https://code.visualstudio.com/ ) with downloads for macOS, Windows and Linux on the home page. :+1:

Using The Terminal/Shell

You can approach this different ways. It is pretty nice to have the command prompt running right inside your IDE. Pressing CTRL +` will show and/or hide your terminal. This will let you run Commandbox directly inside your terminal.

Commandbox only

Go to File > Preferences > Settings and search for shell.windows. Hover over the item in DEFAULT SETTINGS and you will see an edit pencil. Click on that and it will copy the values over to USER SETTINGS. (NOTE: You can also set stuff up in WORKSPACE SETTINGS for different projects. Now set the location of commandbox on your system like we did in our system in the example below.

"terminal.integrated.shell.windows": "/path/to/box",

When adding a path, follow the rules for adding platform specific path seperators.

Commandbox and Shells of Choice

Install Shell Launcher and reload the IDE.

• Shell Launcher Easily launch multiple shell configurations in the terminal.

Now open your user settings like is shown in the Commandbox only section just above. Add the following to your USER SETTINGS.

//Shell launcher // A list of shell configurations for Windows "shellLauncher.shells.windows": [ { "shell": "C:\\Windows\\sysnative\\cmd.exe", "label": "cmd" }, { "shell": "/path/to/box", "label": "Commandbox" } ],

Or loading it as desired

If you have commandbox mapped to a path you can of course just call box like you would from any terminal and it will load right up for you. Just use any terminal in VSC that would load box outside VSC and it will run the same.

Key Extensions

You should also install a few extensions. (These extensions can also be added from the built in Extensions item.)

• CFML Language Support

• CFLint Support

• Tag Comment Support

Git Extensions

Additional Extensions ( of course, choose the ones you want and ignore the others )

• Git Lens This will take your git IDE to new levels.

P.S. A couple of other nice plugins.

• TODO Highlight Add TODO, FIXME or other comments to code and find quickly with this extension.

• Project Manager: save folders as projects and easily switch between projects

• Hg: integrated Mercurial source control

• Great Icons Because it is more fun, nuff said!

More information to follow. (Including video guides to show how to get started that may not be as familiar with different parts.)

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:

print.lightGoldenrod5Line( 'This is pretty' );
print.color221( 'This is the same color as above' );

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

config set modules.commandbox-bullet-train.packageBG=lightGoldenrod5
config set modules.commandbox-bullet-train.packageText=color21

The start command will scan your system and find a random port that is not currently in use to start the server on. This ensures that multiple embedded servers can run at the same time on the same host without collisions. Ensure any redirects in your applications take the port into account.

Any Port in the Storm

You may want to set a specific port to use-- even port 80 if nothing else is using it. Pass the HTTP port parameter to the start command like so:

It is also possible to save the default port in your server.json. Add a web.http.port property, or issue the following command:

Now every time you start your server, the same port will be used.

If the server won't start or is unreachable, make sure it's port is free with your operating system's netstat command. On Unix-based OS's:

HTTPS

You can start your server to listen for SSL connections too.

This will enable SSL without an approved SSL certificate. If you need an official certificate so you don't have to confirm your SSL connection you can add these entries

Although free certificates are available (e.g LetsEncrypt) this is not very convenient, because these certs are valid only for three months. Automatic renewal it is difficult if your dev site is not accessible from the web. For a few dollars a year (< 10) you can apply for a domain validated certificate from companies like Comodo, RapidSSL, Trustwave, Digicert, Geotrust and others or a reseller for these certs. For a domain validated certificate you need a valid domain which is under your control which means (depending on provider):

• mail is sent to domain owner

• or mail is sent to well-known administrative contact in the domain, e.g. (admin@, postmaster@, etc.)

• or you can publish a DNS TXT record

So, now you have a valid domain, you have to generate a SSL key and a SSL Certificate Signing Request. With the CSR you can apply for the certificate. Generating a key and CSR with openSSL

This will generate output and some questions, and will finally result in a key file named dev_mydomain_com.key and a certificate signing request (csr) named dev_mydomain_com.csr

You have to enter Country Name, State and City. Organization Name is preferably the same as the domain owner. Organizational Unit Name will not be checked, so enter something simple such as ICT Common Name is the hostname for your site, such as dev.mydomain.com You can skip Email Adress and optional company name. For development you don't need a challenge password, which means your key file is NOT protected. But don't give this key to others or protect it with a challenge password. If you protect your key you have to server set web.SSL.keyPass=MyChallengePassword Now you have a CSR, which you can submit at your SSL provider. They will send you a certificate file (*.csr), and probably one or more intermediate certificates. Create a new my.csr file and copy everything from your certificate file into it, and append the intermediate certificate(s). Now you have a valid my.csr certificate file and a key file. Place both files in a location accessible for your commandbox and enter the corresponding paths to web.SSL.certFile and web.SSL.keyFile

AJP

You can start your server to listen for AJP connections too.

A Gracious Host

Your application may rely on a specific host name other than the default of 127.0.0.1. You can set the host to anything you like, but you must add a host file entry that resolves your host name to an IP address assigned to your network adapter (usually 127.0.0.1)

If you have multiple IP addresses assigned to your PC, you can bind the server to a specific IP using the host parameter.

A server configuration can only have one host entry. If you require your server to be available on multiple IP addresses of the machine it runs on, you can set the host to 0.0.0.0. This will effectively bind the server to all network interfaces (including local).

Or save in server.json

Customize URL that opens for server

By default, CommandBox will open your browser with the host and port of the server. You can customize the exact URL that opens. This setting will be appended to the current host and port.

Or you can completely override the URL if your setting starts with http://.

If a server isn't starting, the first thing to run is the server log command. It will show you the console log for that server. Note, this dumps the entire log file to the console, which may be very large. We recommend using the tail or --follow tricks below.

Tailing and Following logs

If the log is very large, use the tail command to just see the last few lines of it.

To get a live stream of the console log from a running server, use the --follow flag and the command will continue streaming new lines to the console until you press Ctrl-C to stop.

You can also look at your server's access log (if enabled) and rewrite log (if enabled).

Start server in console mode

You can use the --console flag to the server start command to start a server in the foreground. The console log will be live-streamed to the CLI and the log will continue streaming as long as the server is running. Press Ctrl-C to stop the server and stop streaming the log file.

Debug Logging

You can get additional information about a server start with the --debug flag. When debug is set, the start command will not exit immediately, but wait for the server to come up and live stream the debugging information and server logs to the console while the server is coming up.

Maximum logging! (trace)

You may still really be having issues getting your server to start up correctly due to a setting not getting picked up, rewrites not working, or maybe a jar not loading. You can "drink from the firehose" so to speak by turning on trace level logging. This works best when starting the server via the console so you can watch the logging as it streams past.

These settings are used to configure CommandBox's endpoints.

endpoints.forgebox.APIToken

string

endpoints.forgebox.APIURL

string

This is the URL of the ForgeBox REST API. Remove this setting to use the default. If you wish to test submitting package in an environment other than production, you may point to our staging server. Note, this will funnel ALL ForgeBox calls to the staging server where your APIToken may be different.

If you need to use CommandBox behind a corporate proxy, these settings will be necessary for it to successfully connect to the Internet.

proxy.server

string

This is the URL of the proxy server on your network.

proxy.port

integer

This is the port to connect to on the proxy server.

proxy.user

string

This is the username to connect to the proxy server with, if required.

proxy.password

string

This is the password to connect to the proxy server with, if required.

These are some one-off settings that doen't really belong anywhere else.

nativeShell

string

This setting affects how CommandBox invokes the shell for the run command or when using the !binary shortcut. The default *nix shell used for the run command is /bin/sh but you can override it to use a custom shell. Set the full path to the shell binary.

tagVersion

boolean

Running the bump command from a Git repo will attempt to tag the repo unless you provide the tagVersion parameter. This setting provides a global default to prevent CommandBox from trying to tag Git repos.

tagPrefix

string

Running the bump command from a Git repo will tag the repo using the format v{version} such as v1.0.0 or v4.3.6. You can remove the v or swap it for another prefix using the tagPrefix parameter. Remember, another string like foo1.2.3 will not be parseable by CommandBox as a valid semver. This setting can be overriden by the tagPrefix parameter to the bump command.

artifactsDirectory

string

You can control where your artifact cache is stored with the artifactsDirectory config setting. This can be useful to keep your primary drive from filling up, or to point your files to a shared network drive that your coworkers can share.

FusionReactor is a popular tool for monitoring performance and gathering metrics for ColdFusion and Java J2EE applications. You may wish to use FusionReactor with the servers you start up via CommandBox. We've created a CommandBox module that will add FusionReactor support to your CommandBox servers which you can view here on ForgeBox.

https://www.forgebox.io/view/commandbox-fusionreactor

Installation

The CommandBox FusionReactor module is a separate project that you can optionally install by typing this: