Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
In this section you will find the release notes for each version we release under this major version. If you are looking for the release notes of previous major versions use the version switcher at the top left of this documentation book. Here is a breakdown of our major version releases.
Versions 5.x - Mar 2020 - May 2021
Versions 4.x - Jun 2018 - Sept 2019
Versions 3.x - Feb 2016 - Nov 2017
Versions 2.x - June 2015 - Nov 2015
Versions 1.x - Feb 2015
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.
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
In this section you will find the release notes for the 5.x version of CommandBox.
Version 5.4.2 - October 2021
Version 5.4.1 - September 2021
Version 5.4.0 - August 2021
Version 5.3.0 - May 2021
Version 5.2.1 - Dec 2020
Version 5.2.0 - Nov 2020
Version 5.1.1 - June 2020
Version 5.1.0 - May 2020
Version 5.0.0 - Mar 2020
Luis Majano is a Computer Engineer with over 15 years of software development and systems architecture experience. He was born in 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 . Luis resides in Houston, Texas with his beautiful wife Veronica, baby girl Alexia and baby boy Lucas!
He is the CEO of , 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 . You can read his blog at
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 grew up in southern Missouri where he systematically disassembled every toy he ever owned which occasionally led to unintentional shock therapy (TVs hold charge long after they've been unplugged, you know). After high school he majored in Computer Science with a music minor at (Olathe, KS). Today he lives in Kansas City with his wife and three girls where he still disassembles most of his belongings (including automobiles) just with a slightly higher success rate of putting them back together again.) Brad enjoys church, all sorts of international food, and the great outdoors.
Brad has been programming CFML since 2001 and has used every version of CF since 4.5. He first fell in love with ColdFusion as a way to easily connect a database to his website for dynamic pages. Brad blogs at () and likes to work on solder-at-home digital and analog circuits with his daughter as well as building projects with Arduino-based micro controllers.
Brad's CommandBox Snake high score is 141.
Jorge Reyes - ColdBox Aficionado
There is a fix for a regression introduced in 5.4.0 where updating the version of a CF engine doesn't work without forgetting the server first.
There is also an important security improvement to CommandBox servers. Thanks to Abram Adams for reporting this to Ortus so we could address it.
Note, the details of the security improvement have been tracked privately.
COMMANDBOX-1382 Java path shows up twice in "server info --verbose"
COMMANDBOX-1381 Updating server in-place keeps old web.xml path
COMMANDBOX-1375 recipe with multiple "install" instructions fails
COMMANDBOX-1380 Add additional interceptData to server interceptors
COMMANDBOX-1379 Update to WireBox 6.5.2
COMMANDBOX-1376 Immediately activate modules after installation
COMMANDBOX-1349 Improve multiselect DSL
COMMANDBOX-1120 Add JSON and Properties output for info command
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
.
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.
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.
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.
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 (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.
Welcome to the CommandBox Manual. CommandBox is a standalone, native tool for Windows, Mac, and Linux that will provide you with a Command Line Interface (CLI) for developer productivity, tool interaction, package management, embedded CFML server, application scaffolding, and sweet ASCII art. It seamlessly integrates to work with any of Ortus Solutions *Box products, but it is also open for extensibility for any ColdFusion (CFML) project as it is written in ColdFusion (CFML) using our concepts of CommandBox Commands.
CommandBox is maintained under the Semantic Versioning guidelines as much as possible. Releases will be numbered with the following format:
And constructed with the following guidelines:
Breaking backward compatibility bumps the major (and resets the minor and patch)
New additions without breaking backward compatibility bumps the minor (and resets the patch)
Bug fixes and misc changes bumps the patch
CommandBox is open source and bound to the LGPL v3 GNU LESSER GENERAL PUBLIC 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.
The CommandBox help and discussion group can be found here: https://community.ortussolutions.com/c/communities/commandbox/
We all make mistakes from time to time :) so why not let us know about it and help us out. We also love pull requests, so please star us and fork us: https://github.com/ortus-solutions/commandbox
CommandBox is professional open source software backed by Ortus Solutions, Corp offering services like:
Custom Development
Professional Support & Mentoring
Training
Server Tuning
Security Hardening
Code Reviews
Official Site: http://www.ortussolutions.com/products/commandbox
Source Code: https://github.com/ortus-solutions/commandbox
Twitter: @ortussolutions
Facebook: https://www.facebook.com/ortussolutions
Google+: https://google.com/+OrtusSolutions
Vimeo Channel: http://vimeo.com/channels/commandbox
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
Bug
COMMANDBOX-1374 Some installs unnecessarily write to the box.json
COMMANDBOX-1370 ConfigService::settingExists() fails in race conditions due to non-varscoped variables in JSONService
COMMANDBOX-1372 Support excludePaths in watcher DSL and watch command
COMMANDBOX-1369 Ensure Adobe wars have a seeds.properties file
COMMANDBOX-1368 Add tab complete for "env clear" command
COMMANDBOX-1367 Ignore empty startScript on server start
When you start an Adobe or Lucee CF Engine, the WAR CommandBox uses has a stock web.xml baked into it. Sometimes you may want to add custom servlets, servlet mappings, etc into your server. You can override the stock web.xml in part or in total with a file of your own which you specify in the server.json like so:
More info here:
https://commandbox.ortusbooks.com/embedded-server/configuring-your-server/web.xml-overrides
In addition to quoting parameter values, parameter names can also be quoted. This is useful when setting keys into settings or JSON files that have spaces, hyphens or special characters. Each of these examples are now supported:
More info here:
https://commandbox.ortusbooks.com/usage/parameters
Lucee Server has been updated to 5.3.8.201 and JBoss Undertow has been updated to 2.2.10.Final. The Lucee update, as usual, applies to the CLI as well as the default server you get when you run server start.
When you install a Jar via HTTP URL and the version number is baked into the URL, the jar endpoint now makes more assumptions about what the version of the package is that allows it to optimize the update checks and eliminate unnecessary downloads.
More info here:
https://commandbox.ortusbooks.com/package-management/code-endpoints/jar-via-http#semantic-versioning
Here are some fun commands for user interactivity in the shell. You can use these as part of a recipe or a nice "one-liner".
The ask command is similar to the ask() method in Task Runners. It requires an interactive terminal and will ask the user a question and return their answer. It is meant to be changed with other commands.
or with default values
or with masked input
Or fun stuff like this
The confirm command will ask the user a yes/no question and return a passing or failing exit code from the command based on the answer.
Remember the && operator will only execute the second command if the first command returns an exit code of 0.
More info here:
https://commandbox.ortusbooks.com/helpful-commands/ask-and-confirm
You can easily forget all servers which have not been started for a certain period of time with the server prune command. It accepts the number of days that need to have passed since a server was last started in order to prune it.
More info here:
https://commandbox.ortusbooks.com/embedded-server/manage-servers#prune-old-servers
Here are the full release notes for CommandBox 5.4.0
COMMANDBOX-1364 Cancelling a prompt with active job doesn't clear job logs
COMMANDBOX-1361 Param tab completion is off-by-one when piping
COMMANDBOX-1360 Can't list files in directory with brackets ( [ or ] ) in the name
COMMANDBOX-1356 forgebox timeout is too small when publishing packages
COMMANDBOX-1354 dir command returns no results in drive root
COMMANDBOX-1353 Summary over 200 chars in box.json causes error when publishing
COMMANDBOX-1352 Addition of Apache logging classes breaks 3rd party libs using it
COMMANDBOX-1350 Installing a system module as one-off command doesn't clear wirebox metadata cache
COMMANDBOX-1348 Commenting server rules doesn't work correctly in text files
COMMANDBOX-1346 CommandDSL doesn't handle struct args
COMMANDBOX-1344 create a server prune command
COMMANDBOX-1339 Server start can hang when CF engine blows up
COMMANDBOX-1338 Tab complete doesn't work after a pipe
COMMANDBOX-1337 Working dir of server custom menu items doesn't default properly
COMMANDBOX-1336 Error when setting failing exist code in Task Runner
COMMANDBOX-1334 updating commandbox to 5.3.1 via Homebrew breaks with a java error
COMMANDBOX-1333 Rewrite rule with query string doubles up question mark
COMMANDBOX-1332 printTable column validation breaks with spaces in list
COMMANDBOX-1330 Directory listing not showing folders properly when names are numeric
COMMANDBOX-1230 Certain Java installs fail version check
COMMANDBOX-1366 ask and confirm command to capture user input from shell
COMMANDBOX-1365 Improve version handling in JAR endpoint
COMMANDBOX-1351 Update to Lucee 5.3.8
COMMANDBOX-1347 Support dots in struct keys with set/show/clear commands
COMMANDBOX-1342 printTable custom header names for non-array input
COMMANDBOX-1331 Add printTable check for data with no columns
COMMANDBOX-1329 Sort column names in printTable --debug
COMMANDBOX-1362 Set env vars directly in server.json for local one-off overrides
COMMANDBOX-1011 Support web.xml Overrides
COMMANDBOX-1363 Update to Undertow 2.2.10.Final
JLine - 3.19.0
jGit - 5.11.0.202103091610-r
Launch4j - 3.14
JANSI - 2.3.2
When you configure libDirs for a server, CommandBox used to only load jar files found in the root. Now it will include sub directories which gives you more flexibility around how to install your jars.
In the previous release, we introduced a new helper for printing ASCII Art tables in your custom commands and task runners. We've taken this a step further and wrapped the table printer utiilty in a new command so you can use it from the CLI directly. We've also expanded its functionality to accept ANY data in as JSON and it will marshall it into a query for you. This means it can be a query, an array of structs, an array or arrays, and more. You can now get quick and easy visualization of any data right from the CLI or in builds.
As if the previous command isn't cool enough, we've also added a new "sql" command which will also accept any sort of data as JSON, marshall it into a query object and allow you to alias, filter, order, and limit the rows on the fly using CFML's query of queries!
The sql command works very nicely with the new tablePrinter command, and truly makes JSON a first class citizen of the CommandBox CLI.
We've made a small adjustment to the print.table() helper that was introduced in CommandBox 5.3.1 as follows. The old method signature is
And the new method signature is:
The parameters to the new printTable command matches the NEW method signature of the print.table() helper as well.
When working with XML in the REPL, formatting is now applied when the XML is printed out to the console, making it easier to read (same as JSON)
COMMANDBOX-1320 Server stop doesn't message user when it fails
COMMANDBOX-1319 Stop loading cfusion/lib in system class loader
COMMANDBOX-1318 5.3.0 errors with commandbox-dotenv 1.x versions due to WireBox change
COMMANDBOX-1314 When building Lucee war from local jars, seeded web.xml file is ignored
COMMANDBOX-1311 Table printer error with no rows
COMMANDBOX-1310 update '{slug}' fails as it is trying to print the package version and its dependencies.
COMMANDBOX-1308 Relative Web Alias Behavior (regression)
COMMANDBOX-1307 jq doesn't resolve file paths to current working directory
COMMANDBOX-1303 CFEngine adobe - Could not initialize class coldfusion.vfs.VFile when using s3 protocol
COMMANDBOX-1328 Improve performance of piping large strings to "cfml" command
COMMANDBOX-1317 Format XML in REPL
COMMANDBOX-1316 Change default CLI JSON representation of query to array of structs
COMMANDBOX-1306 Allow upgrade command to pull stable versions when CLI is a prerelease version
COMMANDBOX-1305 Update bundled java libraries
COMMANDBOX-1302 app.libDirs does not load jars/classes recursively from sub folders
COMMANDBOX-1210 Allow for relative URLs when defining trayoption elements
COMMANDBOX-1194 Add Libraries To Runwar Necessary For URLRewrite Proxy
COMMANDBOX-1324 New "printTable" command to add CLI usage of table printer
COMMANDBOX-1323 New "sql" command to filter tabular data with SQL
COMMANDBOX-1321 Add --verbose to 'server stop' to see raw output
COMMANDBOX-1309 Add printTable command that proxies to print.table() helper
This release was primarily to address a regression in 5.1.0 affecting Mac OS users who tried to start Lucee servers. If you see an error similar to this on a Lucee server and you're running a Mac and CommandBox 5.1.0, then this release will fix it for you.
If you are upgrading from CommandBox 5.1.0, there are only a handful of tickets which are listed below. If you are updating from an earlier version of CommandBox, please check out our and release blogs.
[] - Overzealous gitignore matching of parent directories when zipping up for ForgeBox storage
[] - Enabling SSL results in some CFHTTP requests to fail.
[] - writedump failing in Lucee
[] - File globbing matching partial file names
[] - Allow for verbose startup without debug logging of requests
There is now a new "forgebox logout" command you can use for testing or just to remove your API token from the local CLI.
You can change CommandBox's default tab completion to be an inline list that follows your cursor. This setting requires you to close and re-open the shell to take affect.
Read more here:
We've added better debugging information for Server Profiles. If you add the --verbose flag to your server start, you'll be able to see what profile was detected for your server, and what baked-in rules have been turned on as a result.
We've added a new Single Server Mode you can enable in the CLI to make using CommandBox in Docker images easier.
Read more here:
Here are the release notes for the 5.2.1 release.
Every Config Setting can be overridden by convention by creating environment variables in the shell where you run box
. This is ideal for CI builds where you want to easily set ForgeBox API keys, or tweak settings for your build.
More Info:
Every server setting can be overridden by convention by creating environment variables in the shell where you run box
. This is ideal for CI builds where you want to easily set ports, or tweak settings for your build.
CommandBox now has out-of-the-box support for the HTTP/2 protocol. It is always enabled by default and browsers will use it when you're serving over HTTPS.
We've added a new jq command which behaves roughly like the bash counterpart. You can pipe in JSON, or read the JSON from a file and apply a JSON query against it which can be used to filter, massage, rewrite, map, or filter the JSON into a new JSON object.
We've also added the ability to specify powerful jq filters to the "package show", "server show", and "config show" commands directly. Just prefix your filter with the text "jq:" like so:
For this to work, you must also configure your AJP proxy in your web server to send the same secret!
We've updated the version of WireBox inside the CLI and now have access to the AsyncManager for sweet threading and scheduled task support.
CommandBox is using an AsyncManager scheduled task thread now to redraw interactive jobs and progress bars. Look out for some new eye candy hiding in your server starts and package installs!
The print helper in commands and Task Runners has a new toy that will print ASCII representations of tabular data thanks to a pull request from Eric Peterson. You can see it in the output of the outdated command.
And you can use it in your Task Runners like so:
When scaffolding ColdBox handlers, we have support for ColdBox 6.x REST Handlers now.
You can enable extra Resource Manager Logging when troubleshooting file system issues:
You can force case sensitivity on a Windows server:
You can force case Insensitivity on a Linux server:
You can enable a cache of file system lookups of servlet paths. This is only for production and will eliminate repeated file system hits by your CF engine, such as checking for an Application.cfc file on every request, or testing where the servlet context root is. Standard Adobe ColdFusion installations have a similar cache of "real" paths from the servlet context that is tied to a setting in the administrator called "Cache Webserver paths" but that setting is not available and does not work on CommandBox servers for some reason. This setting would apply to any CF engine.
When using a CommandBox web server in production, you may wish to force your users to visit your site over HTTPS for security (and for HTTP/2 to work). However, it is desirable to still have your web server listening on HTTP so a user just typing your address in his browser can still connect to HTTP and then redirect. CommandBox can be configured to redirect all HTTP traffic over to HTTPS with the following setting.
If you want to go one step further, you can add a Strict-Transport-Security
header to your site. This instructs the browser to automatically use HTTPS every time the user visits your site again.
CommandBox won't use ANSI color formatting when running inside of a non-interactive terminal. However, build servers such as Gitlab or Jenkins (via a plugin) support ANSI color sequences. You can force CommandBox to use colored text output with this new setting:
One of the common hangups for people dealing with Lucee Server and Adobe ColdFusion CF Engines versions, is that CommandBox follows the npm-flavor of the semantic version spec and expects
instead of
So we've loosened our sem ver library to treat the 4th number as a build ID if there is no plus sign in the version (instead of just discarding the 4th digit as the spec requires)
Most modern browsers allow you to make up any subdomain you want before localhost such as mySite.localhost and will simply resolve them to localhost (127.0.0.1) even without a hosts file entry. CommandBox now supports using these domains and will bind your server's ports to localhost even without using the commandbox-hostupdater module.
You can customize where CommandBox lives by placing a commandbox.properties file next to the box binary. We have better support for relative paths now so you can have portable CommandBox installations such as a thumb drive.
The only known breaking change in this release is if you try to start two servers on the same HTTP port. Previously, CommandBox would just ignore the port on the second server and choose a random port. Due to the confusion that can cause, CommandBox will now throw an error. If you want to override an explicit port locally, set the port to an empty string or a 0 and CommandBox will choose a random port for you. For example, if you are using the commandbox-dotenv module, you can put this line in your project's .env file to override the port in your server.json
If you have a server with the server.json outside of the web root and at least one relative web alias, the alias will not work on the first start of the server. The workaround is to change the web aliases to be relative to the folder that the server.json lives in.
Some users receive the following error when starting CommandBox after updating:
If you see this, it means you have an older version of the commandbox-dotenv module installed that is not compatible with the new version of WireBox inside CommandBox. To fix, delete this folder out of your CommandBox home:
Now the CLI will start and you can install the latest version of dotenv.
Here is the list of all tickets included in the 5.3.0 release.
Java 14 is now supported in CommandBox 5.1.0. In order to support Java 14, we had to stop using Pack200 which means the binary sizes have grown a little. The good news is CommandBox will start up a little faster on its first run since there's less to unpack now.
You can start up a lightweight server that only serves static files now with CommandBox.
In pursuit of the smallest possible Docker images, we have CommandBox light which is built on Lucee Light. We also have a box "thin" binary you can swap out with the full self-extracting binary when using CommandBox in custom docker images. Check out Pete Freitag's to see both of these in use in a super tiny 78 Meg docker image. More docs here:
If you're using box in an integration where you want it to start up in a specific working directory, there is a new bootstrap CLI arg for that.
You've always been able to specify custom menu items in your server.json or global config settings, but we've kicked it up a notch. Not only can you contribute to existing sub menus now, you can execute arbitrary native commands synchronously or async.
Here's the full list of tickets closed down in the 5.1.0 release.
Even though this is a new major version, it should be very backwards compatible. CommandBox proper has no known backwards compatibility issues we're aware of, but note we've bumped libraries like Lucee Server, Undertow, and Java support, so you may notice differences due to these 3rd party lib updates. For example, one in Lucee 5.3 (which now powers your default server) is how page output buffer is handled.
You should be able to simply replace your box.exe binary and run it to get the same in-place upgrade you're used to. If you run into issue, you can try removing the "engine" folder in your ~/.CommandBox folder and try again. If you need to downgrade for any reason, replace the box binary with the old version, remove the "engine", "cfml", and "lib" folders in your CommandBox home and they will get re-created on the next run.
You may also notice the box binary is larger now. From 44 Megs up to 77 Megs. This is a regrettable byproduct of us turning off the Pack200 process we used to run against the Lucee jar. Lucee seems to have some bugs that causes it to re-download a bunch of OSGI bundles when we compress them and we can't figure it out, or get support on the matter, so for now we're just not compressing as much stuff. This was a huge blocker for anyone needing to run CommandBox on a PC with no external internet access as Lucee provides no mechanism to turn off it's auto-download behavior.
And finally, if you have installed any custom OSGI bundles into your CLI, they will be wiped by the upgrade process now. We didn't want to have to to do this, but Lucee has bugs that cause errors when doing in-place upgrades with the old OSGI bundles left in place and we couldn't get it fixed, so this was the only way to ensure in-place upgrades would "just work" without errors. We are leaving the Lucee engine folder, so any settings you may have put into your CLI should remain in place.
There's a lot of new stuff in CommandBox 5.0.0. Here's an overview. One of the biggest new "features" is you can finally use CommandBox on Java 11+. This was not possible in CommandBox 4.x due to the version of Lucee not fully supporting newer versions of Java. Now that Lucee has been bumped to 5.3 (see below) you are free to leave java 8 behind for the CLI. Note if you're using CommandBox to start up older versions of Adobe CF or Lucee/Railo, you may still need to use java 8 specifically for your servers.
Let's start with the library updates. For the most part, all the jars we bundle are a "black box" but in reality, every update is usually for new features, fixes, or security patches. Here's an overview of the new libs:
WireBox 5.6.2
JLine 3.13.0
Runwar 4.0.3 (major bump from 3.x)
JBoss Undertow 2.0.27.Final (major bump from 1.x)
JGit 5.5.1.201910021850-r
Lucee 5.3.4.77("major" bump from 5.2)
AdoptOpenJDK jdk-11.0.6+10 (In the JRE-included download) (major bump from 8.x)
You can now use user/pass or personal access token authentication when cloning Git repos over HTTPS. This has been tested with Github and Gitlab and is an alternative to SSH keys. Please check the docs, as Github and Gitlab both expect slightly different inputs.
There is a new Lex installation endpoint to help you acquire Lucee Extensions your app needs via the "install" command or a dependency in your box.json file. If the current directory has a Lucee server in it, CommandBox will install the extension file directly into your server's "deploy" folder (server context)
The auto-install feature into your server will work on any Lex package, even one coming from ForgeBox:
Tuning your server is easier now. You can configure your Undertow worker-threads setting with first-class server.json property
Which gives you this in your server.json
We've also unlocked a method for you to set ANY valid Undertow option or XNIO option. So if Undertow supports it, you can configure it!
We've added a new experimental feature that lets you create a batch file, powershell script, or bash shell script that directly starts a server with the exact settings that you get from "server start". This is for you to create super-optimzed startups in Docker or Service that bypass the CLI steps and "lock in" the settings. No server.json or CFConfig, or dotenv code will be processed, but you will have a fast streamlined start that is the same every time. Couple this with our new "dryRun" flag on server start that will unpack the CF engine, but not actually start the server, and you can create your customs start script like so:
The Globber helper can now take more than one globbing pattern. This also means every built-in command in CommandBox that takes a globbing pattern, can now take a comma delimited list of patterns. We've also added an exclude list of globbing patterns to the dir command as well.
We've got a couple new handy commands to help you from the command line, "unique" (modeled after the Bash "uniq" command)
And "sort" (modeled after the Bash "sort" command)
The "grep" command has received a "count" parameter if you just want the count of lines that match the regex (or no regex will count all lines)
The tray icon for your servers now has a new option under the "Open" menu that will open up the file system folder where the server home lives. This is nice for finding your CF Engine's log files.
There are a lot of bug fixes and even more enhancements I didn't cover above. You can read the full release notes here:
There are a number of pretty exciting new features and a pile of bug fixes. And as usual, input from the community via Pull Requests. Huge thanks to Pete Freitag, Kai Koenig, Matthew Clemente, Bobby Hartsfield, Scott Steinbeck, Daniel Mejia, and Miguel Mathus! Here's an overview of the new stuff in 5.2.0
We know library updates are boring, but they are important and we want you to know we take them seriously. Keeping up-to-date ensure you have the latest fixes and security updates from all the third-party libs we bundle in CommandBox.
Here's an overview of what we updated in CommandBox 5.2.0.
Upgraded Runwar from 4.1.2 to 4.3.8
Upgraded JBoss Undertow from 2.0.27.Final to 2.2.0
Upgraded UrlRewritesFilter to Ortus fork 5.0.1 with custom fixes
Upgraded jboss-logging from 3.2.1.Final to 3.4.1.Final
Upgraded jboss-logging-annotations from 2.1.0 to 2.2.1.Final
Upgraded JCabi Log from 0.18 to 0.18.1
Upgraded Apache HttpClient from 4.2.6 to 4.5.12
Upgraded Apache httpmime from 4.2.6 to 4.5.12
Removed unused JOpt Simple 5.0-beta-1
Removed unused Gson 1.2.3
The Undertow bump is a minor update, but a pretty big deal. Ortus sent three pull requests to the core Undertow project fixing bugs and adding predicate logging. All of our pulls were accepted and merged into the core Undertow project and released in the 2.2 release.
Read more about library updates here:
This is a feature that we expect to grow in the future. We've started it out simple, yet powerful but left a lot of room to build on it. The two main goals here are
Make CommandBox secure-by-default so a server shoved in production comes nice and locked down
Makes it very easy for you to toggle off all the security stuff for development
CommandBox now has profiles you can assign to a server when you start it to configure the default settings. This is to provide easy secure-by-default setups for your production servers, and to make it easier to switch between a development mode and production mode.
There are 3 currently supported profiles. Custom profiles will be added as a future feature.
Production - Locked down for production hosting
Development - Lax security for local development
None - For backwards compat and custom setups. Doesn't apply any web server rules
In production mode, CommandBox will block access to your CF admin to all external traffic, will block all common config files such as box.json or .env and will block, the "TRACK" and "TRACE" HTTP verbs
You can set the profile for your server in your server.json
Or you can specify it when starting the server like so:
If a profile is not set, CommandBox looks for an environment variable called "environment" or it checks to see if the site is bound on localhost to try and guess the correct profile for you.
We've also added some new flags in your server.json to fully customize how your profile behaves.
Read more about Server Profiles here:
This is huge-- probably the biggest chunk of work, and it's actually what makes the server profiles above even possible! It's always been possible to perform basic lock downs with a custom rewrite file, but we've exposed an amazing built-in functionality of Undertow called the Predicate language. It allows you to create ad-hoc rules that apply to your server to provide any of the following:
Security - Block paths, IPs, or users
URL rewrites - Rewrite incoming URLs to something different
Modifying HTTP requests on the fly - Set headers, cookies, or response codes
An example of a server rule using Undertow's predicate language to block access to any box.json files looks like this:
One of the best things about these rules, is they don't have to be in a single monolithic XML file. Instead they can come from
An array of ad-hoc definitions in your server.json file or config server defaults
one or more external JSON or text file specified in your server.json or config server defaults
Built in CommandBox server profiles (see above)
Custom 3rd party CommandBox modules that contribute rules on-the-fly (time to get creative!)
Here's some examples of what can be in your server.json
CommandBox also registers some custom rules in Undertow you can use for your CF apps:
There are lots of new docs on this. Read more about Server Rules here:
The more we use Task Runners for builds, scheduled tasks, and utilities, we've seen the need to have lifecyle events in the same manner as the preHandler and postHandler sort of stuff in ColdBox MVC. Now if a task runner has methods of this name, they will be executed automatically.
preTask - Before any target in the task
postTask - After any target in the task
aroundTask - Wraps execution of any target in the task
pre- Before a specific target
post- After a specific target
around - Wraps execution of a specific target
onComplete - Fires regardless of exit status
onSuccess - Fires when task runs without failing exit code or exception
onFail - Fires if exit code is failing after the action is done (always fires along with onError, but does not receive an exception object). Use this to respond generally to failures of the job.
onError - fires only if an unhandled exception is thrown and receives exception object. Use this to respond to errors in the task. Does not fire for interrupted exceptions
onCancel - Fires when the task is interrupted with Ctrl-C
The lifecycle methods are very powerful and can be controlled via whitelist and blacklists to control what targets they execute for. "Around" events are very easy to use thanks to the use of closure. There's a lot more details in the docs.
Read more about Task Runner Lifecyle events here:
The default namespace when using the $ {foo}
system setting expansion syntax is box environment variable, Java system properties, and OS environment variables.
It is also possible to leverage built-in namespaces to allow expansions that reference:
server.json properties
box.json properties
arbitrary JSON file properties
Config settings (like the config show command)
Server info properties (like the server info property=name command)
Other properties in the same JSON file
This gives you a lot more power now to be able to create dynamic configuration in your JSON files and even from the command line. Here are some examples:
And one of the coolest things is this implementation is driven by a new onSystemSettingExpansion interception point and completely extendable! That means you can write a module that powers something hypothetical like this:
Read more about System Setting namespaces here:
CommandBox has had the ability to enable/disable GZip compression in Undertow for a while. Now you can fully control when it activates based on the type or size of file, etc. This feature utilizes the same Undertow predicate language that we introduced above.
Read more about GZip Compression Control here:
This is a fun one. There are some specific commands that make use of the Watcher library in CommandBox such as testbox watch and coldbox watch-reinit. However, there is also now a generic watch command that will run any arbitrary command of your choosing when a path matching your file globbing pattern is added/updated/deleted. Use this to build custom watchers on-the-fly without needing to touch any CFML code to write a Task Runner.
That command will echo out "config files updated!" every time a JSON file gets changed in the current directory. Here's a more complex one:
That one will list every new file that's added in this directory and all sub directories.
Read more about the generic watch command here:
There are a handful of features in CommandBox that will open URLs for you in your default browser. We've had requests to allow the browser in use to be customized, so we've reworked all of that logic, consolidating it in some places and now you can control what browser CommandBox uses. To change the default browser for all URL opening functions use this:
Supported browsers are:
firefox
chrome
opera
edge (Windows and Mac only)
ie (Windows only)
safari (Mac only)
konqueror (Linux only)
epiphany (Linux only)
And you can even dial in a browser on demand for the browse and server open commands.
Read more about setting the default browser here:
Here are some honorable mentions.
The CommandBox Tuckey rewrites allow an .htaccess file that uses the mod_rewrite style syntax of rewrites. Previously, use of flags such as these didn't work:L
We've added a "restart" option to the tray icon that does exactly what you think it does.
There's a new trick supported in CommandBox's shell that we've borrowed that allows you to change directories and go "up" more than one directory with less typing:
You can now pipe the output of a previous command in CommandBox directly to a native binary like so:
In this case, clip
is a Windows binary that will read the standard input and place that text on the clipboard.
We work hard to make every CommandBox upgrade backwards compatible. There's a couple things that you may notice different in this release. They're both done to put security first and can be modified to get your original behavior back.
Since the CF Administrator is now blocked for traffic not coming from localhost when in production mode, you may need to explicitly open up the CF admin to make it accessible again if you needed it open to the public on a production server. Even with the profile set to production, you can activate just the CF admin like so:
The web server built into CommandBox will now only serve static files if their extension is found in a whitelist of acceptable files. This is to prevent prying eyes from hitting files they shouldn't be able to access on your server. The current list of valid extensions is:
If you have a common static file you need to serve, you can add your own custom extensions to the list like so:
And if you think we've missed an obvious one that deserves to be added to the default list, please let us know.
Here's the full list of tickets in the 5.2.0-RC.1 release.
[] - Installing via lex endpoint uses incorrect file extension
[] - Location of predicate file is in a folder that the Docker finalization script deletes
[] - Command alas for run command doesn't expand properly
[] - Add config setting to activate JLine's AUTO_MENU_LIST
[] - forgebox logout command
[] - verbose server start output for profile and security settings
[] - Extend ${} scopes to apply to any getSetting() call or "env show" command
[] - Modules aren't unloaded on reload or shutdown
[] - Add debug output that shows location of commandbox.properties file on start
[] - Add single server mode for CommandBox in a Docker container
[] - Add Testbox runner to sensitive paths in production profile
[] - Use UTF-8 when reading files with "cat" command
More Info:
More Info:
Thanks to a massive effort from Scott Steinbeck, the CFML world has a new of the , which is what powers the popular . We've plugged this new library into CommandBox and exposed it in the following ways.
The jq command and JMES spec are very powerful and probably do ! Make sure you check out the docs for more ideas.
More Info:
CommandBox's AJP listener (provided by Undertow) is already protected against the . However, if you would like to set up an AJP secret as well to ensure all requests coming into the AJP listener are from a trusted source, you can do this by setting the web.ajp.secret
property.
More info:
More Info:
More Info:
More Info:
More Info:
More Info:
web server aliases in server.json should be relative to the folder of the server.json
${Setting: serverinfo.foo not found} expansions don't work in a folder that's not the web root
Re-using same server.json with two names doesn't work
Corrupted WireBox metadata cache file will prevent CommandBox from starting
HTTP2 Additional Port Handling and Flexibility
REPL & Command highlighters don't handle square brackets [] well
JVM arg ending in backslash doesn't work
Coldbox Watch-Reinit Watches Unwanted Folders
Package installation doesn't always optimize duplicate packages
Globber.count() bombs if run after .asQuery()
Starting lucee@1.2.3 will use light-light when using CommandBox Light
Loading class files in task runner doesn't work
variables scope doesn't persist between task dependencies
tokenreplace removes BOM from files
trayOptions.json not respecting serverHomeDirectory
Server status not always correct.
Add singleServerHome option to not auto-deploy different versions of servers
Improve error message if version isn't found in ForgeBox
Loosen parsing of build ID in semver
Treat empty HTTP port the same as 0 (chooses random port)
Remove runwar hack that sets java vesrion
Runwar timesout when Lucee's new warmup flag is used
Add option for PID file
Allow generic override of server start settings via env vars or java sys props
Have parser ignore quotes inside a token
Cache "/" path lookup in Runwar's mapped resource manager
Add setters for run() arguments in CommandDSL
Default embedded server only needs to copy lucee.jar
Have outdated
also show latest version of a package
Integrate AsyncManager into CommandBox
Upgrade to latest WireBox 6.x
Bundle testbox in testbox module to prevent auto download
Halt server start if asked for port is in use
the git bullet train car disappears while current working directory is not the root project folder
Support AJP secret in Undertow
Rethink the way the screen is redrawn upon extensive installs so it can be fluent on all screen sizes
Can't link package if no modules are installed
New first-class setting to enable HTTP2
Comment out the default environment vars in .env when createing a new coldbox app
Allow server rules to be commented out with #
Allow servers to use random.localhost domains
Integrate JMES JSON filtering
Debug when lucee-extensions don't find Lucee server
Allow JSON service to create implicit arrays
Add config setting to enable ANSI colors in dumb terminals
Allow generic override of config settings via env vars or java sys props
Add --json flag to server list
Add HTTP redirect options
Add optional servlet path cache in Runwar
Allow caching of task runners
Support for generating ColdBox RESTHandlers
Support default module export as @moduleName,
Allow commandbox_home to be relative
[] - Runwar deadlocks when using Lucee server warmup flag
[] - Server start console output isn't always formatted correctly
[] - Boolean env var causes error on server start
[] - Output of foreach can't be piped
[] - Lucee Extension install doesn't recognize Lucee Light
[] - Package unlink command misspelled parameter moduleDirectory as moduleDrectory
[] - Package link command misspelled parameter moduleDirectory as moduleDrectory
[] - Tab complete doesn't work on Windows paths with backslashes
[] - CommandBox Watcher shows error on Ctrl-C
[] - Extension management doesn't "recognize" a Lucee server started with --dryRun
[] - Downgrading a package with install doesn't work without --force
[] - The run command doesn't always seem to kill interactive binaries
[] - Relative paths incorrect in drive root on *nix
[] - Using a warPath of ./ gets normalized to "" and then ignored in subsequent starts
[] - native commands with * can fail due to missing regex escape
[] - Incorrect serverInfo for a server that hasn't started
[] - Allow arbitrary actions for menu items
[] - Allow to start a pure HTML server
[] - Update ColdBox Templates to new standards
[] - Allow default working dir of box to be overridden
[] - Create box-thin binaries that don't bundle any libs
[] - Create CommandBox Light built that uses Lucee Light jar
[] - Add two new methods to commands for working with async futures: getCurrentThread() getThreadName()
[] - TestBox run commands now support the outputFormats argument to allow you to output post-test reports in many formats
[] - TestBox revamped UI for the CLI reporter
[] - Add Java info debug to box binary
[] - Add Java version as info log
[] - Provide way to disable server instance icon in MacOS dock
[] - Add --full flag to dir command to output full path
[] - Rework the server list command so it is more performant
[] - Bump to Lucee 5.3.6.61
[] - Tab complete for sort options in dir command
[] - Have the ProgressableDownloader send an Accept header
[] - Don't overwrite lucee-server.xml file when updating libs
[] - Auto-detect *unix distros with non-bash shells
[] - Copy lco files so Lucee server can start on CommandBox Light
[] - Reset console window title after `run` executes a process
[] - Remove extra stashes on url paths when servlet init params starts with WEB-INF
[] - Tray Icon not displaying on Debian8
[] - X Window Errors
[] - "Coldbox create resource" uses wrong paths on Windows
[] - urlrewrite.xml has file size of 0 on docker restart but not regular start
[] - CommandBox instances crashing because of TrayIcon rendering
[] - CommandBox always reads STDIN even when in non-interactive mode
[] - Using zsh exits out of CommandBox when running a binary command
[] - Shebang scripts no longer work without .cfm extension
[] - If custom rewrite file is already in correct destination, runwar overwrites it as 0 bytes
[] - worker-threads setting no longer has any affect
[] - Tray icon not showing in Ubuntu 18.04
[] - Undertow error output when starting server
[] - [RUNWAR] Tray menu placeholders such as ${Setting: runwar.port not found} are not replaced in sub menus
[] - regex string index out of bounds exception
[] - URL Rewrites fire incorrect on URL containing a space
[] - Browser doesn't open when server start
[] - Host updater does not work
[] - Server doesn't stop on Windows
[] - ConcurrentModificationException with undertow?
[] - Restrict /dumprunwarrequest to be used only on Unit Testing
[] - Remove trailing slash from Adobe updates path
[] - Default command parameters don't work on commands in namespaces
[] - Command DSL has unexpected behavior with equals sign in positional tokens
[] - Tab complete for negated flags isn't complete
[] - box fails to open in vSphere Web Client console due to outdated JLine jar
[] - Server start doesn't correctly expand relative Java Home directory
[] - slashes into the servlet init param paths
[] - Tray icon doesn't disappear on Windows when server stops from CLI
[] - Install dependency from box.json with env var placeholder gets overwritten with actual value
[] - coldbox create resource command ignores specsDirectory argument
[] - foreach cannot be interrupted with Ctrl-C
[] - validate non-numeric exit codes from the "exit" command
[] - Task Runner's loadModule() fails on path with period
[] - Tasks don't treat return 1 and setExitCode( 1 ) the same
[] - When a task sets a failing exit code, no output is sent to console
[] - Commands that set a failing exit code don't raise proper exception
[] - foreach, grep, and sed only break on chr(10)
[] - Ability to install/uninstall box server services
[] - Server command to explode server war but not start it
[] - Set any valid XNIO option
[] - Add generic feature to set any valid Undertow option
[] - Allow no rest mappings to be supplied
[] - Tab completion for task targets
[] - New TestBox commands: generate visualizer and generate browser
[] - Update ColdBox module templates for 5.0 standards
[] - Expose Undertow worker-threads setting with first-class server.json property
[] - Support HTTPS username/password auth
[] - Option for server start to write file with full start args for direct Runwar call
[] - Add lex endpoint for installing Lucee extensions
[] - Add unique command to filter out duplicates rows of input
[] - Add sort command to sort rows of input
[] - Make sure the build works
[] - Document Setup in the Repo
[] - Vet all changes on Runwar since April 25, 2018.
[] - Enhance Globber to take more than one pattern
[] - Enhance Globber to have exclude patterns
[] - Update CLI to Lucee 5.3 and test Java 11
[] - Change CommandBox build to pull Ortus build of Runwar
[] - Output Runwar version and jar path in "info" command output
[] - Need Config for Max Thread Request at runwar
[] - Enhance dir command with new Globber features
[] - Optimize installation of packages with createPackageDirectory set to false
[] - Improve performance of print buffer by using String Builder internally
[] - Add --count flag to grep command
[] - Update CommandBox to Runwar 4.0.0
[] - Upgrade to JGit 5.5
[] - Tie into FusionReactor to report transactions for tasks, commands, etc.
[] - Default location to forgeboxStorage for package init command
[] - Improve default package naming of jar endpoint
[] - Add option to tray menu to open server home directory
[] - Update to latest WireBox
[] - Stop outputting extra line break for commands with no output
There are TON of built in predicates and handlers your rules can use. We've documented some of them :
[] - Tuckey UrlRewrite DTD version issues
[] - when installing a package which doesn't exist, commandbox claims forgebox is unreachable
[] - Remove mail-4.1.1.jar from runwar's lib dir
[] - "testbox run" output garbled on Windows (wrong encoding)
[] - UndertowOptions and XNIOOptions don't work for Long type
[] - HTTP endpoint leaves a zip file in the CommandBox temp folder
[] - url rewrite no longer works
[] - Piping a command into run does not execute interactivley
[] - Support flags on .htaccess file for Tuckey rewrites
[] - Restart server via tray icon
[] - Stop expanding /WEB-INF paths in servlet init params
[] - Allow configuring default browser to use when opening a URL
[] - Add a preInstallAll and postInstallAll interception points when running an `install` command
[] - Add Task Runner lifecycle events
[] - Generic watch command
[] - When starting an already-started server, offer to open the existing one instead
[] - Add directory expansion command for going back multiple directories
[] - Add built-in predicates and handlers for undertow for easier lockdown
[] - Add "profile" setting to help default security settings
[] - Allow standard input to be piped to native binaries
[] - review all the runwar dependencies and check for outdated ones
[] - Block TRACE HTTP Verb by default
[] - Implement web server rules in Undertow
[] - Add an option to console log output without ANSI codes
[] - Migrate to AdoptOpenJDK API v3
[] - Move ANSI logging format from Runwar to CommandBox
[] - Automated flag negation hint is the same as the hint for the flag itself
[] - Default server menu actions working directory to web root
[] - Expand working directory when specified for a menu item
[] - Validate incoming version for bump command
[] - Programmatic skipping of package install via interceptor
[] - Adding support for installing lex files from file or unc paths
[] - Add File Filtering For GZIP Compression
[] - Allow default server java version to be cleared
[] - Add setSystemSetting() to BaseCommand
[] - "testbox run" command - show tag context for global bundle exceptions
[] - Add --trayEnable flag to server start
[] - Allow ${} system setting expansions to have extendable namespaces
[] - Improve verbose output of JVM args if args contain " - " in them
[] - forgeboxstorage default ignores are over-aggresive
[] - If native command is piped into RUN, allow the output to be piped again
[] - Load predicates in Runwar
[] - Pass Predicates as part of Server Start in CommandBox
[] - Add default server rules/predicates in CommandBox for default lockdown
[] - Improve logging in Undertow for execution of predicate handlers
[] - Track/address Undertow tickets
In this section you will find the release notes for the 4.x version of CommandBox.
Version 4.8.0 - Sept 2019
Version 4.7.0 - June 2019
Version 4.6.0 - Mar 2019
Version 4.5.0 - Dec 2018
Version 4.4.0 - Nov 2018
Version 4.3.0 - Oct 2018
Version 4.2.0 - Aug 2018
Version 4.1.0 - Jun 2018
Version 4.0.0 - Jun 2018
Here's the full list of what we've packed into the 4.7.0 release. Click any ticket link for more details.
[COMMANDBOX-962] - CommandBox not recognizing implicit folder endpoint
[COMMANDBOX-967] - Update semver for fix in prerelease comparison
[COMMANDBOX-970] - Tokenizer breaks "run" command with odd syntax
[COMMANDBOX-972] - init-wizard command is incorrectly aliasing as init
[COMMANDBOX-978] - File watcher that modifies the file system triggers the watcher again
[COMMANDBOX-985] - bump command doesn't work on a submodule
[COMMANDBOX-986] - Text on standard input causes banner and prompt to be blank
[COMMANDBOX-988] - Inconsistent behavior of "run" command.
[COMMANDBOX-989] - Tab completion incorrect for some partial command names
[COMMANDBOX-990] - Interactive jobs are not thread safe
[COMMANDBOX-956] - Leading zeros in semver prevent them from being matched
[COMMANDBOX-957] - Allow --verbose flag on uninstall command
[COMMANDBOX-958] - Add --roundup flag to indents command
[COMMANDBOX-959] - JSON Schema for box.json
[COMMANDBOX-968] - Update JGit to 5.3.0.201903130848-r
[COMMANDBOX-969] - Update Jline to 3.10.0
[COMMANDBOX-971] - Remove Riaforge endpoint Rince riaforge is dead
[COMMANDBOX-973] - Modify default box.json from "init" command
[COMMANDBOX-974] - Add box: namespace for compat with Coldbox injection DSL
[COMMANDBOX-976] - Improve debugging and error messages for custom ForgeBox endpoints
[COMMANDBOX-979] - If the test runner produces a 500 exception during watcher no output is shown
[COMMANDBOX-982] - support for Environment variables in "Key" names
[COMMANDBOX-983] - Make env vars in CommandBox visible to native OS binaries
[COMMANDBOX-984] - Launching VSCode from ConEMU screws up the integrated terminal
[COMMANDBOX-987] - Keep relative installPaths in box.json
You can now cache downloads using the HTTP(S) endpoints using the following syntaxes:
This will speed up builds.
Thanks to a pull request from John Berquist, we've borrowed a Bash and Powershell feature of being able to change back to your previous working directory by typing this:
Thanks to more pull requests from John Berquist, you can use file and folder based tab completion when typing native binaries from CommandBox
And tab completion also works better now when typing a quoted string such as a file path that contains a space. This is a huge timesaver!
Package scripts that are fired from internal interception points, can access any intercept data via environment variables. This example writes a file into a server home directory when the server starts, using an environment variable to dynamically find the correct path.
Here are the full release notes for CommandBox 4.8.0:
[COMMANDBOX-991] - Can't always install modules - git error: Directory already exists
[COMMANDBOX-994] - regex metachars not escaped properly in first token of run command
[COMMANDBOX-998] - testbox watch command doesn't obey verbose flag in box.json
[COMMANDBOX-999] - Sometimes line breaks leak to console when using expansions
[COMMANDBOX-1000] - Pass ad-hoc parameters to package scripts
[COMMANDBOX-1003] - Servers bound to 0.0.0.0 don't open useful browser URL
[COMMANDBOX-1030] - unicode chars not read from readme files when publishing
[COMMANDBOX-1040] - Native OS execution doesn't handle exit on fail for *nix
[COMMANDBOX-1041] - Install path not respected when createPackageDirectory set to false
[COMMANDBOX-1002] - Add cached version of HTTP(S) endpoints
[COMMANDBOX-1031] - Output binary objects in REPL
[COMMANDBOX-1039] - Add support for "cd -"
[COMMANDBOX-993] - Announce onServerStop when stopping a --console server
[COMMANDBOX-996] - Support path completion with "run" or "!" command
[COMMANDBOX-997] - Expand log output of failed job steps
[COMMANDBOX-1001] - Pass interceptData to package scripts
[COMMANDBOX-1004] - Allow tab completion on quoted parameters
[COMMANDBOX-1033] - Editor on Linux
[COMMANDBOX-1042] - Return actual exit code of server process from server start
[COMMANDBOX-1045] - Java install endpoint allows invalid slugs
[COMMANDBOX-1046] - Pass CommandBox shell env vars to server starts
[COMMANDBOX-1047] - Better detection of CF Engine when using HTTP provider
The main features of CommandBox 4.5.0 are:
Ability to install OpenJDK automatically for your servers to use (read more)
Environment Variables in the shell (read more)
Support for Forgebox Enterprise (TBA soon)
JRE Bundled CommandBox installs now use OpenJDK instead of Oracle JDK
TestBox Code Coverage integration (read more)
I already wrote a fairly comprehensive overview of the new features and big fixes here. Go read it:
https://www.ortussolutions.com/blog/commandbox-450-rc-release-candidate-ready-for-testing
Note, there are two backwards incompatible changes. The first is we turned OFF directory browsing by default on servers. You can easily get the old behavior back with
The second is that unhandled errors in the shell no longer show the stack trace (you probably wouldn't have noticed if I didn't tell you!) Get the old behavior back with:
Here's the full list of everything that went into this release.
[COMMANDBOX-784] - editing in the shell prompt is buggy while using Gitbash in VSCode
[COMMANDBOX-895] - Passing positional args to task errors with required param
[COMMANDBOX-897] - Passing command string as single arg to box fails
[COMMANDBOX-899] - Exitting recipe with exit code errors
[COMMANDBOX-901] - external module mappings broken in CommandBox 4
[COMMANDBOX-903] - Incorrect behavior when parsing unmatched quotes
[COMMANDBOX-915] - Cruft left in temp folder
[COMMANDBOX-917] - Silence annoying ESAPI warnings
[COMMANDBOX-919] - Warnings on java 11 about illegal reflective access
[COMMANDBOX-516] - Add concept of env vars for commands to use
[COMMANDBOX-906] - Add preCommandParamProcess interception point
[COMMANDBOX-907] - outdated commands now verify packages in parallel
[COMMANDBOX-908] - Automatically download JRE for server if specified by version range
[COMMANDBOX-910] - Support multiple ForgeBox endpoints
[COMMANDBOX-911] - New Java endpoint that ties into the AdpotOpenJDK builds
[COMMANDBOX-914] - Make exit code of native binary from run command available in the exception that is thrown
[COMMANDBOX-916] - Pull Code Coverage data on "testbox run"
[COMMANDBOX-921] - Allow recipe args to be used as environment variables for that command
[COMMANDBOX-896] - Add ETA to progress bar when downloading
[COMMANDBOX-898] - Improve default handling of JVM heap size
[COMMANDBOX-900] - Default directoryBrowsing to false
[COMMANDBOX-902] - Allow box to be called with a single string containing a command chain
[COMMANDBOX-904] - Prevent folder endpoint from picking up folders in CWD on install
[COMMANDBOX-909] - Hide stack trace by default when CLI errors
[COMMANDBOX-922] - Allow recipe command to accept arbitrary commands directly
[COMMANDBOX-923] - Include mapping-tag in rewrite exclusion list
[COMMANDBOX-924] - Update JRE builds to use OpenJDK instead of Oracle JDK
[COMMANDBOX-925] - Provide all other args to command completor UDFs
[COMMANDBOX-926] - Announce postInstall interceptions even if package was found to be already installed
[COMMANDBOX-934] - Server commands can have huge delay on Windows
[COMMANDBOX-937] - List artifacts alphabetically.
[COMMANDBOX-939] - /usr/bin/open on Linux
[COMMANDBOX-942] - Errors in command CFCs can cause box to exit completely during tab complete
[COMMANDBOX-949] - Running native binary that returns lots of text can perform poorly
[COMMANDBOX-950] - Interceptor service blows up if you register a module with an interceptor not matching any current states
[COMMANDBOX-951] - Allow modules to register an interceptor with no currently valid states
[COMMANDBOX-953] - Catch errors from desktop.isDesktopSupported()
[COMMANDBOX-930] - Allow system setting (env var) expansions in REPL
[COMMANDBOX-932] - Improve task DSL to allow access to exit code
[COMMANDBOX-944] - Add config setting to debug raw native command being used in the "run" command
[COMMANDBOX-249] - Enforce correct casing conventions on scaffolding commands
[COMMANDBOX-927] - Update propertyFile core module
[COMMANDBOX-928] - Improve default ignores in box.json from init command.
[COMMANDBOX-929] - Disable ping to time server host by default
[COMMANDBOX-931] - Allow exit code to be returned via "return" keyword
[COMMANDBOX-935] - Improve syntax highlighting in REPL
[COMMANDBOX-938] - Checking interrupted status from inside a thread doesn't end the task/command
[COMMANDBOX-943] - Remove hint from default CFC in Lucee for CommandBox CFCs with no hint of their own
[COMMANDBOX-945] - Endpoint URL shows incorrectly for forgebox endpoints
[COMMANDBOX-948] - Enhance tab complete for private slugs
The foreach command which was introduced recently and allows you to iterate over any list of input and run a command using each item in the list has been enhanced to also allow you to iterate from the CLI over any JSON string that you pipe in.
https://commandbox.ortusbooks.com/usage/foreach-command#iterating-over-json
Now when you create a directory watcher in a task runner or custom command, you can not only get notified when something in that directory changes, but you also now receive a list of files added, removed, and modified.
Thanks to Scott Steinbeck, we have a new command called coldbox watch-reinit. This will watch for changes to certain files in your project and will automatically issue a framework reinit when you edit things like configs or services.
Thanks to John Berquist, CommandBox now has sweet color coding any time it outputs JSON to the screen. Try it out by running something like "server show".
Users can also customize the colors they see for JSON with the following config settings:
json.ansiColors.constant
json.ansiColors.key
json.ansiColors.number
json.ansiColors.string
Setting values can be any color name from the system-colors command.
Thanks to Jason Steinshouer we have a new Gist endpoint for installing code from a public Gist.
https://commandbox.ortusbooks.com/package-management/code-endpoints/gist
[COMMANDBOX-876] - testbox watcher shows error when test fail
[COMMANDBOX-881] - Tab complete doesn't work on param values with spaces
[COMMANDBOX-882] - Long lines wrap in interactive jobs
[COMMANDBOX-887] - Exact versions don't update from ForgeBox when manually changed.
[COMMANDBOX-895] - Passing positional args to task errors with required param
[COMMANDBOX-877] - Allow watcher access to files that were added, removed, updated
[COMMANDBOX-878] - coldbox watch-reinit command
[COMMANDBOX-879] - Color code JSON on console output by default
[COMMANDBOX-698] - Refresh any salt values when deploying a new CF engine.
[COMMANDBOX-732] - Add Gist endpoint
[COMMANDBOX-880] - Change update behavior of GIT and URL endpoints to use semver in path if present
[COMMANDBOX-883] - Enhance foreach command to accept JSON
[COMMANDBOX-884] - ACF 11 should start without Secure Profile
[COMMANDBOX-890] - Enhance "forgebox search" command to break up versions like "forgebox show"
[COMMANDBOX-891] - Support versions like 0.5.2 in forgebox show/search output
[COMMANDBOX-892] - Speed up embedded server start
In this section you will find the release notes for the 3.x version of CommandBox.
- Nov 2017
- Aug 2017
- Jul 2017
- Mar 2017
- Jan 2017
- Nov 2016
- Oct 2016
- Jul 2016
- Jul 2016
- Feb 2016
- Feb 2016
For a task that has more than one target (method) you can specify dependencies that will run, in the order specified, prior to your final target. Specify task target dependencies as a comma-delimited list in a depends
annotation on the target function itself. There is no limit to how many target dependencies you can have, nor how deep they can nest.
Given the above Task Runner, typing
would run the runMeFirst()
and run()
method in that order.
Docs:
The web server in CommandBox is capable of enabling GZIp compression to reduce the size of HTTP responses. To enable GZip compress on your CommandBox server, add a web.gzipEnable
setting in your server.json
file.
When you get a directory listing in CommandBox, you can add the --simple flag which will only output the file and folder name without any other information. This feature was added to compliment the feature below.
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 example will find all JSON files in a directory and run the cat command against them.
This is still a little experimental since it hasn't gone through full testing, but we upgraded to Lucee 5.2.9.31 in the core CLI which has support for the newer versions of Java. We've removed the checks that previously preventing CommandBox from even trying to run on versions of Java later than 8 and at first glance it seems to be working though there's been some flakiness on Java 11. Please help test these later Java versions and remember that if you spin up a server, you'll want to still dial in Java 8 for Adobe CF 2016 and prior and Lucee 5.2.8.50 and prior even if you have the CLI running on Java 9+.
Docs for setting custom Java version in your server:
Here's the full release notes for CommandBox 4.3.0.
In no particular order...
Fix background colors not showing up in Powershell and Windows cmd
System Setting expansions not always working in server.json
testbox run no longer blindly assumes you're returning JSON.
Piping commands into box was broken since 4.0.0
Starting server with --debug didn't output logs on error.
Sorted by createUUID() DESC...
Custom commands have more control over their tab completion candidates.
Control how many levels deep package list displays
New versions of Lucee, JGit, JLine, and WireBox
More pack200 of the Lucee jar (and more improvements to come soon in the next version of Lucee)
Automatic detection for build servers like Travis-CI to hide progress bar animations.
Cloning Git repos during install has a nice new progress bar that plays well with
You can use the aforementioned progress bar for your own purposes in custom commands and Task Runners.
The run command has been a pain over the last few versions as every "fix" has seemed to lead to another regression. We've made some more changes to try and get each use case working as expected with no annoying bash messages about "job control". Fingers crossed.
Single one-off command, streams output to console as it comes.
Piping output of native binary into another Command (output captured all together and not streamed).
Running interactive commands. No output at all really, standard input and output of CommandBox bound directly to native shell
You can now control the exit code that CommandBox (or your recipe) exits with. Remember, zero is successful, any other number is failure.
Access the Exit Code of the previous command via a System Setting expansion of${exitCode}.
Recipes now have better support for exit codes. If a command throws an error OR returns a non-zero exit code, the recipe will stop and the exit code of the last command will be returned as the exit code from the recipe command. And if it was a non-interactive shell, the exit code will flow all the way back to the operating system from the box binary. Also, running "exit" inside of a recipe will no longer exit the entire shell, but just that recipe execution. This give you a lot better control over your recipes.
Let's take a moment to review an existing but little known feature of CommandBox that we borrowed from bash. This is not new, but you need to know this for the following section to make any sense. Similar to bash, CommandBox allows you to chain multiple commands together on the same line and make them conditional on whether the previous command was successful or not.
You can use &&
to run the second command only if the previous one succeeded.
You can use ||
to run the second command only if the previous one failed.
You can use a single semicolon (;
) to separate commands and each command will run regardless of the success or failure of the previous command.
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.
Returns a passing (0) or failing (1) exit code whether the path exists.
You can specify if the path needs to be a file or a folder.
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
Returns a passing (0) or failing (1) exit code whether both parameters match. Comparison is case insensitive.
Big thanks to John Berquist and Dominic Watson for helping add this new feature. You can now install packages directly from S3, Amazon S3, Digital Ocean Spaces and Google Disk.
There are several different authentications mechanisms available too:
Per bucket credentials in your CommandBox endpoint settings
Global credentials in your CommandBox endpoint settings
Environment variables
AWS credentials file
IAM role
The full docs are here:
We've added 17 pieces of flair to our server tray menus to show you more information such as PID, webroot, and port as well as a new option to open up the web root in your file system explorer.
Here's the full list of everything that changed in CommandBox 4.2.0.
Fixed the annoying "server spanner" error that *nix users saw when starting servers.
Updated CLI engine (and default server) version to Lucee 5.2.7.63 which includes an important security fix.
Added a new "noninteractive" setting to improve the output on build servers like Jenkins or Travis-CI
Task runner metadata changes picked up without needing to reload the CLI
Ability to load ad-hoc modules on the fly from Task Runners
Here's the full list of tickets we addressed in the 4.1.0 release. Thanks to those who send me pull requests for some of these fixes and features!
[] - server start on linux: "/bin/bash not found" message displays
[] - Improve port binding logic
[] - Task component metadata is not refreshed before each run
[] - Error when invalid UTF-8 characters are in servers.json
This has been pretty big for Windows users who access files on their servers over a UNC network path like \\server-name\foo\bar. You can now cd into paths starting with \\, perform file operations like cat against those paths, etc. Note backslashes need escaped in the CommandBox shell.
This was pretty straightforward since Java already supports this, but I had to change a lot of core path handling to make sure the correct slashes were preserved. This needs a fair amount of testing to make sure we nailed it down for good. If your network share requires permissions, you'll need to have saved those in Windows Explorer already or execute a "net use" OS command from the shell.
When running a task from the CLI, the user will be automatically prompted if they don't supply all the required args. This is just like commands work now.
We also fixed several bugs with passing positional parameters and flag to task runners.
This has been a long time coming, but if you want to work on a CommandBox module now, you don't have to keep copying files over to your CommandBox installation just to test. Instead, just run this from the root of your module's repo:
This will symlink (works on Windows and *nix) your module into the core CLI's modules folder and reload the shell so you can immediately start testing. When you're done, just run package unlink. If you'd like to use this same feature, but to link a ColdBox module's repo over to a test application so you can test it without making a copy, you can pass in the path to the remote modules folder you'd like to link to.
This is a little easier than using your OS's native symlink commands and can be used in recipes that will work across operating systems!
box install returns failing exit code if a package install fails. This helps builds fail correctly if things go wrong
When prompted to type in something like a missing parameter, your answer is no longer added to the command history
The --debug flag works correctly when starting a server from your OS shell like $> box server start --debug
box.json dependencies are stored with forward slashes so Mac and Windows devs stop fighting over which file to commit
config set no longer prints out the value to avoid leaking secrets in build script output.
Updating a package now uninstalls the previous version first to ensure a fresh start since the new version may have removed files.
If you're setting CommandBox behind an AJP proxy, we exposed the flag and ports for that as first class citizens of server.json.
Visual markers for private packages in the forgebox search command.
The package init command creates a valid slug for private packages in the @user/slug format.
New --local flag to server list to show all servers that have been started in the current working directory
If for some reason you want to supply some ad-hoc JVM args to the actual CLI process, you can create a new environment var called BOX_JAVA_PROPS="foo=bar;brad=wood"
You can now touch files in a non-existent directory and it will create the directory instead of erroring.
Viewing a ForgeBox package via package show with a markdown based description, now has basic formatting in the CLI
The default URL rewrite file doesn't try to rewrite requests to /favicon.ico even when it doesn't exist.
At John Farrar's request, several URLs in output messages have had space put before and after them so capable shells will auto-link them correctly.
Improved the Java networking error messages on server start if the host name wasn't correct in your host file and you were letting CommandBox pick a random port for you.
Prevented unnecessary saves to box.json when installing to keep file updated dates from being touched.
Added friendly check for Java 9 since it's not supported yet and the error that displayed made zero sense.
Commands like forgebox show and forgebox list now can provide their data in JSON format. ex: forgebox show coldbox --json
Bug
New Feature
Improvement
Docs:
Docs:
[] - Command Box failed to initialize using java 9
[] - CFFileServlet doesn't work with default rewrites in ACF 2016
[] - We need to review exit codes in Tasks
[] - WireBox/LogBox upgrade broke system logging
[] - Engine name not detected correctly when using HTTP URL for cfengine
[] - Fix annoying web-inf folder for Flex logs on Adobe engines
[] - Missing line break when following log file
[] - Spelling error in info message for accessLogEnable
[] - coldbox create app cuts last char from package name
[] - Starting Adobe server errors when no CFIDE mapping is defined
[] - CommandDSL parsing doesn't handle quoted text in command
[] - Task method dependencies
[] - Add setting for GZip compression
[] - Add --simple flag to ls/dir command to only output filename
[] - Add "forEach" command to execute command once per incoming line
[] - TestBox Run command could use a way to add custom url parameters. Also the options parameter does nothing
[] - Improve progress bar cleanup and exit codes on Ctrl-C
[] - Allow Java jars to be installed from S3
[] - JSON Schema for server.json
[] - Upgrade CLI to Lucee 5.2.9.31
[] - Support sorting JSON objects by key when formatting
[] - Task DSL assume CWD of task file
[] - coldbox scaffold install testbox by default
[] - Allow command DSL params() to be called more than once
[] - Make resolvePath() in Base command/task
[] - Reload shell doesn't always fire when non-CommandBox modules get updated in core
[] - Allow print helper to accept complex objects and serialize them for output.
[] - .zip files in artifacts cache don't include empty folders
[] - "bash: no job control in this shell" error message (pull request)
[] - external commands/shells that are interactive (such as vi) are not working when executed from commandBox
[] - tab hinting colors wrong in PowerShell terminals.
[] - System settings not always used in server.json
[] - "testbox run" formats outputfile as JSON even if it's not
[] - Piping input to CommandBox broken
[] - Bleeding edge upgrades show wrong URL after S3 artifacts move
[] - --debug doesn't dump job logs on error
[] - Allow arbitrary command params to have file/folder completion via annotation
[] - Allow custom completion UDFs to provide group and description
[] - New conditional commands pathExists, assertTrue and assertEqual
[] - Allow access to previous exitCode as system setting
[] - Allow user to exit shell with specific exit code
[] - Improve recipe handling of exitCodes
[] - Compact package listing
[] - Write a custom JGit progress updater that clears out at the end
[] - Hide JLine warning about dumb terminals
[] - S3 Endpoint
[] - Upgrade to JGit 5.0.1
[] - Upgrade to Launch4J 3.12
[] - Skip forgebox checks on server start with server home dir that's already installed.
[] - Upgrade to JLine 3.8.2
[] - Pack200 Lucee bundles
[] - Upgrade to Lucee 5.2.8.50
[] - Default rewrites support /pms servlet used for Adobe CF 2018 performance monitor
[] - Default nonInteractiveShell setting in commonly known build environments
[] - Improve messaging when initting private package
[] - Reorganize the tray menus
[] - Upgrade to Wirebox 5.1
[] - Localized CommandBox Modules
[] - Add new slugify function to the formatter utility
[] - When creating coldbox skeleton apps, clear out the basic name, slug, version, location and scripts so the user can configure them
[] - Added new bundles,labels,verbose,directory arguments to the testbox watch command to allow for granular executions
[] - Added verbose options to passthrough to the testbox runner so it true it can return the debug buffer
[] - Remove legacy installColdbox, installColdboxBE, installTestbox arguments from create commands
[] - Added ability to visualize the exception stacktraces with a configurable depth.
[] - Add setting to force "non interactive" shell that disables fancypants progress output
[] - Change user agent on downloader to get around proxies like cloudflare
[] - Store less "result" text in CommandBox's servers.json
[] - Upgrade core Lucee engine to 5.2.7.63
The rest of the changes don't really need a dedicated section but they're worth mentioning, so I've put them in this tidy list :) If you'd like the ticket numbers, you can get them out of this full list of tickets in JIRA:
work on all the aliases for a command now.
Our CF11 servers no longer have secure profile enabled. That was causing issues due to some of the settings like returning 200 on error. If you were making use of that default, please use to set what you need.
[] - --debug flag is eaten when running CommandBox from native OS
[] - Ensure clean install/update of packages
[] - Touching file in nonexistent directory errors instead of creating directory
[] - CommandDSL that errors out doesn't reset CWD
[] - positional task args don't work
[] - cp command doesn't work for folders
[] - CommandBox Modules customInterceptionPoints can't accept an array
[] - CommandBox has no `processState` method on the InterceptorService
[] - Flags aren't passed correctly to task runners
[] - CFML functions don't handle incoming JSON with pound signs
[] - Expose Runwar AJP listener settings
[] - Update server list and server info to be able to show all the servers on a particular directory
[] - New package link and package unlink commands
[] - Add ad-hoc JVM props via an environment variable
[] - Don't store text entered to "ask()" command in history
[] - Handle minor version updating a bit better
[] - Always store dependency install paths with forward slashes
[] - Have a setting to not show secrets when printing out the config
[] - Support UNC file paths on Windows
[] - JSON format for forgebox endpoints
[] - Ask user for required params to task runners
[] - Visually show if a package is private when listing or showing
[] - make package init create correct slug for private package
[] - Make default command parms work on aliases
[] - Box install failures to produce non-zero exit codes so build fails instead of continuing installation.
[] - Provide ANSI formatting for markdown package descriptions
[] - box.json template isn't proper JSON
[] - Remove background color from CommandBox ASCII art
[] - Default rewrite rules to ignore favicon.ico
[] - Disable Secure Profile on CFEngine WARs
[] - Leave space around URLs so some consoles will be clickable
[] - Improve performance of package install ignores
[] - Improve error message in ServerService.getRandomPort()
[] - Prevent unnecessary writes to box.json file when installing dependencies
[] - Improve formatting when asking for required param that has no hint
[] - Add Java 9 check to CommandBox until its supported
[COMMANDBOX-665] - Relative SSL certFile or keyFile path in server.json isn't expanded
[COMMANDBOX-674] - propertyfile set errors if file doesn't exist
[COMMANDBOX-675] - Allow relative property file paths in task runners
[COMMANDBOX-666] - Allow custom tray contributions to have relative image path
[COMMANDBOX-667] - Improve coldbox create app --wizard
[COMMANDBOX-671] - Always run onServerInstall
[COMMANDBOX-672] - add getInstance() to base interceptor class
[COMMANDBOX-673] - Improve handling of loading a bad modules
[COMMANDBOX-678] - Command to normalize line endings for a batch of files
[COMMANDBOX-679] - Improve package parsing regex for private packages
You've been able to run OS binaries from the CommandBox interactive shell for a while now which is great for adding native CLI calls to your recipes.
The biggest problem with this though was that no output shows on the screen until the OS command is completely finished and if your OS command blocks for interactivity or just never ends, the CommandBox shell will just "hang" with no output. All that is a thing of the past now. The standard input and output of the OS process is now bound to the standard input and output of your CommandBox shell. That means that you see output as soon as the binary outputs it and if it stops to ask you for input, you can provide it. This opens up a world of possibilities.
You can ping an address and watch the output stream as the packets return.
You can do a Git commit and interact with the VI window that appears to capture your commit message.
You can actually open a bash/DOS shell right inside of CommandBox and then "exit" back to box when you're done.
Run native commands that collect input from you to continue like a sudo password.
This has been tested and works pretty well on Mac and Windows. Note, we've seen some issues on Linux where output is streamed, but input is not captured.
preServerForget - Always fires before attempting to forget a server whether or not the forgetting is actually successful
postServerForget - Fires after a successful server forget. If the forget fails, this will not fire.
This was supported in CommandBox 3.4.0, but we had a regression in 3.5.0 that caused issues for users who have a space in their path to CommandBox's home dir. This has been fixed along with some related issues with the FusionReactor module. Make sure you have the latest Fusion Reactor module once you upgrade to CommandBox 3.6.0.
The core version of Lucee that the CLI runs on has been updated to 4.5.5.006. Please note this means the default version of Lucee that starts up for your server when you don't specify otherwise will change. If you have settings like datasources and such that you want to keep, make sure you lock in your exact version of Lucee or check into our new CFConfig project for exporting/importing your server settings.
The testbox run command would return an exit code of 0 when your tests had in fact failed. This has been fixed so you can trust a proper exit code from the process when running your tests inside a Jenkins or Travis CI build.
Previously, you couldn't set a global default HTTP port for all your servers. This was on purpose since it didn't really make sense since one one server can use a port at a time. Now, with the introduction of Chris Schmitz's host updater module, you can more easily run each server on a dedicated host name which is added to your host file for you and bound to a unique port. This allows you to run all your local servers on port 80 which is great for cleaning up your local dev. As such, we've added the ability to set the global HTTP port now in your config setting's server defaults.
Here's the full release notes for the 3.6.0 release.
[COMMANDBOX-553] - Windows CommandBox upgrades fail silently if servers are left running
[COMMANDBOX-554] - Box start error
[COMMANDBOX-555] - All semicolons removed in REPL which breaks some code
[COMMANDBOX-558] - Can't start server when space is in user home dir
[COMMANDBOX-559] - server list --verbose produces an error
[COMMANDBOX-567] - package list sometimes shows incorrect version of 1.0.0
[COMMANDBOX-572] - Running server info on non-server folder creates empty server details
[COMMANDBOX-575] - CommandBox fails to start if a 3rd party module fails to load
[COMMANDBOX-582] - NPE on some URLs occasionally
[COMMANDBOX-587] - testbox run doesn't always return correct exit code on failure
[COMMANDBOX-502] - improve execution of OS binaries in "run"
[COMMANDBOX-556] - Add xxxServerForget interceptors to the Server lifecycle
[COMMANDBOX-570] - Improve port binding detection
[COMMANDBOX-571] - Allow port to be defaulted in config settings
[COMMANDBOX-576] - Improve CommandBox module installations
[COMMANDBOX-578] - Bump Lucee version to 4.5.5.006
This release fixes an issue where Adobe CF servers will not start if you're machine is offline and also fixes a bug where the previous version of CommandBox didn't correctly remove old versions of jar files on upgrade.
Git tags when bumping a package command can have a custom prefix now. Tab completion options are also alphabetized. Ctrl-C is also handled better on Unix and actually works in Windows! Also, the timestamp on your sever.json file won't be updated unless the contents of the file actually changed.
Here is the full list of everything that changed in the CommandBox 3.4.0 release.
[COMMANDBOX-471] - Adobe Servers won't start offline
[COMMANDBOX-472] - start serverConfigFile=myServer.json doesn't load json settings
[COMMANDBOX-475] - Adobe web.xml Flex config path is wrong after first engine start
[COMMANDBOX-480] - Error checking whether server is running
[COMMANDBOX-484] - cflib-coldbox endpoint creates invalid CFML for Adobe
[COMMANDBOX-485] - write history before command finishes
[COMMANDBOX-491] - Coldbox create interceptor doesn't create test with proper CFC mapping
[COMMANDBOX-492] - war path not stored in server.json as relative path
[COMMANDBOX-494] - CFML upgrades don't delete removed files
[COMMANDBOX-496] - Forgetting a named server deletes the 'default' server.json too
[COMMANDBOX-476] - allow bump Git tag to have custom prefix
[COMMANDBOX-477] - testbox create bdd include describe and it block
[COMMANDBOX-481] - Allow server list to filter partial server names
[COMMANDBOX-486] - Sort tab completion options
[COMMANDBOX-487] - Also negate boolean options with "no" in front
[COMMANDBOX-488] - Stop model scaffolding with empty names
[COMMANDBOX-489] - Handle Control-C better in the shell
[COMMANDBOX-493] - Improve check for previously-installed package
[COMMANDBOX-495] - Don't update modified date of server.json unless actually modified.
[COMMANDBOX-497] - Starting named server inherits same server.json settings
Task Runners - Run ad-hoc builds from the CLI written in CFML (Read more)
Manage System Packages - update, list, and uninstall system modules (Read more)
File Globbing - Use place holders like **.cfc for file operations to affect more than one file at a time. (Read more)
Command Aliases - Alias your favorite commands for easy access in the future (Read more)
Global Command Parameter Defaults - Set common parameters to have a given value at a global level (Read more)
System Settings - Utilize environment variables to make your package and servers more dynamic (Read more)
Testbox Run - Improved, minimalist output to the "testbox run" command (Read more)
TestBox Watchers - Watch a directory for file changes and run your unit tests (Read more)
Customize REST Servlets - Customize or disable the REST servlet paths on Lucee and Adobe servers (Read more)
Custom Java Versions - Start your CF servers with any version of Java you want (Read more)
Property files - New commands and helper libs for dealing with property files (Read more)
Basic Authentication - Enable basic security on your servers with unlimited users (Read more)
Custom URL to Open - Customize the browser URL that opens when you start a server (Read more)
Disable Tray Icon - Turn off the system tray icon for your servers entirely (Read more)
Show Proxy IP - Servers pass through the original user IP through proxies
Jar Endpoint - Install 3rd party jars into your projects (Read more)
[COMMANDBOX-176] - Server start tries to open HTTP URL even if it's disabled
[COMMANDBOX-474] - testbox run with runner urls that have a query string fail
[COMMANDBOX-525] - cf_scripts folder not working on Adobe 2016
[COMMANDBOX-600] - Catastrophic runner errors in testbox run don't fail tests
[COMMANDBOX-611] - errors if you start second CLI while first one is using the temp dir
[COMMANDBOX-616] - TestBox scaffolds are missing super calls for beforeAll/afterAll
[COMMANDBOX-621] - Prevent two servers from getting the same name
[COMMANDBOX-625] - Basic auth doesn't set cgi.remote_user
[COMMANDBOX-651] - unregister method in interceptor service doesn't work
[COMMANDBOX-15] - Allow file globbing patterns in file/folder operations
[COMMANDBOX-50] - Create BaseTask
[COMMANDBOX-51] - Add "task" command to run tasks
[COMMANDBOX-54] - Create watchers
[COMMANDBOX-459] - Create the --system argument to all package commands for system wide packages
[COMMANDBOX-513] - Allow REST servlet to be configured
[COMMANDBOX-548] - Allow custom JRE version for server starts
[COMMANDBOX-560] - Support Basic Auth
[COMMANDBOX-564] - Allow placeholders in for env vars and system props
[COMMANDBOX-585] - Provide convenient command to do simple token replacements from the CLI
[COMMANDBOX-589] - Checksum Command
[COMMANDBOX-590] - Property files commands support
[COMMANDBOX-599] - Add MinHeapSize setting
[COMMANDBOX-608] - Support for viewing/installing private packages
[COMMANDBOX-610] - Finalize box.json testbox runner options
[COMMANDBOX-613] - Allow Command DSL to set working directory
[COMMANDBOX-614] - Implement "testbox watch" command
[COMMANDBOX-638] - Simple Jar endpoint
[COMMANDBOX-642] - Ability to disable tray icons
[COMMANDBOX-644] - Allow ad-hoc aliases to be created for commands
[COMMANDBOX-645] - Allow global defaults to be set for command parameters
[COMMANDBOX-647] - Automatic collection from parameter names containing a colon
[COMMANDBOX-648] - Implement the equiv of Tomcat's remoteIPValve
[COMMANDBOX-649] - Support missing Tuckey config settings
[COMMANDBOX-655] - Command to remove trailing whitespace from files
[COMMANDBOX-656] - Command to add final EOL to files
[COMMANDBOX-568] - Better error message for invalid JSON in a server.json file
[COMMANDBOX-429] - Update debian build signing to be higher than SHA-256
[COMMANDBOX-586] - If publishing but not logged into forgebox, prompt for login instead of just erroring
[COMMANDBOX-597] - Clean up SSL cert and key file parameters for server start
[COMMANDBOX-601] - Improve HTML to ANSI conversion on larger strings
[COMMANDBOX-602] - Refactor JSON formatter to separate lib for reuse
[COMMANDBOX-606] - Add trace flag for starting server
[COMMANDBOX-612] - Improve output of "testbox run" command
[COMMANDBOX-617] - Remove deprecated and unused properties from box.json with init
[COMMANDBOX-618] - Don't try to output binary data in REPL
[COMMANDBOX-622] - Show "last started" datetime for servers
[COMMANDBOX-623] - Customize URL that opens when starting server
[COMMANDBOX-626] - Allow commandbox-modules to register endpoints
[COMMANDBOX-646] - Enhance parser to allow quoted spaces in parameter names
[COMMANDBOX-650] - WireBox injection DSL allow to drill down into Config Settings
[COMMANDBOX-652] - Command to remove trailing spaces from code files
[COMMANDBOX-657] - Allow console flag to be stored in server.json like every other setting
[COMMANDBOX-658] - Allow publishing of private packages
We upgraded to a new version of the underlying library that handles the CLI interactions which brought a number of nice things.
The cls command now clears background colors that used to be left on the screen
Tab completion works better when two folders with different case were in the same directory
When developing commands, default text can be placed in the buffer when asking the user for input.
Fixed some instances where undesired spaces would get added when hitting tab completion
We also made the following improvements to the CLI shell environment
You don't need to escape an equals sign that's part of a quoted parameter value
Removed extra line break when piping the output of the "run" command
Fixed some regressions when piping text to the box binary
Added better BOM detection when tailing files
cp command will create destination directories
Windows paths that start with \ or / will be treated as absolute (like DOS works)
All OS's will expand ~ to the current user's home directory
The tail command used to only take a file as input, but now you can pipe raw text in as well.
When tailing a file, you can specify the --follow flag and any new text added to the file will live stream to your console until you press Ctrl-C to stop. This is perfect for tailing application logs while your code is running to see new entries.
The server log command also has a new --follow flag added to it which will live stream a running server's console log to the shell until you press Ctrl-C to stop it.
The artifact storage location is now customizable thanks to Chris Schmitz, allowing you to store your artifacts on another drive, or even a network share so your coworkers can all use the same "local" copies.
CommandBox will always re-download snapshot versions of packages to make sure you get a fresh version.
When you try to install a package and CommandBox is offline, instead of giving up, we'll now look in your local artifacts cache for a satisfying version. If we find a package that works in your artifacts, we'll install it instead.
We added a few new ways to start up a server. You can use the --debug flag when starting a server to see additional information and the foreground process also waits for the server to start before finishing. Now when starting in debug mode this output will stream to the console as it becomes available instead of showing up all at the end. This is great to troubleshoot errors that are happening on server start as well as finding the slow parts of the startup sequence.
By default, your servers fire up in a new process that runs independently from the CLI. There is now a new flag called --console that will start the server up in the foreground and stream the console output to the CLI for you to watch. The start command will not end and will keep streaming the console output until you press Ctrl-C to stop it. You can also use --debug alongside the console flag for even more information.
If you have an app that uses a default welcome file other than index.cfm, you can control that now.
This is one that you take for granted if you've always used Adobe ColdFusion, but for any CF server not running on Adobe's custom version of Tomcat, you can't use SES URLs in a subfolder like this without adding custom mappings to your web.xml:
We've added just a dash of servlet fairy dust that now makes this possible. Note, if you want to hide the index.cfm with URL rewrites, you'll need a custom rewrite config for it to work in a subfolder.
All server engines and versions have been standardized to install into the same reliable directory structure to make it easier for you to script config file replacements.
For Adobe CF WARs, the xml config files are located in the WAR here: /WEB-INF/cfusion/lib/neo.*.xml
For the Lucee server context, the xml config file is located in the WAR here: /WEB-INF/lucee-server/context/lucee-server.xml
For the Lucee web context, the xml config file is located in the WAR here: /WEB-INF/lucee-web/lucee-web.xml.cfm
To find the folder where your WEB-INF lives (as well as lots of other information about your server) you can use the server info command to get useful properties about a starting or started server.
Combining these allows you to do some nice one-liners like scripting out the copying of config settings when the server starts up. Hint: Use an onServerInstall or onServerStart package script!
Read more about this here:
https://commandbox.ortusbooks.com/content/v/development/embedded_server/copy-configs.html
Until now you've had to live with the special directory that CommandBox uses to install your servers into. Now you can get full control over where the server goes which is perfect for creating a folder "seeded" with config files that you want the server to use when it first starts. This trick (with some clever Git ignores) will also allow you to commit changes to your config files back to the repo while ignoring the rest of the engine.
Customize Lucee's server context folder with the serverConfigDir setting
Customize Lucee's web context folder with the webConfigDir setting
Customize where the entire WAR explodes to for any server with the serverHomeDirectory setting
This is very powerful since it gives you full control over the server deployment. Server installs have also been changed to NOT overwrite existing files when they unzip, so any config files you place in the server home prior to starting the server will be left in place and used by the server when it starts up. This means you can have datasources, mappings, and more start out-of-the-box for your site on a fresh install.
Read more about this here.
https://commandbox.ortusbooks.com/content/v/development/embedded_server/custom-server-home.html
There were a few small changes in the "undocumented" core of CommandBox that got rearranged to make more sense. There's a small chance you may have been relying on one of them, so take note:
The serverHome property that comes back from server info has been renamed to serverHomeDirectory.
The webConfigDir property used to point to the server home, but this was incorrect. The property will now be blank unless specified. Use serverHomeDirectory instead.
The default Lucee server used to have a non-standard folder structure, but now matches the WAR folders of all other servers
The web context in Lucee servers used to be in a folder named after a random hash which was kind of silly (and impossible to find). It's now always under /WEB-INF/lucee-web
All "internal" Lucee servers used to share a single server context (and settings). All servers are now separate. Use the serverConfigDir setting to point more than one server at a single server context or use one of the new options for copying configs.
The core CLI server context now has a default password of "commandbox" set. This would apply if you wanted to use the tag from .cfm files executed via the shell or a custom command.
Several new properties were added to the server info data for your convenience. Check them out by starting a server and running server info --JSON.
[COMMANDBOX-236] - `box reload` doesn't clear background colors from buffer on Windows
[COMMANDBOX-248] - tab completion doesn't always work on paths
[COMMANDBOX-500] - CommandBox timeout is shorter than runwar timeout when starting Adobe servers
[COMMANDBOX-505] - BOM interferes with commandbox.properties
[COMMANDBOX-507] - Staring server with defautlPort in box.json, adds optional keys back in.
[COMMANDBOX-509] - Ignore equals in a quoted parameter
[COMMANDBOX-522] - Improve error message when endpoint fails installing server
[COMMANDBOX-526] - Use hostname for "coldbox reinit"
[COMMANDBOX-533] - Error starting CommandBox in some instances
[COMMANDBOX-539] - "run" expressions contain line break on Linux
[COMMANDBOX-542] - Regression in piping input from OS console
[COMMANDBOX-543] - Piping a file of commands with a BOM into box fails
[COMMANDBOX-544] - package set doesn't always set what you expect
[COMMANDBOX-545] - The `commandbox-home` when used in symbolic link mode fails on mac
[COMMANDBOX-234] - ability for server start to deploy web-inf locally instead of server location
[COMMANDBOX-473] - Control list of welcome files
[COMMANDBOX-479] - Make artifacts path customizable
[COMMANDBOX-503] - Allow tail command to follow a log file
[COMMANDBOX-504] - Allow raw text to be piped into the tail command
[COMMANDBOX-506] - Add startTimeout parameter to control how long to wait for server to start
[COMMANDBOX-508] - Console flag to server start
[COMMANDBOX-523] - new preServerStart interceptor
[COMMANDBOX-534] - Add --follow flag to "server log" to tail it and follow
[COMMANDBOX-535] - cp command create directories if necessary when copying file
[COMMANDBOX-536] - If Forgebox is down, use artifacts cache on installs
[COMMANDBOX-538] - Allow programmatic access to server info
[COMMANDBOX-546] - Allow custom server home dir
[COMMANDBOX-153] - Support for double wildcard servlet mappings
[COMMANDBOX-222] - Set default password Lucee CLI context
[COMMANDBOX-439] - absolute paths on Windows don't follow the same rules as DOS
[COMMANDBOX-456] - If forgebox is down, 'internal' server won't start
[COMMANDBOX-498] - Upgrade engine to Lucee 4.5.4.017
[COMMANDBOX-499] - improve contentbox-widget package installation conventions
[COMMANDBOX-501] - Stream server start log when debug is true
[COMMANDBOX-510] - Improve JSON parsing when piping complex values to cfml command
[COMMANDBOX-511] - Allow webConfigDir, serverConfigDir & webXML to be relative
[COMMANDBOX-514] - Improve rewrites to not fire on SES URLs in a subdir
[COMMANDBOX-515] - server forget does not stop server if running
[COMMANDBOX-518] - libdirs aren't relative when starting a server
[COMMANDBOX-519] - Libdirs aren't used for non-internal servers.
[COMMANDBOX-520] - Improve output of server info and server list commands
[COMMANDBOX-521] - Stop loading java agent for Lucee 5
[COMMANDBOX-524] - Improve starting internal server when not specifying buildID
[COMMANDBOX-528] - Improve server start intercepors
[COMMANDBOX-529] - Standardize server home directories
[COMMANDBOX-530] - Upgrade to JLine 2.15-snapshot
[COMMANDBOX-531] - Allow default text to be put in buffer for ask() function
[COMMANDBOX-532] - Don't cache snapshots
[COMMANDBOX-537] - Remove .git folder when cloning a Git repo
[COMMANDBOX-540] - Support ~ as a shortcut for the user home directory like bash.
[COMMANDBOX-547] - Improve tab completion for server/package/config set commands
[COMMANDBOX-549] - Spruce up the opening ASCII art
[COMMANDBOX-550] - Pass JVM args through to background server process
[COMMANDBOX-551] - Fix working directory of xxxInstall package scripts
Major rewrite of CLI engine loader
Lucee 5 now powers the CLI
Using JSR-223 to dynamically load Lucee 5
All 3rd Party libs updated
JGit
Launch4J
Runwar
JLine3
Improved Task Runner support
Task scaffolding with “task create”
Task DSL to call other tasks
Ortus Builds are now being converted to Task Runners. No Ant! No XML!
Support for Private package
Revamped Server Logs (access, rewrite, console)
ColdBox 5 updates
Tons of bug fixes and improvements
There are currently 69 tickets that are part of the 4.0 release. You can view them all over in JIRA if you filter based on a fixVersion of 4.0.0. Here's an overview of some of the cooler new features, in no particular order.
This is dependant on your terminal, but the CLI now can look a lot prettier. For Mac users, this will probably work out of the box. For Windows users, cmd won't cut it. We recommend checking out ConEMU as a sweet, tabbed terminal replacement. To see what kind of punch your terminal packs, run this new command:
Along with the newest version of JLine, there's a ton of nice little things now available in CommandBox 4. The first is a totally revamped tab completion interface. Pressing Tab is now prettier, colored, and more organized. Help is integrated right into the interface, and pressing tab repeatedly will cycle through the available options instead of redrawing the screen over and over.
Next is color coding when you type commands in the shell. This make it much easier to tell when you've typed the name of a command correct and makes the difference between the command and parameters easier on your eyes.
Finally is tab complete and syntax highlighting in the REPL. You can tab complete any CFML function as well as previous variable names you've typed. Common CFML keywords are highlighted, as well as CFML functions and there's even color coded matching of braces, parens, and quotes as you type.
There are two new features in the shell's history. Pressing "up" will still show the previous items in your history. But typing a partial command like "cd" and THEN hitting up will jump to the most recent histories that start with that word. Very handy to find that one "coldbox create..." command you ran two days ago.
The second new history feature is known in the bash world as i-search. Press Ctrl-Shift-R to open a search from the console where you can search your entire command history by keyword. Keep pressing Ctrl-Shift-R to cycle backwards through the results. Press Ctrl-Shift-S to cycle forwards through the results. Press enter to run the matched search select, or edit it inline before running it.
There's a new CommandBox module available called "commandbox-bullet-train" which makes the CLI look super sleek and sexy. You can add it very easily with:
You'll want to install a powerline-patched font as well. Check out the instructions under the "Fonts" section in the readme.
https://www.forgebox.io/view/commandbox-bullet-train
And is that some sweet new ASCII art taking advantage of 256 colors as well as a randomized quote/tip on every shell start? Why yes, yes it is!
CommandBox has a new way to interact with users and give them a list of pre-defined options that doesn't require typing a free text response. You'll see it if you try to start the same server twice in a row. This is fully documented and available for you to use in Task Runners and custom commands as well.
Some of the more wordy tasks you perform like installing packages and starting servers have gotten a big makeover in how they reveal their output to you. If an installation fails, you want to know about it, but so long as everything worked, you usually don't care. These actions will now scroll the last few active log entries past in a controlled format, but hide them at the end so the shell stays much cleaner, even when installing dozens of packages at once.
As an example, installing CFConfig actually installs 9 separate packages. This used to output around 100 lines of console logging which no one in their right mind ever read. All the same logging is still there, but now by the time it's done, this is all you see:
If you want to troubleshoot, or you are running this install as part of a build and you want to see all this output later, just use the --verbose flag. For server starts, using the --debug flag will preserve all your precious log output on the screen after the server starts.
Even cooler, the Interactive Job interface is fully documented and available for you to use in your Task Runners or Custom Commands.
Docs:
https://commandbox.ortusbooks.com/task-runners/interactive-jobs
Example:
Which looks like this when it's done:
We did a lot of work to make dealing with servers easier-- especially when it comes to your log files. Console starts and tailing server logs are now color coded so it's easier to find errors and warnings.
We've also fine tuned what information shows up when you do --console starts as well as --debug starts to reduce the noise and enhance the useful information. For instance, when you do:
You'll see a line of debug logging that shows if the URL rewrites kicked in and what the URL was rewritten to. How useful is that?!
Remember you can view and tail the server "out" logs like so:
The built in Undertow web server that CommandBox uses just got more powerful. You can turn on access logs that show you every incoming HTTP request in the same "common format" as Apache web server.
You can view and tail this log file like so:
But wait, there's more logging goodness. Troubleshooting rewrite rules can be really tricky. That's why we broke out a new separate log file just for Tuckey Rewrites to dump into. You can dial in how much information you get with --debug and --trace server starts.
You can view and tail this log file like so:
CommandBox web servers are truly ready for prime time. All the Undertow log files above automatically rotate which means you'll never fill up a hard drive on accident due to out of control log files.
Another optional module you can install is the CommandBox update check module. It will check every 24 hours (when starting the shell) and let you know if your CLI or any of your system modules are out of date.
This used to work back in the day, but was a regression back when I added the ability to interact with native binaries. Now you have the best of both worlds.
Running other tasks from inside of Task Runners is now easier. Docs:
https://commandbox.ortusbooks.com/task-runners/running-other-tasks
Example:
(Same as running "task run build" from the CLI)
You can now cancel long running commands, tasks, and even HTTP downloads by pressing Ctrl-C. Yay! Pressing Ctrl-C from the prompt does nothing, which is consistent with other shells. Pressing Ctrl-D from the shell will now exit CommandBox entirely which is also consistent with other shells. In case you're wondering, Ctrl-C fires the interrupt terminal signal, and Ctrl-D sends the EOF (end of file) signal.
Docs:
https://commandbox.ortusbooks.com/usage/interactive-shell-features#ctrl-c-and-ctrl-d
You can now load ad-hoc jars right from Task Runners which is sometimes necessary for working with Java libs. Docs:
https://commandbox.ortusbooks.com/task-runners/loading-ad-hoc-jars
Examples:
Wanted to play with Task Runners but not sure where you start? Drop everything, grab the closest CommandBox 4 CLI, and run these two commands:
You just created a new task and ran it. Go on, look around!
https://commandbox.ortusbooks.com/task-runners/task-anatomy
Directory listings have gotten a makeover. The columns actually align, the file sizes are human-readable, and the file types are color coded. Be careful, you might actually be able to find stuff now!
If you remember the "Magic Eye" books from your childhood, you'll be pleased to know CommandBox has an ASCII Art Stereogram for every day of the month. You'll find it hiding inside the info command. The "image" will change every day at midnight.
If you keep looking like that, your face will freeze that way!
We tried very hard to keep CommandBox 4 compatible but there are a few things that might surprise you.
The REPL and Task Runners run against Lucee 5.2.7 instead of 4.5.5. That might affect valid CFML syntax as well as datasource definitions
The default server you get when you type "server start" is also Lucee 5.2.7, not Luce 4.5.5.
Java 7 support removed. This affects both the core CLI as well as any servers. For CF9 users, you can still run CF9 servers but you'll need to use an older version of Java 8 such as 1.8.0_92. (Note: Java 9 and 10 don't work yet!)
Native CFML execution via box foo.cfm now routes through the "execute" command which means no Application.cfc will get run. You can refactor your cfm scripts or use the undocumented _internalRequest() function in Lucee 5.
You no longer can use \t and \n to escape tab and line breaks in command parameters. This caused a lot of confusion in Windows paths and there are other ways to do it right in your terminal. Check out the docs on it.
The waitForKey() method in Task Runners and custom commands no longer returns the ASCII code, but the actual character pressed OR a special string representing the key press like "key_up" or "key_down". Check out the docs here.
CommandBox 4 is prettier, more productive, and cooler than CommandBox 3. This may cause CLI envy with your Node coworkers. Don't worry, this is normal.
[COMMANDBOX-174] - Box CLI not working inside cygwin
[COMMANDBOX-395] - Commandbox 3.1.X no longer works with Git Bash
[COMMANDBOX-728] - Allow control of default package name when box.json is missing
[COMMANDBOX-749] - Server won't start with $ in web root path
[COMMANDBOX-750] - Can't list files in directory with parenthesis in the name
[COMMANDBOX-761] - Default rewrites don't start regex at the start of the request URI
[COMMANDBOX-763] - Ctrl-C in shell kills associated server processes on *nix
[COMMANDBOX-767] - Issue installing older CF engine when two versions exist who only differ in build ID
[COMMANDBOX-778] - Adobe war has incorrect default /CFIDE CF mapping
[COMMANDBOX-782] - CLI Loader crashes: Error reloading cached bundle
[COMMANDBOX-783] - ls and dir do not list directory content after 'cd ..' without trailing slash
[COMMANDBOX-785] - restart command not correctly detecting stopped server
[COMMANDBOX-787] - Starting two servers at once can corrupt servers.json file
[COMMANDBOX-788] - Starting server from non-ForgeBox endpoint doesn't detect proper engine/verion
[COMMANDBOX-790] - Package publishing fails with folder named "readme" in the root
[COMMANDBOX-724] - Control HTTPOnly and secure attribute of JSESSIONID
[COMMANDBOX-73] - Version check on startup
[COMMANDBOX-566] - CommandBox bullet train
[COMMANDBOX-583] - Create a "checkbox" user input for commands
[COMMANDBOX-722] - Task DSL
[COMMANDBOX-725] - Make SSL work on Adobe servers
[COMMANDBOX-726] - Allow testbox run runner to be relative URL
[COMMANDBOX-727] - validate box.json properties for testbox run usage
[COMMANDBOX-729] - Change default jAnsi temp path
[COMMANDBOX-745] - Updating ColdBox commands to ColdBox 5
[COMMANDBOX-751] - Enhance REPL console highlighter to work with parens and curlys
[COMMANDBOX-752] - Support 256 colors with print helper
[COMMANDBOX-757] - Update testbox command to trim and prettify json results
[COMMANDBOX-759] - Be able to add jars to core Lucee classloader from inside the CLI
[COMMANDBOX-760] - Command to scaffold new task
[COMMANDBOX-771] - Create dedicated log for rewrites
[COMMANDBOX-438] - Remember the currently edited command when navigating through the history
[COMMANDBOX-482] - better tab completion for REPL
[COMMANDBOX-527] - Upgrade to JLine3
[COMMANDBOX-552] - Update Launch4j library
[COMMANDBOX-596] - Refactor `Box foo.cfm` to funnel through execute command
[COMMANDBOX-702] - Remove \t and \n escapes
[COMMANDBOX-706] - Upgrade CLI core to use Lucee 5
[COMMANDBOX-714] - Parsing issue with native OS binaries
[COMMANDBOX-719] - Add serverDetails and installDetails to the onServerStart interceptor
[COMMANDBOX-720] - Add web access logs to undertow
[COMMANDBOX-730] - Improve message on server forget
[COMMANDBOX-731] - Don't escape params() in CommandDSL when the command is "run"
[COMMANDBOX-735] - Change how Ctrl-C and Ctrl-D behave
[COMMANDBOX-736] - Pressing "up" filters history on what you've already typed
[COMMANDBOX-737] - Allow Ctrl-C to interrupt executing tasks like downloading a file
[COMMANDBOX-738] - REPL isn't clear whether expression returned empty string or null
[COMMANDBOX-739] - Allow commands to be interruptible with Ctrl-C
[COMMANDBOX-740] - Highlight code in the repl
[COMMANDBOX-741] - Add prePrompt interception point
[COMMANDBOX-742] - Allow installPath to override PackageDirectory
[COMMANDBOX-744] - preProcessLine and postProcessLine interception points
[COMMANDBOX-747] - Allow raw params to CommandDSL that aren't escaped
[COMMANDBOX-753] - start --console should exit if server is killed externally
[COMMANDBOX-754] - Handle download progress when no total file size is avaiable
[COMMANDBOX-755] - Switch to load CFML engine via JSR-223
[COMMANDBOX-756] - Throw on invalid server.json
[COMMANDBOX-758] - Add rewrite exception for Adobe CF's cf_scripts folder
[COMMANDBOX-764] - Allow output of native OS binaries to be captured from CLI and task runners
[COMMANDBOX-765] - Upgrade to latest JGit lib
[COMMANDBOX-768] - PackageDirectory in package box.json is never honored
[COMMANDBOX-769] - Improve "testbox run" error output on Adobe CF
[COMMANDBOX-770] - Update bundled JRE to latest
[COMMANDBOX-773] - Upgrade to WireBox 5.0
[COMMANDBOX-774] - Cache CFC metadata for faster startup times
[COMMANDBOX-775] - Refresh progress bar UI
[COMMANDBOX-776] - UI control for "Jobs" to pare down output for several operations
[COMMANDBOX-777] - Spruce up info command with easter eggs
[COMMANDBOX-780] - Spruce up dir command
[COMMANDBOX-786] - Default to latest in upgrade command when on a prerelease already
[COMMANDBOX-789] - Add additional debugging information to the "info" command
The embedded CommandBox server have seen a number of nice enhancements to make it easier for you to use CommandBox for super easy local development.
The more people begin to use CommandBox for local development, the more interested they became in being able to run FusionReactor on their dev servers to help trouble shoot their code. That's why we created a CommandBox FusionReactor module. It's not part of the core, but can be installed in a single command and will attach FusionReactor's server monitor to every server you start. You'll need to have a FusionReactor license or sign up for a trial to use it.
CommandBox allows you to create web aliases for the web server that are similar to virtual directories. The alias path is relative to the web root, but can point to any folder on the hard drive. Aliases can be used for static or CFM files. To configure aliases for your server, create an object under web called alises. The keys are the web-accessible virtual paths and the corresponding values are the relative or absolute path to the folder the alias points to.
Here's what your server.json might look like.
Here's how to create aliases from the server set command:
You can customize the error page that CommandBox servers return. You can have a setting for each status code including a default error page to be used if no other setting applies. Create an errorPages object inside the web object in your server.json where each key is the status code integer or the word default and the value is a relative (to the web root) path to be loaded for that status code. This is what you server.json might look like:
You can set error pages via the server set command like this:
You can customize these tray menus and add your own option for your convenience. To add a menu contribution to an individual server, add the following to your server.json
:
We've updated to a new library that creates the tray icon for your running servers and the menu that appears when you right click. In addition to better support for some Linux distros, we've added some nice new icons to the menus.
Before any package script is run, CommandBox will look for another package script with the same name, but prefixed with pre. After any package script is run, CommandBox will look for another package script with the same name, but prefixed with Post. So if you have a package that contains 3 package scripts: foo, preFoo, and postFoo, they will run in this order.
preFoo
foo
postFoo
This works for built-in package script names as well as as doc package scripts. It also works on any level. In the example above, if you created a 4th package script called prePreFoo, it would run prior to preFoo.
If you use more than one ForgeBox login, perhaps a personal one and a company one, it can be a pain to keep logging in. It's also hard to remember the last user you logged in with. We've introduced two new commands to help with this. Run this to tell you who you are logged in as:
Run this to switch between users that you've previously logged in with:
We've added a new "onRelease" interceptor and package script to help with the workflow of publishing packages. Here's a run down of the three key points when bumping a package version.
preVersion - Announced before the new version is set using the bump command
postVersion - Announced after the new version using the bump command but before the Git repo is tagged.
onRelease - Announced after a new version is set using the bump command and after the Git repo is tagged.
Here is a typical package script work flow for working with a package that's hosted on GitHub and published to ForgeBox:
Then when you want to publish a new version of your package, commit your changes to Git and run the following commands:
Those two commands, in combination with your package scripts, would accomplish the following:
Run the package's test suite (a failure will abort the process)
Increase the minor version of the page
Tag the Git repo
Change the package's location property in box.json to point to the new tag
Commit the tag and new box.json
Publish the package to ForgeBox
Push the new box.json and Git tag
Announced while a package is being installed, after the package endpoint and installation directory has been resolved but before the actual installation occurs. This allows you to override things like the installation directory based on package type. Any values updated in the interceptData struct will override what the install command uses.
The Lucee version that the CLI runs on has been updated to be 4.5.3.020 which is also now the default engine to be used when you use the "server start" command and don't specify a cfengine. If you still want to start a web server on Lucee 4.5.2.018, then simply to this:
There are tons of little bug fixes in this version that you can view in our release notes.
[COMMANDBOX-187] - error when updating forgebox when slugname changes
[COMMANDBOX-422] - Empty command CFCs with no functions throw an error starting box
[COMMANDBOX-423] - Error "key [FUNCTIONS] doesn't exist" thrown when trying to start command box
[COMMANDBOX-426] - server name completion errors on server open command
[COMMANDBOX-434] - Document the resolvePath() differing behaviour on OSX vs Windows
[COMMANDBOX-435] - artifacts clean fails on OSX when there's .DS_Store files
[COMMANDBOX-437] - appSkeleton in the coldbox create app wizard needs to comply to IDs instead of local disk
[COMMANDBOX-449] - "server open" always opens localhost
[COMMANDBOX-451] - The trayicon in server.json does not work with relative paths
[COMMANDBOX-464] - update command doesn't respect original install path
[COMMANDBOX-465] - custom url rewrite location doesn't respect starting server by name in different location
[COMMANDBOX-466] - coldbox create crud doesn't work on Windows
[COMMANDBOX-316] - Add Fusion Reactor support for server
[COMMANDBOX-399] - Starting server in web root with WEB-INF treats CWD as war
[COMMANDBOX-416] - Add "open" flag to touch/new command.
[COMMANDBOX-430] - forgebox whoami command to show what user your API key is set to
[COMMANDBOX-431] - Update the storage of the APIkey in the commandbox settings to include multiple keys
[COMMANDBOX-432] - Have a forgebox use {username} command to switch the current api key
[COMMANDBOX-445] - Allow aliases (virtual directory) in web server
[COMMANDBOX-458] - Provide custom 40x and 50x error pages for servers
[COMMANDBOX-398] - Catch error scenario when user tries to start a server with a WEB-INF
[COMMANDBOX-410] - Upgrade to latest Runwar with several bug fixes
[COMMANDBOX-412] - Refactor string similarity to use external library
[COMMANDBOX-413] - Refactor semver CFC to be separate lib
[COMMANDBOX-414] - Refactor path pattern matcher CFC to be separate lib
[COMMANDBOX-419] - coldbox create app command does not list all templates
[COMMANDBOX-420] - Run pre/post package scripts by convention
[COMMANDBOX-421] - Add onRelease interception point/package script
[COMMANDBOX-424] - Serious performance issue with formatting large JSON strings
[COMMANDBOX-425] - Better handle syntax errors in a module's config
[COMMANDBOX-427] - Move onServerStart interception announcement to have server home dir
[COMMANDBOX-428] - Allow tray options to be customized
[COMMANDBOX-433] - Add onInstall interception point
[COMMANDBOX-436] - Incorrect custom model path in the unit test
[COMMANDBOX-440] - Exit REPL multi-line with extra enter stroke
[COMMANDBOX-442] - Don't use in-use port specified in start params or server.json
[COMMANDBOX-443] - Wait for full debug output when starting server with debug=true
[COMMANDBOX-444] - Append JVM args and runwar args to server defaults
[COMMANDBOX-454] - Update to Runwar 3.4.10
[COMMANDBOX-457] - Improve server status detections
[COMMANDBOX-460] - Show tag stack when executing .cfm files
[COMMANDBOX-461] - Improve tab completion of forgebox slugs
[COMMANDBOX-467] - Allow custom images inside tray menu plus disabled items
[COMMANDBOX-468] - Add overwrite confirmations to all coldbox create commands
[COMMANDBOX-469] - Improve version output in "forgebox show" command
[COMMANDBOX-470] - Upgrade engine to Lucee 4.5.3.020
Properties weren't being read correctly from the server.json
file. If you have been using server.json
, please double check the format of the file here in our docs:
This fix will make this functionality work as expected:
If you already have 3.0.0 then this fix only affects the CFML bits and is very easy for you to install. Simply run this command:
If you're still on CommandBox 2.x, check out our to see the cool new stuff.
In this section you will find the release notes for the 2.x version of CommandBox.
- Nov 2015
- Aug 2015
- Aug 2015
- June 2015
One of the biggest pieces of feedback we got from the CommandBox 3.1 release was that it requires an Internet connection to start a server. Since you can specify the version of the server you want to start, including semver ranges like 5.x, this required a trip to ForgeBox to check and see what the best version match was since it might have changed since the last time you started the server.
Now, if you provide an exact CF engine version number (meaning you give us a major, minor, AND patch version) CommandBox will skip phoning home to ForgeBox and will just continue with that version.
Remember that the version "5" de-sugars to "5.x.x" so you need to have all three numbers even if they're "0"
We even went a step further. Sometimes ForgeBox may be down for maintenance or due to an outage and it was preventing people from being able to start their servers. If ForgeBox can't be reached for some reason while starting the server, we'll try again by comparing the version range you provided with the CF Engines already cached in your local artifacts cache. If we can find a version that satisfies what you asked for, we'll use it to start the server. That means you might not be getting the latest version of the engine from ForgeBox, but at least your server will start with that is has downloaded already.
Unpublishing a package should be something you rarely need to do since once a package is published, someone else may be depending it for their app to run. However, we now have an unpublish command you can run from the CLI to remove a specific version of a package, or the entire package itself from ForgeBox.
We've also included the latest versions of Adobe ColdFusion 10, 11, and 2016 on ForgeBox. This is something we can update separately from our CommandBox releases, but they came at the same time so I bundled the announcements together :) Here are the latest Adobe versions available:
Adobe CF 10.0.20+299202
Adobe CF 11.0.09+299201
Adobe CF 2016.0.02+299200
We also fixed a few bugs too. For example, targeting a Git tag stopped working in version 3.1 due to a library update, plus CommandBox's proxy settings weren't being used for all HTTP requests.
Here's the full list of everything in version 3.2.0 of CommandBox. Click on the ticket numbers for more details in JIRA.
[] - Execute command doesn't work in interactive shell
[] - Testbox create commands break if testname includes package
[] - installpaths not added when not creating package directory
[] - Git endpoint psses java.io.File instead of string
[] - HTTP Endpoint package name guessing doesn't account for periods in file name
[] - When you do an 'update' command, it updates the modules but does not update the box.json with the latest version
[] - SQL Server JDBC driver doesn't work
[] - Sign Debian packages
[] - Update the status command to output the results in json
[] - Update coldbox model generator to allow the creation of accessors
[] - Add ability to generate properties on coldbox model generations
[] - Update all BDD tests to fail by default to promote refactoring and process
[] - CFLib endpoint
[] - RIAForge Endpoint
Now CommandBox will not only start up Lucee 4 servers with a single command, but you can start up Adobe ColdFusion, Railo, and even Luce 5 servers all at the same time. Now it's easier than ever to test your code across multiple platforms. CommandBox's embedded server makes for a fast and easy development machine too regardless of what CF engine you need.
We'v released a brand new site with a new UI, fresh features, and a shiny new API. CommandBox 3.1.1 is now powered by the new ForgeBox site and API which includes features like having more than one version for a package.
You no longer need to visit the ForgeBox web site to publish new or updated packages to ForgeBox. This is all available from the CLI once you've logged in. This means you can even automate the process of publishing to cut down on the number of manual steps it takes you to update your projects and share those changes with the community.
You can now run commands of your choosing automatically when certain events in the CLI happen (like publishing a package, or starting a server). You can also create ad-hoc collections of commands to run whenever you want to help automate things like building your projects or publishing to ForgeBox.
CommandBox now has a JSON file of settings that can be used to configure any kind of behavior we want. We're still working on implementing features that actually use the settings, but the first will be the ability to set up a proxy server for your corporate network. Config settings give us a place to store ad-hoc settings like this as well as an API for retrieving them. What's great is the settings JSON file can store ANY information, including complex structs and arrays so feel free to use it for your own purposes as well. You can interact with config settings like so:
This is perhaps the most radical thing we've done in CommandBox to date and it is huge. We've introduced modules (just like ColdBox) into the actual CLI itself. A module is a unit of code re-use that allows you to take a folder of code that follows a few simple conventions and drop it into a module-aware application for instant extension. This means that we've broken out all the internal commands into system modules for organization. What's more, you can write your own CommandBox modules that hook into the internal workings with interceptors, register their own custom commands, or help manage settings or servers. Modules can be placed on and installed by your friends in seconds to extend the core of CommandBox. The benefits here can't be understated. Check out and go through the quick, easy steps to create your first CommandBox module.
Not only can modules have settings, but you can also override a module's default settings easily with config settings that follow a simple convention. For example, if a module named "foo" has a setting named "bar", you don't need to edit the module's code to change the setting. Simply run this command:
CommandBox interceptors, like modules, work the same way that ColdBox interceptors do. They give you hooks that you can register to listen to events broadcast by the CommandBox core, or custom events of your own design that you announce. These are very powerful for being able to extend and modify how the core CLI works to build upon it. Interceptors are bundled inside modules so they install quickly and easily. Distribute them on as well. I've already created a that uses the onCLIStart interceptor to modify the ASCII art banner that appears when you start CommandBox.
Here's some of the core interception points:
onCLIStart
onCLIExit
preCommand
postCommand
onServerStart
onServerStop
onException
preInstall
postInstall
Now you can write modules that check for upgrades on CommandBox startup, manipulate the output of commands, log exceptions, customize server startup, or audit what package you install the most!
We've had the ability for custom commands for a while, but they were limited and didn't easily allow you to include additional CFC files with your commands. Now with the addition of modules, your custom commands can be package in a module right alongside settings, interceptors, or services. We also simplified the creation of custom commands so things like extending our BaseCommand class is optional thanks to WireBox's virtual inheritance. We hate boilerplate as much as you do!
This feature has been a long-time coming. There are a lot of options you can set when starting a server, and portability has been hard for people wanting to distribute an app that needs to start with custom JVM args, rewrites, or a specific port. Now all server startup options can be set in your web root in a server.json file which will be used automatically the next time you run "start". You interact with these settings the same as package or config settings.
We've had the "run" command for a while now that allows you to run native binaries from the interactive shell, or from a CommandBox recipe. The output is returned which allows you to create mashups that pipe the output of OS commands directly into CommandBox commands. We took this a step further and borrowed from other CLIs out there so now the parser allows you to call native OS binaries by simply prefixing an exclamation mark (!) in front of the binary name. Now only are OS commands run in the current working directory, they are also executed via the shell for that machine which makes non-binaries and aliases like "ll" function.
This is a really neat feature that allows you to actually run CFML functions straight from the CommandBox CLI as commands. Just prefix the function name with a hash sign (#) and then type the function name with no parenthesis. Any parameters to the function can be passed (or piped) into the command like normal named or positional CLI command parameters.
This really gets cool when you start piping the output of commands together to string together mixtures of CommandBox commands and CFML functions for fancy one-liners. Here's some string manipulation. The first one does some list manipulation. The second one outputs the lowercase package name.
But wait, there's more! You can even use struct and array functions. Their output is returned as JSON and automatically deserialized as input to the next command. Keep in mind that piped data gets passed in as the FIRST parameter to the next command. This outputs a nice list of all the top-level dependencies in your package.
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.
You can really go crazy with these mashups by combining CFML functions too. This example sets a property in a package's box.json that's equal to a nicely formatted date:
We've really focused on doing CommandBox development now with the possibilities opened up with the addition of modules. One pain point of extending CommandBox was calling other commands since parameters needed to be escaped. We created a nice method-chaining DSL to help execute any other command from inside of your custom commands.
You can even nest the DSL to pipe output between commands:
In line with the previous item, we've made it yet easier to write custom modules that extend the functionality of CommandBox by adding new WireBox injection DSLs. Everything inside of CommandBox is created and autowired by WireBox. You can now ask WireBox to inject core services, module settings, or config settings.
[] - Box install throws exception on git endpoint with commit-ish syntax
[] - Starting server from diff directory by name uses wrong web root
[] - semver isExactVersion returns true for 3 and 3.4
[] - Proxy server not used in ForgeBox calls
[] - Unpublish command
[] - Show package URL location after publish, some consoles allow you to click and visit
[] - Show number of packages in forgebox types
[] - Add ForgeBox URL to show command as some consoles allow you to visit
[] - Add ForgeBox URL to search command so consoles can click and open
[] - Add new patches for Adobe CF 10, 11, and 2016 to forgebox
[] - Add Offline Ability for cfengine Server Start
[] - Add box.json data to pre/post publishing interceptors
[] - Add a directory argument for the REPL
[] - REPL's handling of functions that output content
[] - Optimize JVM Memory Arguments to Prevent PermGen and Java.lang.outOfMemory errors
[] - Improve error message when ForgeBox REST API is down
[] - Update to latest Lucee stable build
[] - Update to latest ColdBox application templates
When you install packages from , you can use fancy semver ranges to specify the versions of a package you're willing to install. CommandBox will automatically grab the latest version that satisfies your version range. This also applies to the "update" command which makes keeping your projects' dependencies up-to-date even easier.
Another feature of the new site is the ability to create a new ForgeBox user right from the CLI. After creation, you'll be logged in with your ForgeBox API Key which let's you update your packages.
We hope you enjoy playing with the new features. As always, jump on our , or the with any questions or feedback. And remember, we provide tools like CommandBox CLI free of charge to the community as . If you have specific needs in the form of features or training for your team, Ortus is here to help you. with any questions.
[] - CFML Function commands do not work on recipes
[] - box update pulling down dev dependencies
[] - Exception in packageservice determining testbox slug runner
[] - Git clone doesn't obey commit hash
[] - tail command doesn't handle CR and LF correclty
[] - Linux: CommandBox 3.1.0-1: Fails to start
[] - Linux distros: /usr/bin/box created with wrong permissions
[] - Progress bar errors if console is too small
[] - Slug auto-complete doesn't work with ForgeBox 2.0
[] - "forgebox search" doesn't work with ForgeBox 2.0
[] - bump command creates invalid version if it starts blank.
[] - CF servers create WEB-INFcfform directory in server root
[] - Start server on any engine
[] - ForgeBox 2 API Integration
[] - forgebox register command
[] - forgebox login command
[] - forgebox publish command
[] - Creation of API Docs for internal CommandBox Core
[] - Update S3 Sync for CommandBox to publish core API Docs
[] - Update the coldbox create command to make the skeleton be a 'name,git+url,http' endpoint
[] - Add command to output system log file
[] - Allow forgebox downloadURL to be any endpoint ID
[] - Allow a package to have listener scripts run by convention
[] - Add pre/postVersion, pre/postPublish interception points
[] - Allow interactive shell (scripts/recipes) to have more than one command per line
[] - bump command tags and commits Git repo if present
[] - Global default for server settings
[] - New Icons for Multi-Engine taskbars
[] - Ability to run ad-hoc scripts
[] - Track installs in ForgeBox 2.0 API
[] - Add onServerInstall interception point for addition engine config
[] - Allow server set/show/clear to target a custom JSON file
[] - Missing 'models' namespace on model test creation
[] - Update Adobe CFEngine wars to have latest updates
[] - Return with exit code 1 when things fail
[] - Add ability to use environment variables to supply java args for BOX itself
[] - install my-module installs unneeded devDependencies
[] - Add ability to specify a server.json by path
[] - Modify build to include sdk format of Unix binary
[] - Improve error message when using "box" from interactive shell
[] - Convert all existing ForgeBox calls to new API format.
[] - Improve messaging and logging when errors connecting to Forgebox
[] - Enhance semver logic for satisfying versions
[] - Allow param completion UDF to see typed text
[] - Capture full java exception stack from Jgit errors
[] - Convert CF Engine downloads to S3/ForgeBox
[] - Fix right click options on server tray icon to be non-Lucee
[] - Allow masking of user input
[] - Auto-correct rewritesEnabled to be rewritesEnable in the start command
[] - Update module scaffolding to create in modules_app folder.
[] - Make help for commands more intuitive
[] - Don't create init methods for models if included in the method list
[] - Switch create controller command to create handler command
There are already some cool custom commands popping up on ForgeBox. Check out for making http calls from the command line similar to curl.
[] - Starting a server by short name doesn't work
[] - Tag REPL seems to be unavailable
[] - REPL output cannot be piped
[] - url rewriterules in commandbox incorrect
[] - Brew fomulas SHA1 mismatch
[] - Starting server from OS shell doesn't always work
[] - Restarting server saves openBrowser as false in server.json
[] - Can't clear JSON properties with dash in the name
[] - Coldbox create view commands break if name includes package
[] - CommandBox TestBox array of runners does not run
[] - Provide a more programmatic way to run commands/tasks like a method
[] - Allow native binary execution with exclamation mark
[] - Add server.json to default server settings
[] - Global CommandBox setting file
[] - Disable sendfile in runwar server
[] - Refactor JSON handling out of package commands for reuse
[] - Allow # as a REPL shortcut to run CFML tags or functions
[] - Allow expressions in command parameters
[] - Add option to server start for enabling/disabling directory browsing module
[] - Allow commands to be piped in to box
[] - Override module settings with config settings on module load
[] - WireBox injection DSLs for module config and settings
[] - Handle struct of environment variables in server.json
[] - Add additional helper reference to the Executor
[] - Remove bleeding edge builds from production Debian repo.
[] - Standardize command packaging
[] - HTTP Calls don't work behind company proxy
[] - Use virtual inheritance for commands
[] - Allow ad-hoc JVM args when starting server
[] - Add modularity
[] - Add event-listener model to CommandBox
[] - Improve error handling in CFLib endpoint
[] - Alias Execute as exec
[] - Return better details from progressable downloader
[] - Run command uses same environment as box executable when it was first started
[] - Improve error handling in HTTP endpoint
[] - Update to latest version of WireBox
[] - bump command reset minor and patch
[] - bump runwar version to 3.3.0
[] - Enhance server rewrites for file/dir detection
[] - Refactor core commands to be modules
[] - Move application templates into the coldbox-commands module
[] - Move scaffolding templates into respective modules
[] - Improve error handling in commands
[] - Shortcut to cd into directory after mkdir command
[] - Run command doesn't run in the same CWD as CommandBox
[] - Allow run command to run any OS command from the shell
[] - Allow ConfigService to use nested setting keys
[] - Improve parsing of run and ! command
[] - Allow user to set custom shell with config setting
[] - warn user if package has invalid JSON file
[] - Bump JRE version to 1.8.0_72
[] - Embedded server doesn't sent proper headers for SVGZ files
[] - Support ContentBox installation paths
In this section you will find the release notes for the 1.x version of CommandBox.
Version 1.0.0 - Feb 2015
This fixes a bug in the "update" and "outdated" commands that caused them to error after you had installed packages from an endpoint other than ForgeBox. Note, packages installed from HTTP(S) and Git endpoints will always show as outdated and will always update since those endpoints don't provide a way to know what version they're hosting without downloading the entire package anyway.
We also included a small enhancement to the Git endpoint to allow for authentication via public/private SSH keys. As long as you have a public key configured on your Git server and the private key is stored in ~/.ssh/ using a standard name, SSH-based clones should automatically authenticate. Please see the docs for more info.
As always, the CommandBox Getting Started Guide is located here:
http://commandbox.ortusbooks.com/content/getting_started_guide.html
[COMMANDBOX-259] - update command erroring
[COMMANDBOX-263] - Git SSH endpoint private key support
[COMMANDBOX-260] - Standardize parameter names for install command
The biggest feature is the switch-over from Railo to Lucee as the underlying CLI engine that powers the REPL and commands. The embedded server now also runs Lucee 4.5 as well. If you require a Railo embedded server, you will need to stay on CommandBox 1.1.1 for now.
Another major new feature is support for different endpoints when installing packages in addition to ForgeBox. Now packages can be installed from the following locations:
Local zip file
Local folder
HTTP/HTTPS URL that points to a package zip
ForgeBox (default)
The ForgeBox endpoint now also has rudimentary support for targeting a specific version. If you request a specific version of a package to be installed, and it is in your artifacts cache, no network calls will be made. This allows completely offline installations! Here are some examples:
We also have a nice collection of bug fixes. Below are the full release notes for CommandBox 2.0.0.
[COMMANDBOX-211] - CommandBox caches .cfm files between executions
[COMMANDBOX-214] - Lucee version leaves tons of old jars on upgrade
[COMMANDBOX-218] - Script repl confused on paranthesis or quotes
[COMMANDBOX-223] - coldbox create model command doesn't escape "open" parameters
[COMMANDBOX-224] - Coldbox create model creates incorrect testcase w/ no methods
[COMMANDBOX-225] - Calling `forgebox slugcheck` with empty slugname throws error
[COMMANDBOX-232] - osx brew installation broken for commandbox 2.0
[COMMANDBOX-237] - Application times out and wirebox references die
[COMMANDBOX-238] - Dev installation w/out package directory overwrites box.json
[COMMANDBOX-159] - Switch CommandBox core to Lucee
[COMMANDBOX-215] - Multi Endpoint support
And finally, the ability to install packages from a Git repo is here!
And this nice shortcut for installing from GitHub:
If you've not used CommandBox yet, check out our getting started guide here:
http://commandbox.ortusbooks.com/content/getting_started_guide.html
You can download CommandBox 2.1.0 here on our product page:
http://www.ortussolutions.com/products/commandbox#download
[COMMANDBOX-170] - Piping content to box repl
[COMMANDBOX-220] - Lucee default error template is broken in CLI
[COMMANDBOX-221] - OWASP jars corrupt
[COMMANDBOX-229] - REPLParser doesn't allow // in strings (like in URLs)
[COMMANDBOX-246] - commandbox.properties isn't picked up when box.exe is in a folder with spaces
[COMMANDBOX-165] - Improve parameter escaping when running commands from native OS
[COMMANDBOX-210] - Make ColdBox skeleton hints dynamic by reading folder instead of hard-coded values
[COMMANDBOX-244] - Increase the size/resolution of the icon
[COMMANDBOX-65] - Additional install endpoints
[COMMANDBOX-240] - Git endpoint
[COMMANDBOX-242] - Update all tray icons to CommandBox latest icons
[COMMANDBOX-243] - new server argument: heapSize to allow for sizing the embedded server heap size
[COMMANDBOX-256] - Integrate the Loader java bits into the CommandBox source
[COMMANDBOX-257] - Migrate APIDocs generation to DocBox
CommandBox is a Java-based executable that will run on most recent desktop operating systems (Linux, Mac OS X, Windows). Since it is a command line tool that uses a shell interface, it does not even require an operating system using a GUI. CommandBox can be used as a development aid and automation tool alongside your favorite CFML engine and IDE, but neither of those are requirements for installation of CommandBox.
Here are the requirements for installing and using CommandBox on your system. Notice some of these such as RAM and disk space depend on how many features you will plan on using. For instance, the shell only allocates about 256MB of RAM to run, but if you plan on starting embedded servers, that will spawn additional threads-- each of which will consume their own memory.
Windows XP+
Mac OS
Linux
256MB+ RAM
250MB+ free hard drive space
Multi-core CPU recommended
A Java JRE is listed as a software requirement, but if you have a brand new PC with no JRE we have a download option that contains the Java Runtime bundled with it.
After almost a year in development, we are so excited to finally announce the release of CommandBox 1.0.0 Final. This has been definitely one of the most challenging and fun projects we have overtaken here at Ortus. We had a vision of how we could accelerate not only development, tools and ultimately the ColdFusion (CFML) landscape by building a tool that could put us up to par with many other technologies. I am glad to say we have now a great foundation to move forward. CommandBox brings CFML to any Operating System and even embedded systems like the Raspberry and Banana Pi. It also gives ColdFusion (CFML) developers a much better workflow to work with their projects and a sense of community we lovingly call ForgeBox.
With anything we do here at Ortus, it is fully documented using our new book formats. So head on over to commandbox.ortusbooks.com to download or read the entire CommandBox documentation. In the next coming weeks we will begin our CommandBox 5-week roadshow that will include weekly blogging tutorials and video presentations, so stay tuned as each week progresses. So without further ado, I present to you project Gideon: CommandBox CLI!
CommandBox is a standalone, native tool for Windows, Mac, and Linux. It provides a Command Line Interface (CLI) for developer productivity, tool interaction, package management, embedded CFML server, application scaffolding, and some sweet ASCII art. It includes a plethora of commands to interact with your Operating System, TestBox, ForgeBox, ContentBox, CacheBox, etc. Built-in help is completely integrated for every command. You can pop open a CommandBox shell in your terminal window and manually type commands, or even automate things externally via the CommandBox binary with your OS's native shell.
So one of the biggest things we think the CFML community was missing, was a true package management platform. With this in mind, CommandBox + ForgeBox now includes full package management control for ANY ColdFusion (CFML) application. We have created a spec for a box.json file which will go in the root of CFML packages to describe metadata about the package, how it should be installed, and dependencies that the package requires to run. CommandBox is getting a tight integration with the ForgeBox REST API to search, view, and install packages/modules directly into your app from the command line.
The CommandBox CLI also leverages a REPL console for executing a-la-carte CFML commands. You can use it in script or even tag mode with full command history as well. Each REPL instance also has included memory, which means you can declare functions, datasources, etc and leverage them within the same command executions. We even support multi-line statements.
CommandBox has tons of commands for quickly building out applications. Create a new ColdBox app with coldbox create app
, add a handler with coldbox create handler
. You can even get actions added to it, views created, and BDD integration tests stubbed out at the same time. This can bring new productivity for people who like to live on the command line and especially for those who want to be able to automate stuff they do a lot of.
CommandBox has a thin Java layer and a rich CFML command suite built using WireBox dependency injection. This allows for any CFML developer to contribute and write out their own commands. You can even register your commands in ForgeBox and have them available to any CommandBox installation. This means that any application or framework author can contribute their own suite of commands for their community.
CommandBox also leverages the concept of CommandBox Recipes which allows you to create reusable command files with a box
extension. You can execute this recipes and even do argument-binding for further reusability. You can even shared them in ForgeBox as well. It also natively integrates into your operating system you can even use CommandBox for Unix shell scripting or just plain template executions: box myfile.cfm
or even use argument-binding box execute file=mayflies.cfm var1=hello name=luis
and we will bind those variables into the variables
scope for you.
One of the cool things CommandBox brings to the table is the ability to spin up an ad hoc, lightweight, CFML server in any directory from the command line. Simply change your working directory to the root of your app, type server start
and a super fast CFML server spins up on a new port running your code. When you're done type server stop
from that directory or use the little icon that's showed up in your system tray.In our final release we even included SSL and full URL rewrite support as well.
We have spent considerable time in our auto-update capabilities so users can transition to patches and updates with ease. We have even created two channels for updates:
Stable : Stable releases
Bleeding Edge : Bleeding edge releases
So from you console you can type: box upgrade --latest
for bleeding edge releases or box upgrade
for stable releases.
In the next coming months, ForgeBox 2.0 will be released with many more features to help developers manage their contributions, multiple version control, CommandBox integration, private repositories and much more. We will also be using the URL forgebox.io instead of embedding it in the ColdBox site; time for separation. We also have tons of features planned for CommandBox, here are a few teasers:
Adobe CF embedded server
Task Runner
NodeJS bridges
Lucee Support
Multiple installation providers
ForgeBox Enterprise (For private enterprise installations)
ForgeBox Cloud Private Entries
RCE (Let's see if you can figure out the acronym)
Multiple version and fuzzy version package management
WAR packager
Package signing
Much More
So as you can see, so much work to be done. I leave you with one final note, we highly encourage you to support us in any way you can as ultimately we offer these tools as professional open source and they need your support in order to continue with their development. Enjoy and go code something!
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
If you don't already have CommandBox in hand, download it from the product page on the Ortus Solutions site:
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!
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.
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:
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.
Now, let's see if your installation is up to date with the upgrade
command:
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.
Type these lines one at a time and press enter to see what you get.
When you're done, just type quit
to exit the REPL. How does it feel to master CFML from the command line?
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.
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.
Wow, that Luis guy is busy! Let's install the the ColdBox MVC Platform. Don't worry, this won't hurt a bit.
We can create a skeleton ColdBox app really easy with the ColdBox generator commands. Let's give them a try:
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.
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:
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.
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 are just installing CommandBox to use on your PC as a local development tool, the standard version of the box binary should be fine. It contains a full version of Lucee with all its default extensions pre-installed. However, if you are creating an automation or a distributable such as a Docker container you may want to look into one of these alternative box binaries.
CommandBox Light does not include the full version of Lucee, but rather Lucee Light which only comes with the Compress extension (because CommandBox requires this extension to run). The CommandBox Light binary is roughly half the size of the normal version. The on-disk size of the CommandBox home is about 1/3rd of the size. This can be handy for places where disk size is very important.
Starting a default web server in CommandBox will give you a Lucee Light server, which may not run your app since it lacks extensions such as JBDC drivers and the admin. You can still ask for a specific version of Lucee with the cfengine
parameter. If you delete the engine
folder from a CommandBox Light installation, Lucee will not be able to work since the Lucee.jar file in CommandBox Light has had it's core.lco
file removed to make it smaller. Deleting the entire .CommandBox
folder will work however.
Any Task Runners or CLI automations in CommandBox light will also not be able to use things like JDBC drivers unless you install the extensions. Extensions can be installed by placing them in the CLI's server context deploy folder and waiting a minute:
You can download the CommandBox Light binary directly from our S3 artifacts repo:
box-light - Mac/Linux
box-light.exe - Windows
box-light.jar - Executable jar
The CommandBox Thin binary cannot be used by itself as it contains nothing inside of it but the Java bootstrap. It does not contain any of the other libraries, jars, or Lucee versions that CommandBox needs to load. it is only 300KB in size. The way that the 'thin" binary is to be used is to first download and run the normal CommandBox or CommandBox Light binary which will extract itself into the CommandBox Home. Once this has been completed, you can delete that box binary and replace it with the box-thin binary (renamed to box
). The new thin binary will take up less disk space and will simply use the existing CommandBox home that has been extracted.
The thin binary does not care whether the CommandBox home was extracted with a full or "light" version. This can create additional disk savings in an environment like Docker, but would not serve much of a purpose on your local development PC. If you delete your .CommandBox
folder, the CommandBox thin binary will not be able to recreate it.
You can download the CommandBox Light binary directly from our S3 artifacts repo:
box-thin - Mac/Linux
box-thin.exe - Windows
box-thin.jar - Executable jar
If you already have a Java JRE installed level 1.8 or higher (and set in your environment variables) you can the non-JRE version for your Operating System. If you don't have a JRE installed or aren't sure, we would recommend you the version with a JRE included. Below you will find the way to get the latest stable and bleeding edge releases. Please also note that in our page you will find much more detail information on how to install CommandBox with modern Operating System package managers as well.
Info The non-JRE versions are all around 80MB in size, while the embedded JRE versions will go up to 120MB in size.
Below you can see an image of the available downloads from the Ortus Solutions page:
Info Keep in mind, bleeding edge builds may contain experimental features that are likely to change or bugs.
Info Please note that the upgrade command will not update the main CommandBox binary. If there are major updates or you get a message about updating the binary, you will need to download the latest binary and re-install it.
Regardless of where you place the box binary, the first time you execute it, a .CommandBox
folder will be created in your user's home directory and CommandBox will be extracted into that location. If you delete this directory, it will be replaced the next time the CommandBox executable is run.
You can specify a different install location by adding -commandbox_home=E:\CommandBox
when you run the box binary.
To avoid specifying the commandbox_home variable every time you can create a file called commandbox.properties
(case sensitive) in the same directory as the binary, and fill it with this line:
The CommandBox home can also be a path relative to the location of the commandbox.properties
file.
Extract the executable box.exe from the downloaded zip file, placing it anywhere you prefer where you can then execute it when needed, such as from the Windows command line/terminal. You can also run it directly Windows File Explorer, where you would just double click on the exe,which will open the CommandBox shell in a new terminal window.
Warning On Windows 10 and above, the first time you try to run via Windows File Explorer an exe that you've downloaded, Windows Defender Smartscreen will popup with a warning that "Windows protected your PC". You will need to choose the offered "More info" link and then the offered "Run anway" button, to proceed.
Hint When running from the Windows command line/terminal, you can make it so that you can run
box.exe
while you are in any folder (not just the one where you placed it), by simply adding the exe's location to the WindowsPATH
system environment variable. See
When you are finished running commands in the CommandBox shell, type exit
. Or if you ran the box.exe from within Windows File Explorer, you can just close the terminal window which that opened.
is a great Mac package manager, it can easily install and keep your CommandBox installation up to date (even binary releases), just run the following for stable releases:
To stay with current bleeding edge releases use the following:
Then run the box
binary to begin the one-time unpacking process.
Versions will be installed in /usr/local/Cellar/commandbox
. To switch between versions, you will need to install the new version - either using the bleeding edge tap or the main repo. For example to switch to a (very) old version:
If you are using a tap, and want to revert back to the current stable version
If you want to use a commandbox.properties
file as mentioned above, even though the symlink is added in /usr/local/bin
, your box
binary file will be in the /usr/local/Cellar/commandbox/<version>/libexec/bin/
directory where you should place your commandbox.properties
file. There will also be a box
binary in the /usr/local/Cellar/commandbox/<version>/bin/
directory where you should place the jre
if you want CommandBox to use a version of Java that is different from your default version reported by java -version
.
When using Homebrew to install CommandBox you must use Homebrew for any upgrade, minor or major. To upgrade CommandBox with Homebrew:
NOTE: If you use Homebrew to upgrade your version of CommandBox it will erase your /usr/local/Cellar/commandbox/<current_version>/
folder. So before upgrading, take a copy of your /usr/local/Cellar/commandbox/<current_version>/libexec/bin/commandbox.properties
file to drop back into /usr/local/Cellar/commandbox/<new_version>/libexec/bin/
before running box
for the first time after upgrading.
Unzip the binary box and just double click on it to open the shell terminal. When you are finished running commands, you can just close the window, or type exit
.
Hint You can place the binary in your
/usr/local/bin
directory so it can be available system-wide via thebox
command in any terminal window.
Please note that if you are running Ubuntu 18.04 or greater, or Debian 8 (Jessie) or greater, it's necesarry to have the
libappindicator-dev
package in order to have the tray icon working correctly.
Run the following series of commands to add the Ortus signing key, register our Debian repo, and install CommandBox.
( This first install routine also works for the Raspberry Pi. )
If you do not have Java installed you can install it with the following command.
Then run the box
binary to begin the one-time unpacking process.
Add the following to: /etc/yum.repos.d/commandbox.repo
Then run:
After you have downloaded the commandbox.deb
file, install it using the dpkg
command.
Run the box
binary to begin the one-time unpacking process.
After you have downloaded the commandbox.rpm
file, install it using the rpm
command.
Stable versions of CommandBox can be downloaded from the downloads section of our product page.
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:
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. .
Here are some common issues starting up CommandBox and troubleshooting help.
If you have a Windows machine which has been locked down to not allow DLL files in the user's appData
folder, you may receive a message similar to this when attempting to start CommandBox.
If you don't have the option of changing the security controls on your PC, then you can try changing your Windows environment variables of TMP
and TEMP
to repoint to another folder which does not have this restriction.
If you receive a message like the one above, which was taken from a Linux machine, when starting CommandBox, this means that you do not have Java installed. You can solve this in three ways: 1. Download the JRE-included CommandBox install which comes with a folder called jre
2. Download your own jre and place it in a folder called jre
in the same folder as the box
binary. 3. install Java onto your machine and ensure the correct JAVA_HOME
and JRE_HOME
environment variables are set.
CommandBox is a Java-based tool that involves several pieces including native Java classes, CFML code, and the embedded Railo CLI. However, most changes are confined to the CFML code managed by WireBox. To determine what version you have installed, use the version
command.
The auto-upgrade commands shown below will not upgrade the main CommandBox Java Binary. If there are any major upgrades to this binary, you will see a message that you will need to download the new Java binary and replace your current one.
To upgrade to the last stable version of the shell and commands, use the upgrade
command.
This command will connect to our server to determine the last stable build. If there is an upgrade, it will be downloaded and installed for you.
To upgrade to the bleeding edge version of the shell and commands, use the latest flag.
This command will connect to our server to determine the latest build. If there is an upgrade, it will be downloaded and installed for you.
If you already have the latest version installed, but you still want to force an upgrade, use the force parameter.
Note, if you delete your {user}/.CommandBox
folder and re-run the executable, the version of CommandBox in the executable will be unpacked regardless of any upgrades you may have installed in the mean time. On that note, another way to force an upgrade is to simply download the new executable, wipe the .CommandBox
folder in your user directory and re-run. This will also erase any saved command history, embedded servers, or installed user commands.
If you have used Hombrew to install CommandBox you must use Homebrew for any upgrade, minor or major. To upgrade CommandBox with Homebrew:
If you want to automate several commands from your native shell, it will be faster to use our recipe command that allows you to run several CommandBox commands at once. This will allow you to only load the CommandBox engine once for all those commands, but still be dumped back at your native prompt when done. Recipes can also just be useful for a series of commands you run on a regular basis.
Read more about the recipe command in our Command API docs.
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.
Technically a recipe can have any file extension, but the default recommendation is .boxr
which stands for "box recipe". Lines that start with a pound and whitespace characters (e.g. "# My Comments") will be ignored as comments. The pound character followed immediately by word-like characters is the mechanism for invoking CFML functions.
buildSite.boxr
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.
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.
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
.
Now let's look at the same recipe set up to receive positional parameters.
You would call it like so:
Output:
If an argument is not passed, you can use the default value mechanism:
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:
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 become 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.
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.
There are two ways to run commands via CommandBox: inside the CommandBox interactive shell, or one-at-a-time commands from your native shell.
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.
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.
The box
text is calling the CommandBox binary, and the version
bit is passed along to the CommandBox shell to execute once it loads.
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
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.
Pipe output into the grep command to apply a regex upon it. grep will only emit lines matching the regex.
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.
Redirect output into a file, overwriting if it exits like so:
Use the double arrows to append to an existing file.
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.
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:
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.
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.
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.
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.
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.
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.
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.
In the past, 99% of people used the Oracle (previously SUN) version of Java for all their Java needs. As of January 2019, the license is changing on Oracle Java which makes it no longer free for commercial use as well as the end of updates for Java 8. This has led to many people looking at alternatives to Oracle. Java itself is open source, so it will always be free and there are several other organizations offering their own builds of Java. If you want support, it matters which provider you get Java from.
This page is a work in progress to track the non-Oracle JREs and how to use them. Please send pull requests to this page with any additional information you have as this is a changing landscape right now.
You can read more about Oracle's changes in this post:
Corretto is a build of OpenJDK maintained by Amazon. It is free and will have long term support. Initial tests show that Corretto 1.8 works with CommandBox and ACF 11.
OpenJDK is Oracle's free version of Java. it comes with a 6 month support window. CommandBox has received a fair amount of testing on OpenJDK and everything seems to work.
Zulu is free and offers long term support. Zulu provides supported builds of OpenJDK. Initial tests show that Corretto 1.8 works with CommandBox and ACF 11.
When running box.exe
on Windows, the registry is used to determine the current versions of java that are installed. If you install a some non-Oracle JRE such as Corretto, you will not currently have the necessary registry entries created for box to find Java.
Oracle - No manual action needed
Azul - No manual action needed
OpenJDK - Manual creation of registry keys required
Corretto - Manual creation of registry keys required
You can manually create the needed keys by modifying and running the following registry entries. (Contributed by Jim Pickering)
The box
binary on *nix uses your OS environment variables to locate Java. In the 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.
And as always, on any operating system and with any JRE provider, you can override what version of java is used by creating a folder called JRE
in the same directory as the box
or box.exe
binary that contains the JRE you wish CommandBox to use. This will bypass all registry and env var checks above.
For macOS users who have installed CommandBox via HomeBrew, the installer creates a box
alias in /usr/local/bin/
which points to the box
binary in the /usr/local/Cellar/commandbox/<version>/bin/
directory. If you want CommandBox to use a particular version of the JRE
then put the jre
folder in the /usr/local/bin/
directory. If you want CommandBox to have a different home .CommandBox
directory, place your commandbox.properties
file in the /usr/local/Cellar/commandbox/<version>/bin/libexec/bin/
directory.
If you want to debug what JRE is being used by the CommandBox CLI, use the -clidebug
flag when starting CommandBox and the first few lines will tell you what version of Java is being used, and where on disk it lives.
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.
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.
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.
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.
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.
On Windows, /
or \
will be treated as the current drive root based on the current working directory. This is the same as DOS.
On all OS's, ~
will expand to the current user's home directory.
CommandBox's true power comes from it's command-based architecture, but we also support just running plain-jane .cfm files as well.
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:
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!
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
.
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()
.
As a handy shortcut, you can invoke the cfml
command by simply typing the name of the CFML function, preceded by a #
sign.
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' )
.
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")
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.
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.
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.
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.
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.
For a full list of all the commands that ship with CommandBox as well as all their parameters and samples, please visit our which are auto-generated each build.
To help organize our commands, we introduced the concept of namespaces. this means that commands can contain spaces and be comprised of more than one word. This is to keep things readable. Several commands that are all related will start with the same word, or namespace. An example of this is the namespace. It contains several commands inside of it including , , and . Calling each of them would look like this:
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 typinghelp
after the namespace.
Namespaces can be more than one level. Another example would be which contains commands such as , , and .
Commands can be aliased so you can call them more than one way, ever wanted to run an ls
command in Windows or a dir
command in Unix
? . Check the or the CLI help command to see if a command has aliases. For instance, the command is aliases as q
for quick typing. Another example would be the command that is aliased to just init
.
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!
Every command that executes has an exit code. Usually the exit code is 0 if the command ran as expected. If an error of any kind was encountered, then the exit code will be a non-zero number. Often times 1. You can easily see this if you install the module as it shows you the exit code of the last command to run. Commands such as testbox run
will return a failing exit code if the tests being run didn't all pass.
You can access the last exit code from CommandBox in a called exitCode
.
The CommandBox shell also keeps track of exit code of the last command. When the shell exits, it will report that last exit code to the OS. When running a one-off command from your native shell, the exit code of that command will be passed straight through to your native shell. This means that running something like
from a Travis-CI build will automatically fail the build if the tests don't pass.
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.
Similar to bash, CommandBox allows you to chain multiple commands together on the same line and make them conditional on whether the previous command was successful or not.
You can use &&
to run the second command only if the previous one succeeded.
You can use ||
to run the second command only if the previous one failed.
You can use a single semi colon (;
) to separate commands and each command will run regardless of the success or failure of the previous command.
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.
Returns a passing (0) or failing (1) exit code whether the path exists. In this example, we only run the package show command if the box.json
file exists.
You can specify if the path needs to be a file or a folder.
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
Returns a passing (0) or failing (1) exit code whether both parameters match. Comparison is case insensitive.
Hopefully this gives you a lot of ideas of how to start using CFML on your next automation task. And if you want even more control like print objects, object oriented code, and fancy parameters, look into making custom .
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.
If a parameter has any white space in it, you'll need to wrap the value in single or double quotes. It doesn't matter which kind you use and it can vary from one parameter to another as long as they match properly.
Quotes are actually allowed unescaped in a value, so long as they don't appear at the start of the string.
However, if the parameter contains white space and is surrounded by quotes, you'll need to escape them with a backslash.
Hint Only like quotes need to be escaped. Single quotes can exist inside of double and vice versa without issue. These examples below are perfectly valid.
Backticks 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.
If you have an equals sign in your value, you'll need to escape it with a backslash unless you've quoted the entire string.
Line breaks 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.
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.
Since the backslash is used as our escape character you'll need to escape any legitimate backslash that happens to precede a single quote, double quote, equals sign, or letter n.
This will print foo\=bar
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.
Here are examples of fully qualified paths in Windows and *nix-based:
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.
For a relative path, do not begin with a slash.
File system paths will be canonicalized automatically which means the following is also valid:
If you are on Windows, CommandBox supports UNC server shares bu accessing the name of the server or the IP address. Note, you can use forward or backslashes in Windows, but a UNC path MUST start with two backslashes.
Backslashes need to be escaped from the command line and in JSON, so most usage of UNC server paths will require you to type four slashes like \\\\
which will properly escape to \\
You cannot directly list the contents of a server like \\webdev01
as that is not a true directory. You always need to access a specific share like \\webdev01/webroot
.
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.
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.
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
.
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.
To extend the previous example, if we did models/**.cfc
that would match any cfc file in any subdirectory, no matter how deep.
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.
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 can be specified in any order and follow the format name=value
. Multiple named parameters are separated by a space.
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:
Of course, only the required parameters must be specified. I'm only including all of them here for the completeness of the example.
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.
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.
In addition to quoting parameter values, parameter names can also be quoted. This is useful when setting keys into settings or JSON files that have spaces, hyphens or special characters. Each of these examples are supported:
Each of those examples will create this in your box.json
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.
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.
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.
Hint This behavior is dependent on your operating system.
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.
!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.
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.
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:
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.
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.
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):
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.
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
.
When you prepare the native binary ahead of time and then pipe it into the run
command, you are allowed to pipe the result back into another CommandBox command in that specific case. This is only possible when run
appears with nothing after it.
You can pipe the output of a previous command in CommandBox directly to a native binary like so:
In this case, clip
is a Windows binary that will read the standard input and place that text on the clipboard. When the run
command receives two inputs, it will assume the first input is the piped input and the second input is the actual command to run.
You can even pipe commands to an interpreter that normally reads from a keyboard on the standard input, but be aware that some binaries such as Windows cmd
require line breaks after the input or it won't process. In the specific case of Windows cmd
it seems to require at least two line breaks for some reason (this is also true outside of CommandBox)
In the previous example we use a backtick expansion to grab a line feed from the CFML chr()
function.
There are limitations. When you pipe into the run
command, the command will not also be able to read from your keyboard (this is true of any shell) and it will execute in a non-interactive manner, which means the ping's output above would appear all at once as opposed to flowing in one line at a time.
When piping into the run
command you cannot also pipe the output of the run command like so:
As soon as any text appears after run
or !
, then the rest of the line is "eaten" and passed to the native shell.
Also you cannot build up a command like so and also pipe input into the native binary at the same time:
This is because only one parameter can be piped into a command at a time.
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.
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
)
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}
.
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.
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.
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.
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.
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.
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.
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:
Help is integrated at every level in CommandBox. You can help global help, namespace help, or command help at any time.
To get an overall list of all the commands you have available to run, simply type help
at the shell.
Next, drill down and get help on a specific namespace like server
.
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.
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.
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:
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
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
.
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.
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.
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.
You can test it out easily by outputting your system path like so:
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 system setting name will never contain a colon! Also do not use inner single quotes for system setting name nor the default value.
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:
Environment variables for the currently executing command
Environment variables for the parent (calling) command (if applicable)
Global shell environment variables
JVM System Properties in the CLI process
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.
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.
You can use system settings and environment variables in the REPL using the same syntax as the CLI
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.
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:
The SystemSettings
service also gives you programmatic access to individual system settings in your custom commands and task runners.
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.
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:
You can view the contents of that variable from anywhere in the same shell session like so:
Clear out an environment variable like so:
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.
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 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.
To view the environment variable for the current command context, run:
The output is a JSON serialized struct, which makes it suitable for programmatically accessing.
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.
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.
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:
The CFML code running that server process will be able to "see" the foo
environment variable.
The default namespace when using the ${foo}
system setting expansion syntax is box environment variable, Java system properties, and OS environment variables.
It is also possible to leverage built-in namespaces to allow expansions that reference:
server.json properties
box.json properties
arbitrary JSON file properties
Config settings (like the config show
command)
Server info properties (like the server info property=name
command)
Other properties in the same JSON file
server.json
propertiesIf the current working directory of the shell contains a server.json
file, you can reference any property in it with the serverjson.
namespace.:
if you have a server json file with a non-default name such as server-custom.json
then you can access it with the serverjson.
namespace.:
box.json
propertiesIf the current working directory of the shell contains a box.json
file, you can reference any property in it with the boxjson.
namespace.:
You can can reference properties from any JSON file with either a relative path (to the current working directory) or an absolute path with the json.
namespace..
You can expand any valid config setting with the configsetting.
namespace. So getting the same value you get when you run the command
can be expanded like this:
You can expand any valid server info property with the serverinfo.
namespace. So getting the same value you get when you run the command
can be expanded like this:
By default, the expansion looks at the default server in the current working directory. To grab a server property by server name, use this syntax:
You can self-reference other properties in the same JSON file using the @
namespace. So given the following JSON file:
The expansion of ${@appFileGlobs}
self-references the appFileGlobs
property inside the same file, allowing for easy re-use of that value.
Modules can register an onSystemSettingExpansion interceptor to contribute custom system setting namespace expansions. The interceptor gets the following data in interceptData
setting - The name of the setting to be expanded (with ${} and :defaultValue removed)
defaultValue - The default value, or empty string if none specified
resolved - A boolean that should be set true if the interceptor was able to resolve the setting
context - A struct of the original JSON being expanded or the parameters from the command line where the expansion was used.
A hypothetical example would be:
And then we would use our hypothetical namespace to reference any Lucee information like so
It's important if you implement your own onSystemSettingExpansion
interceptor that you check the incoming setting to see if it applies to you. If you process the system setting, you must place the final expanded value back in the interceptData.setting
struct key, set interceptData.resolved
to true
and return true
from the interception method so the chain stops processing.
For a full list of all the commands that ship with CommandBox as well as all their paramaters and samples, please visit our 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.
Sometimes, you need to view the CommandBox log file. Maybe it is to debug a command you are writing or to . 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:
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:
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.
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.
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.
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.
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)
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.
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
.
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.
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 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.
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.
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.
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
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.
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...
the coldbox namespace will be filled in and followed by a space so you are ready to continue typing.
If you then press tab again, you will be presented with a list of second-level namespaces inside of coldbox and the same prompt will be output again below it so you can continue typing.
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!
Here is CommandBox giving every option possible for the delete command. Note, force and recurse are booleans, so they can be specified as flags.
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.
Here, all files and folders in the current working directory are offered as possibilities for the path parameter of the delete command.
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.
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
.
Commands have the ability to give hints in the form of a static list or a runtime function with dynamic output.
Here the forgebox show command dynamically provides completion for its type
attribute based on the current types returned by the ForgeBox REST API.
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
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.
Install the module like so:
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.
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!
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.
There are some specific commands that make use of the Watcher library in CommandBox such as testbox watch
and coldbox watch-reinit
. However, there is also a generic watch command that will run any arbitrary command of your choosing when a path matching your file globbing pattern is added/updated/deleted.
The following environment variables will be available to your command
watcher_added - A JSON array of relative paths added in the watch directory
watcher_removed - A JSON array of relative paths removed in the watch directory
watcher_changed - A JSON array of relative paths changed in the watch directory
Since escaping meta characters can get tricky with nested strings, you can declare the command as an environment variable and then just reference it like so:
That example runs the foreach
command over each item in the watcher_added
array and then runs an echo
statement to output the name of each added path.
Note that the "paths" here work more like .gitignore
entries and less like bash paths. Specifically:
A path with a leading slash (or backslash), will be evaluated relative to the current working directory. E.g. watch /foo
will only watch files in the directory at ./foo
, but not in directories like ./bar/foo
.
A path without a leading slash (or backslash) will be applied as a glob filter to all files within the current working directory. E.g. watch foo
will result in the entire working directory being watched, but only files matching the glob **foo
will be processed.
If your watcher seems slow, unresponsive, or is failing to notice some file change events, it is likely that you have it watching too many files. Try specifying more specific paths to the files you want to process, and use leading slashes in your arguments to avoid watching all files in the current working directory.
paths
- Comma-delimited list of file globbing paths to watch relative to the working directory, defaults to **
excludePaths
- Comma-delimited list of file globbing paths to exclude relative to the working directory.
command
- The command to run when the watcher fires
delay
- How may milliseconds to wait before polling for changes, defaults to 500 ms
directory
- Working directory to start watcher in
verbose
- Output details about the files that changed
There is a sql
command which will accept any sort of data as JSON, marshal it into a query object and allow you to alias, filter, order, and limit the rows on the fly using CFML's query of queries.
data
- The JSON to process
select
- A SQL list of column names, eg. "name,version"
where
- A SQL where filter used in a query of queries, eg. "name like '%My%'"
orderby
- A SQL order by used in a query of queries, eg. "name asc, version desc"
limit
- A SQL limit/offset used in a query of queries, eg. "5" or "5,10" (eg. offset 5 limit 10)
headerNames
- An list of column headers to use (used for array of arrays)
When using an array of arrays and not specifying headerNames
, the columns will be named col_1
, col_2
, col_3
, etc...
Filter, sort, limit, and select extensions installed into the CLI (output as table)
Order and select JSON data from a file (output as JSON)
Limit JSON (output as table)
The sql
command works very nicely with the tablePrinter
command.
JSON Query command for filtering data out of a JSON Object, file, or URL. jq is a query language built specifically for interacting with JSON type data. More information can be found at as well as an online version to test your query Pass or pipe the text to process or a filename
@
- Current Node (eg. current number/string/array/object) used to evaluate or check value
&
- Expression (Function or Keyname) (eg. &to_number() or &keyname)
!
- NOT Expression
&&
- AND expression
||
- OR expression
{'ab':true}
- Literal Expressions (this will be converted to json)
'foo'
- Raw String Literals not evaluated (Single Quotes)
length, reverse, type, not_null
to_list, to_array, to_string, to_number
abs
, ceil
, floor
ends_with
, starts_with
, contains
A common example would be getting a person with the highest or lowest networth max_by(people, &abs(net_worth))
avg: ( ARR )
- convert array of number to average (ex. [1,2,3] -> 2)
first: ( ARR/STR )
- convience method to get the first item
group_by: ( ARR )
- Splits a collection into sets
join: ( ARR, STR )
- concatenate an array of strings/numbers with a provided delimiter to a string
last: ( ARR/STR )
- convience method to get the last item
matches: ( STR/ARR, searchTerm )
- regex match string
min: ( ARR )
- get the minimum string/number/dates of an array (ex. [1,2,3] -> 1)
max: ( ARR )
- get the maximum string/number/dates of an array (ex. [1,2,3] -> 3)
reverse: ( STR/ARR )
- returns a reversal of a string or array
sum: ( ARR )
- convert array of number to sum (ex. [1,2,3] -> 6)
sort: ( STR_ARR/NUM_ARR )
- sorts an array of strings/numbers/dates
split: ( ARR/STR, STR )
- splits strings into arrays
unique/uniq: ( ARR )
- remove duplicates
defaults: ( OBJ/ARR, OBJ )
- sets default values if missing on 1 or more structs
key_contains ( OBJ, &KeyName )
- boolean check if struct contains key name
from_entries ( OBJ/ARR )
- converts a {type:orange}
-> {key: type, value:orange}
keys: ( OBJ/ARR )
- returns an array of keys
max_by: ( ARR,Function/Key )
- same as min but targets a key inside the array and returns a single struct
merge: ( OBJ/ARR, ...)
- Merges objects into one single object with overwrite
min_by: ( ARR,Function/Key )
- same as max but targets a key inside the array and returns a single struct
omit ( OBJ/ARR, STR/ARR )
- loops over 1+ struct and excludes keys provided to_pairs: ( OBJ/ARR )
- converts a {type:orange}
-> [[type, orange]]
pluck ( OBJ/ARR, STR/ARR )
- loops over 1+ struct and only includes keys provided
sort_by: ( ARR, Function/Key )
- same as sort but targets a key inside the array and returns the entire array
to_entries ( OBJ/ARR )
- converts a {type:orange}
-> {key: type, value:orange}
values: ( OBJ/ARR )
- returns an array of values
map: ( Function/Key, ARR )
-
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.
CommandBox has a helper for printing ASCII Art tables in your custom commands and task runners called print.table()
. We've taken this a step further and wrapped the table printer utility in a new command so you can use it from the CLI directly. The printTable
command will accept ANY data in as JSON and it will marshal it into a query for you. This means it can be a query, an array of structs, an array or arrays, and more. You can now get quick and easy visualization of any data right from the CLI or in builds.
data
- JSON serialized query, array of structs, or array of arrays to represent in table form
includeHeaders
- A list of headers to include.
headerNames
- A list/array of column headers to use instead of the default specifically for array of arrays
debug
- Only print out the names of the columns and the first row values
When using an array of arrays and not specifying headerNames
, the columns will be named col_1
, col_2
, col_3
, etc...
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!
A plugin to run your Commandbox tasks from within Sublime plus some handy snippets too.
Install Via Package Control Commandbox
If you have PackageControl installed, you can use it to install the package.
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.
You can clone the repo in your /Packages
(Preferences -> Browse Packages...) folder and start using/hacking it.
If you are having trouble running the plugin in Mac OSX it's possible that your path isn't being reported by your shell. In which case give the plugin SublimeFixMacPath a try. It may resolve our issue.
If you still can't get it to run properly, first make sure your Commandbox tasks run from a terminal (i.e. outside of sublime) and if so then submit an issue.
You may select pre-configured commands from Menu -> Commandbox
, including the ability enter a custom command.
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 )
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:
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
If set to true
, a new tab will be used instead of a panel to output the results.
Defines the delay used to autoclose the panel or tab that holds the Commandbox results.
If true it will open the output panel when running Commandbox (silent)
only if the task failed
Toggles the creation of sublime-commandbox.log
if any error occurs.
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).
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
.
You can use a shortcut for running a specific task like this:
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.
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!
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:
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.
The names and numbers of each color are unique and important if you want to do any Task Runners, custom commands that make use of these colors. Modules like Bullet Train also allow you to customize their colors. You can specify a color by its name like LightGoldenrod5
or its number (221
).
In a Task Runner or custom command, the print helper would look like this:
Here's an example of customizing your Bullet Train module to use fancy colors. (Color 21 is Blue1
)
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.
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
Set item in an array
Set multiple params at once
Override a complex value as JSON
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.
Output a setting:
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
using JMESPath filter on the config show command
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.
If you need to use CommandBox behind a corporate proxy, these settings will be necessary for it to successfully connect to the Internet.
string
This is the URL of the proxy server on your network.
integer
This is the port to connect to on the proxy server.
string
This is the username to connect to the proxy server with, if required.
string
This is the password to connect to the proxy server with, if required.
These settings affect how CommandBox loads modules.
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.
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.
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.
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
.
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:
Here are suggestions for using VSC (Visual Studio Code) for developing in CFML.
What do you want to do with VSC?
Install it?
Key Extensions?
Working with the shell/terminal
Git Extensions?
This IDE has it's own domain. ( ) with downloads for macOS, Windows and Linux on the home page. :+1:
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.
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.
Install Shell Launcher and reload the IDE.
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"
}
],
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.
You should also install a few extensions. (These extensions can also be added from the built in Extensions item.)
Additional Extensions ( of course, choose the ones you want and ignore the others )
More information to follow. (Including video guides to show how to get started that may not be as familiar with different parts.)
These settings are used to configure CommandBox's endpoints.
Whenever possible, use the forgebox endpoint
namespace unless you are setting things manually when those settings not supported by those commands.
string
The API Token provided to you when you signed up for . This will be set for you automatically when you use the forgebox register
or forgebox login
commands. This token will be sent to ForgeBox to authenticate you. Please do not share this secret token with others as it will give them permission to edit your packages!
string
This is the URL of the ForgeBox REST API. Remove this setting to use the default. If you wish change the default Forgebox entry to point to your ForgeBox Enterprise you can do that here. Note, this will funnel ALL ForgeBox calls to the enterprise server where your APIToken may be different. We recommend custom endpoints as an alternative to overriding the default.
You can register a new endpoint with forgebox endpoint register myEndpoint "https://forge.intranet.local/api/v1"
You can see all of your current endpoints with forgebox endpoint list
which will list out all of your endpoints, including indicating the default endpoint.
To view this as JSON we can run config show endpoints
and you'll see what this looks like in the config structure.
When setting APIToken
and APIURL
for Custom Endpoints, it is a little different, you must use ForgeBox-YOURENDPOINTNAME
in the commands to match the data structure.
string
The API Token provided to you when you signed up for your Custom ForgeBox Site/Appliance. This will be set for you automatically when you use the forgebox register
or forgebox login
commands if this endpoint is the default, or if you use forgebox login endpointName=mycompany
if mycompany is not the default. This token will be sent to the ForgeBox endpoint to authenticate you. Please do not share this secret token with others as it will give them permission to edit your packages!
string
This is the URL of the ForgeBox REST API for your custom endpoint. Note, this will funnel ALL ForgeBox calls to this URL if this endpoint is the default, or if you use forgebox publish endpointName=mycompany
if mycompany is not the default.
Easily launch multiple shell configurations in the terminal.
This will take your git IDE to new levels.
Add TODO, FIXME or other comments to code and find quickly with this extension.
: save folders as projects and easily switch between projects
: integrated Mercurial source control
Because it is more fun, nuff said!
You can create your own endpoints usually when you have an appliance, and change the default from ForgeBox to your own if desired. All commands will assume the endpoint is the default unless override with the forgebox publish endpointName=MYENDPOINT
or forgebox whoami endpointName=MYENDPOINT
for example.
boolean
Every time you execute a task runner,
Lucee template cache is cleared
WireBox's metadata cache is cleared
Wirebox's mapping for the CFC is unmapped and remapped
This ensure changes take affect right away, but can cause issue under load when you have multi-threaded execution of more than one task at the same time. To skip these cache clearing steps on every run for multi-threaded production use, add the following config setting.
The setting defaults to false.
You can customize the way that JSON is formatted when it's written to files such as server.json
and box.json
as well as how it displays in the console when using commands such as server show
and package show
string
String to use for indenting lines. Defaults to four spaces.
string
String to use for line endings. Defaults to CRLF on Windows and LF on *nix. Pass the actual character to use, not a placeholder.
boolean
Add space after each colon like "value": true
instead of "value":true
Defaults to false
string
Specify a sort type to sort the keys of json objects: text
or textnocase
struct
A struct of colors to use when displaying JSON in the CLI. You can use any color name from the system-colors
command or a direct ANSI escape sequence.
string
The color to use for constant values (true/false/null). Defaults to "red".
string
The color to use for object key names. Defaults to "blue".
string
The color to use for numbers. Defaults to "aqua".
string
The color to use for quoted string values. Defaults to "lime".
Every Config Setting can be overridden by convention by creating environment variables in the shell where you run box
. This is idea for CI builds were you want to easily set ForgeBox API keys, or tweak settings for your build. You set set these as actual environment variables or Java system properties of the CLI.
The var must start with the text box_config_
and will be followed by the name of the setting.
For nested settings inside of a struct or array you can use underscores to represent dots.
The overrides are applied using the same mechanism that the config set
command uses, which means you can also pass JSON directly for complex values.
On OS's like Windows which allow for any manner of special characters, you can provide any string which would also be valid for the config set
command. Ex:
When you provide JSON, the append
flag will be set to true when adding the configuration to what's already in CommandBox.
Overridden env vars will not be written to the CommandBox.json
file and will be lost when box stops. They will also take precedence and override any explicit settings already set.
These are some one-off settings that doen't really belong anywhere else.
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.
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.
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.
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.
boolean
You can enable this setting if you want to force CommandBox to output ANSI formatting code even though you're running box inside of a non-interactive terminal. This is handy for CI builds such as Gitlab, which will process color coded text in your job logs. Default value is false
.
string
Used to override the default browser to open when a server starts, or when using a command like server open
or calling the openURL()
method from a command or Task Runner. Possible values are:
firefox
chrome
opera
edge (Windows and Mac only)
ie (Windows only)
safari (Mac only)
konqueror (Linux only)
epiphany (Linux only)
boolean
You can change CommandBox's default tab completion to be an inline list that follows your cursor. This setting requires you to close and re-open the shell to take affect.
One of the most useful features of CommandBox is the ability to start an ad-hoc server quickly and easily. Any folder on your hard drive can become the web root of a server. To start up the server, cd
into a directory containing some CFML code, and run the start
command. An available port will be chosen by default and in a few seconds, a browser window will open showing the default document (index.cfm
).
To stop the embedded server, run the stop
command from the same directory.
You can start as many embedded server instances as you want. Each running server will add an icon in your system tray with the logo of your currently running engine. Click on it for options:
Stop Server
Open Browser
Open Admin
Open File System
If you don't want the tray integration, then you can turn it off in your server.json
with this setting.
Or turn it off at a global level in your config settings.
CommandBox's embedded server does not require any prior installations of any CFML engine to work. It does not use Apache, IIS, or Nginx. A very lightweight Java web server called Undertow is used and a context is programmatically deployed via a WAR file.
You should still have all the options you need to set up most local development servers quickly. The web-based administrator is available to you where you can edit any setting, add data sources, CF mappings, and mail servers. To see a list of all the parameters you can pass to the server start
command, refer to the CommandBox API Docs or run server start help
command directly from the CLI.
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:
The CFML code running that server process will be able to "see" the foo
environment variable.