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

Elevate Your ColdBox Experience and Skills

Elevate Your ColdBox Experience and Skills

We're thrilled to announce a significant overhaul of our ColdBox training experience to ensure it's nothing short of extraordinary! We've listened closely to your feedback and made significant improvements geared towards transforming you into a ColdBox superhero. Learn What's New!

Maria Jose Herrera
Maria Jose Herrera
February 20, 2024
Ortus Redis Extension v3.3.0 Released!

Ortus Redis Extension v3.3.0 Released!

We are very excited to bring you another release for our Redis Lucee Extension. The most significant feature in this release is the addition of the `` and `redisLock{}` tag, which allows you perform a lock across all instances in a cluster.

Ortus Redis Extension v3.3.0 gives you greater control over concurrent modifications in a distributed environment, utilizing your distributed cache to prevent overlaps!

Jon Clausen
Jon Clausen
February 16, 2024
Introducing: 102 ColdBox HMVC Tips and Tricks

Introducing: 102 ColdBox HMVC Tips and Tricks

In this comprehensive guide, you'll discover a treasure trove of insights tailored to help you build sustainable ColdFusion applications using ColdBox HMVC. But that's not all – we've also included invaluable tips and tricks for companion libraries like CommandBox, WireBox, LogBox, CacheBox, and TestBox. Whether you are a beginner or a seasoned pro, you'll find something to elevate your skills and streamline your development process.

Maria Jose Herrera
Maria Jose Herrera
February 15, 2024