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

Ortus Solutions Soars Back to CFCamp Munich as Platinum Sponsor and Keynote Presenter!

Ortus Solutions Soars Back to CFCamp Munich as Platinum Sponsor and Keynote Presenter!

We're thrilled to announce that Ortus Solutions is returning to CFCamp Munich for another year! We're incredibly proud to be a continuing sponsor of this fantastic event and can't wait to connect with the ColdFusion community once again.

Taking Center Stage with the Day 1 Keynote

Get ready for some deep dives into the world of BoxLang! Ortus Solutions will be kicking off CFCamp with a dynamic keynote address on day 1. This is your chance to gain valua...

Cristobal Escobar
Cristobal Escobar
May 28, 2024
Into the Box 2025 - Blind Tickets are Out!

Into the Box 2025 - Blind Tickets are Out!

Ortus Solutions is thrilled to announce the release of blind tickets for Into the Box 2025, the premier event for web developers. This year's conference promises to be a game-changer, especially with the unveiling of our groundbreaking new product, BoxLang. **Our team is working hard to get all modern CFML developers amazing tools and software features to improve their productivity. **

Maria Jose Herrera
Maria Jose Herrera
May 27, 2024
Into the Box - Keynote Recap Day 1

Into the Box - Keynote Recap Day 1

Day 1 of Into the Box kicked off with an electrifying keynote session that set the tone for an incredible conference. The excitement was palpable as developers, tech enthusiasts, and industry leaders gathered to explore the latest innovations and trends in web development.

Maria Jose Herrera
Maria Jose Herrera
May 24, 2024