These settings affect how CommandBox loads modules.

ModulesExternalLocation

array

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

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

modulesInclude

array

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

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

ModulesExclude

array

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

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

modules.*

struct

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

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

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

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

config show modules.TestModule

You can 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

JSON.indent

string

String to use for indenting lines. Defaults to four spaces.

config set JSON.indent="  "

JSON.lineEnding

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.

config set JSON.lineEnding=`#chr 10`

JSON.spaceAfterColon

boolean

Add space after each colon like "value": true instead of "value":true Defaults to false

config set JSON.spaceAfterColon=true

JSON.sortKeys

string

Specify a sort type to sort the keys of json objects: text or textnocase

config set JSON.sortKeys=textnocase

JSON.ANSIColors

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.

JSON.ANSIColors.constant

string

The color to use for constant values (true/false/null). Defaults to "red".

config set JSON.ANSIColors.constant=PaleTurquoise1

JSON.ANSIColors.key

string

The color to use for object key names. Defaults to "blue".

config set JSON.ANSIColors.key=Purple5

JSON.ANSIColors.number

string

The color to use for numbers. Defaults to "aqua".

config set JSON.ANSIColors.number=SeaGreen3

JSON.ANSIColors.string

string

The color to use for quoted string values. Defaults to "lime".

config set JSON.ANSIColors.string=MistyRose3

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

proxy.server

string

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

config set proxy.server=myProxy.com
config show proxy.server

proxy.port

integer

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

config set proxy.port=9000
config show proxy.port

proxy.user

string

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

config set proxy.user=proxyUser
config show proxy.user

proxy.password

string

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

config set proxy.password=proxyPass
config show proxy.password

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

Set Config Settings

config set name=mySetting

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

Set module setting

config set modules.myModule.mySetting=foo

Set item in an array

config set myArraySetting[1]="value"

Set multiple params at once

config set setting1=value1 setting2=value2 setting3=value3

Override a complex value as JSON

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

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

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

Show Config Settings

Output a setting:

config show settingName

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

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

using JMESPath filter on the config show command

#normal selections like above just appended with the special `jq:` filter key
config show jq:modules.myModule.settingName
config show jq:mySettingArray[1]

# filter struct to just show name and modules values
config show 'jq:{name:name, modules:modules}'

# return all the key names from modules
config show 'jq:keys(modules)' 

# return all the key names from modules where key contains the string 'book'
config show "jq:key_contains(modules,'book')"

# get command aliases and assign they key and value to {key: keyname, value: value}
config show 'jq:to_entries(command.aliases)'
[
    {
        "key":"git ",
        "value":"!git "
    }
]

Clear Config Setting

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

config clear description

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.

Default ForgeBox Endpoint

endpoints.forgebox.APIToken

string

The API Token provided to you when you signed up for ForgeBox.io. 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!

config set endpoints.forgebox.APIToken=my-very-long-secret-key
config show endpoints.forgebox.APIToken

endpoints.forgebox.APIURL

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.

forgebox endpoint register forgebox https://mycompany.forgebox.io/api/v1 --force 
# or
config set endpoints.forgebox.APIURL=https://mycompany.forgebox.io/api/v1
config show endpoints.forgebox.APIURL

Custom Endpoint Settings

You can create your own endpoints usually when you have an ForgeBox Enterprise 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.

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.

Endpoint: forgebox (Default)
  API URL: https://www.forgebox.io/api/v1/

Endpoint: mycompany
  API URL: https://mycompany.forgebox.io/api/v1

To view this as JSON we can run config show endpoints and you'll see what this looks like in the config structure.

{
    "forgebox":{
        "APIToken":"YOUR-API-TOKEN-HERE"
    },
    "forgebox-mycompany":{
        "APIURL":"https://forgebox.stg.ortushq.com/",
        "APIToken":"YOUR-COMPANY-FORGEBOX-API-TOKEN-HERE"
    }
}

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.

endpoints.forgebox-MYENDPOINTNAME.APIToken

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!

config set endpoints.forgebox-mycompany.APIToken=my-very-long-secret-key
config show endpoints.forgebox-mycompany.APIToken

endpoints.forgebox-MYENDPOINTNAME.APIURL

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.

forgebox endpoint register mycompany https://mycompany.forgebox.io/api/v1 --force 
# or
config set endpoints.forgebox-mycompany.APIURL=https://mycompany.forgebox.io/api/v1
config show endpoints.forgebox-mycompany.APIURL

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.

box_config_colorInDumbTerminal=true

For nested settings inside of a struct or array you can use underscores to represent dots.

box_config_endpoints_forgebox_APIToken=my-token-here

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.

# JSON which will be parsed
box_config_proxy={ "server" : "localhost", "port": 80 }

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:

# dot-delimited keys
box_config_endpoints.forgebox.APIToken=my-token-here
# array indexes too
box_config_foo.bar[baz].bum[1]=test

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.

taskCaching

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.

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

nativeShell

string

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

tagVersion

boolean

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

tagPrefix

string

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

artifactsDirectory

string

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

colorInDumbTerminal

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.

preferredBrowser

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)

tabCompleteInline

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.

developerMode

The developerMode setting reloads shell before each command to help testing changes to CommandBox core or modules.

It will prevent you from needing to use the reload command, but it will cause a delay before each command. Don't forget to turn this back off when you're done.

terminalWidth

Terminal width can be overridden for entire CLI. This will affect ASCII art, interactive job output, progress bars, and the table printer.

offlineMode

The offlineMode setting will disable most external HTTP calls. This can be useful for

• testing production server starts to ensure they aren’t reliant on external calls

• running box in a secure network which blocks or flags any external access

This setting is obeyed in the following parts of CommandBox:

• commandbox-update-check module

• installation endpoints

  • forgebox

  • http/https/cached+http/cached_https

  • git/git+ssh/git+https/github

  • java

  • lex

  • jar

  • CFLib

  • S3

• upgrade command

• inside the progressable downloader class

These settings control how servers start in CommandBox.

server.defaults

struct

This struct can contain any . These settings are used as global default settings if there is not a corresponding setting provided by the user via a parameter to the start command or in the server's server.json file.