CFConfig 1.4.0 released!

Brad Wood July 13, 2021

Spread the word

Brad Wood

July 13, 2021

Spread the word

Share your thoughts

Today we've released a new version of CFConfig-- your friendly neighborhood CLI for configuring Adobe and Lucee servers.  CFConfig sees a lot of little releases that we don't announce, but they are usually very small little releases adding a single setting here or there.  Today's release has a nice collection of brand new features that seemed worth talking about.

Get the new version

To play with the latest version of CFConfig, just run

CommandBox> update --system

The latest docs are located here:

If you find any issues or bugs, please report them right away in Slack or our ticket system, JIRA.

New Features

Here's an overview of the new things we've added.

IncludeList and excludeList

This feature applies to the following commands:

  • cfconfig import
  • cfconfig export
  • cfconfig transfer

You can customize what config settings are transferred with the includeList and excludeList params. If at least one include pattern is provided, ONLY matching settings will be included. Nested keys such as datasources.myDSN or mailservers[1] can be used. You may also use basic wildcards in your pattern. A single * will match any number of chars inside a key name. A double ** will match any number of nested keys.

# Include all settings starting with "event"
cfconfig transfer from=.CFConfig.json includeList=event*
# Exclude all keys called "password" regardless of what struct they are in
cfconfig transfer from=.CFConfig.json excludeList=**.password

Append flag

This feature applies to the following commands:

  • cfconfig import
  • cfconfig export
  • cfconfig transfer
  • cfconfig set

Use the append parameter to merge incoming data with any data already present. For example, if a server already has one datasource defined and you import a JSON file with 2 more unique datasources, the --append flag will not remove the pre-existing one.

cfconfig transfer from=.CFConfig.json includeList=datasources --append
cfconfig set datasources={"brad":{"class":"test","dbdriver":"name"}} --append

JSON Expansion Replacements

This feature applies to the following commands but ONLY where the "to" destination is a JSON file:

  • cfconfig import
  • cfconfig export
  • cfconfig transfer

Note, the replace:foo=bar syntax below will work on the cfconfig transfer command, but due a dependency on a new feature in the bleeding edge of Commandbox, you'll need to be on the bleeding edge of CommandBox 5.4 to use it with cfconfig export and cfconfig import.

If you usually replace sensitive or volatile information in a JSON export with env var expansions like $ {DB_PASSWORD}, you can do this automatically my supplying one or more replace mappings. The key is a regular expression to match a key in the format of datasources.myDSN.password and the value is the name of the env var to use. The values will be written to a .env file in the current working directory. You can override this path with the dotenvFile param, or pass an empty string to disable it from being written.

cfconfig transfer to=.CFConfig.json replace:datasources\.myDSN\.password=DB_PASSWORD

Remember, the first part of your replace is a regular expression so make sure you use proper syntax!

As the value is a regular expression, you can use back references like \1 in your env var to make them dynamic. This example would create env vars such as DB_MYDSN_PASSWORD where MYDSN is your actual datasource name.

cfconfig tranfser to=.CFConfig.json replace:replace:datasources\.(.*)\.password=DB_\1_PASSWORD

Any valid regex is possible for some clever replacements. This example would create env vars such as DB_MYDSN_PORT, DB_MYDSN_HOST, and DB_MDSN_DATABASE

cfconfig tranfser to=.CFConfig.json replace:datasources\.(.*)\.(password|class|port|host|database)=DB_\1_\2 dotenvFile=../../

To avoid having to pass these replacements every time you transfer your config, you can set then as a global setting for the commandbox-cfconfig module.

# Replace all mail server passwords with $ {MAIL_PASSWORD}
config set modules.commandbox-cfconfig.JSONExpansions[mailServers.*.password]=MAIL_PASSWORD

# Dynamically replace with $ {DB_MYDSN_password}, $ {DB_MYDSN_CLASS}, $ {DB_MYDSN_PORT}, etc
config set modules.commandbox-cfconfig.JSONExpansions[datasources\.(.*)\.(password|class|port|host|database)]=DB_\1_\2

# Use default env var name for all settings starting with "requestTimeout" and replace with $ {REQUEST_TIMEOUT} and $ {REQUEST_TIMEOUT_ENABLED}
config set modules.commandbox-cfconfig.JSONExpansions[requestTimeout.*]=

Note, the config set syntax shown above require at least CommandBox 5.4.0

Using "deep" property names

This feature applies to the following commands:

  • cfconfig show
  • cfconfig set

The cfconfig set and cfconfig show commands now work the same as package set/show in that you can use "deep" keys to access nested properties.

cfconfig show datasources.myDSN
cfconfig show mailServers[1].port
cfconfig set loggers.deploy.level=debug
cfconfig set datasources.myDSN.password=myPass

Keep in mind that examples such as the last line above can create invalid config if you don't already have a datasource called myDSN.  If you're needing to create new complex objects, or you're not sure if they will exist, use the other CFConfig namespaces like cfconfig datasource save which will ensure complete settings are saved.


Add Your Comment


Aug 25, 2021 17:31:15 UTC

by Mark Drew

What about the other way, where I want to provide the values for env files ? for example: 1. I have a config.json (with something like ${PASSWORD} in it) 2. I want to create a lucee-server.xml from it 3. I have a .env file with PASSWORD=ortus 4. I would expect I can do: cfconfig import from=.CFConfig.json to=lucee-server.xml toFormat=LuceeServer@5 dotenvfile=.env 5, And now have a .xml file with the word "ortus" in it instead of blank or ${PASSWORD}

Aug 25, 2021 17:59:55 UTC

by Brad Wood

The "other way" has always worked, but it's not quite as you showed. Firstly, you don't point directly to the XML file, just the Lucee home directory where you want the config written as shown here: Assuming this server already exists, you also don't even need the toFormat and CFConfig will figure that out. And finally, you don't need to specify the .env file anywhere in the command. Assuming you have the commandbox-dotenv module installed, the .env file will just automatically get picked up and any properties defined in it will be available to the command. If you wanted to load some arbitrary file of properties in a different folder, you can always just call the "dotenv load" command to load them up first.

Recent Entries

CBWIRE 3.0.0 Released

CBWIRE 3.0.0 Released

We are very excited to announce the release of version 3 of CBWIRE, our ColdBox module that makes building modern, reactive apps a breeze. This version brings with it a new component syntax, 19 enhancements and bug fixes, and improved documentation. Our biggest goal with this release was to improve the developer experience and to provide a low barrier to entry to getting started with CBWIRE.

Grant Copley
Grant Copley
May 22, 2023
ColdBox 7.0.0 Released

ColdBox 7.0.0 Released

Introducing ColdBox 7: Revolutionizing Web Development with Cutting-Edge Features and Unparalleled Performance

We are thrilled to announce the highly anticipated release of ColdBox 7, the latest version of the acclaimed web development HMVC framework for ColdFusion (CFML). ColdBox 7 introduces groundbreaking features and advancements, elevating the development experience to new heights and empowering developers to create exceptional web applications and APIs.

Designed to meet the evolving needs of modern web development, ColdBox 7 boasts a range of powerful features that streamline the development process and enhance productivity. With its robust HMVC architecture and developer-friendly tools, ColdBox 7 enables developers to deliver high-performance, scalable, and maintainable web applications and APIs with ease.

Esme Acevedo
Esme Acevedo
May 16, 2023
TestBox v5.0.0 Released!

TestBox v5.0.0 Released!

We are excited to announced the release of Testbox version 5, which brings a host of new features and improvements for developers. TestBox is a powerful and flexible tool that helps developers write comprehensive BDD/TDD tests for their applications, ensuring code quality and reducing the likelihood of bugs and errors. With TestBox v5, developers can take advantage of new features such as batch code coverage testing, improved reporting capabilities, method spies, and better integration with other tools in the Ortus suite.

These new features make TestBox even more versatile and user-friendly, and provide developers with a powerful tool for building high-quality, reliable applications.


Luis Majano
Luis Majano
May 11, 2023