Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
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".
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 settings control how servers start in CommandBox.
struct
This struct can contain any setting that is valid in a server.json
file. 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.
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.
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:
If you are authenticated to ForgeBox in the CLI, you can synchronize your config settings to and from your ForgeBox account. This is a great way to get up and running on a new PC, or keep multiple CommandBox installs in sync with each other. In addition to synchronizing your Config Settings, this feature will also track your installed system modules, such as CFConfig, etc.
In order to sync your settings and modules, you must first be logged into ForgeBox. Check and see if you are logged in with
If necessary, log in with
Now you can synchronize your settings.
This command will push your local settings and modules up to your ForgeBox account.
By default, the settings are "merged" so new local settings will be added to ForgeBox, but nothing will be removed. In order to remove config that only exists on ForgeBox, you can use the --overwrite
flag to force a full sync.
This command will pull your settings and modules from your ForgeBox account and set/install them locally.
By default, the settings are "merged" so missing settings will be added locally and missing system modules will be installed, but nothing will be removed. In order to remove config and modules that only exists locally, you can use the --overwrite
flag to force a full sync. This will remove local config settings and uninstall local system modules which were not on ForgeBox.
This command will not change anything, but gives you a full report of all settings which are different between your local CommandBox CLI and ForgeBox. It will show you "Remote Only", "Local Only", and "Changed" settings and modules. Use this to see what you're about to change prior to pushing or pulling.
If you are logged into ForgeBox and have a ForgeBox Pro account, your settings will automatically sync for you. If
the user is logged into forgebox
the user has a ForgeBox Pro account
the CLI is not in Offline mode
The autosync feature is not disabled
then CommandBox will auto-sync ForgeBox settings based on these rules
Pull new settings from ForgeBox when …
CLI Starts (interactive)
logging into forgebox
switching forgebox users
Push config to ForgeBox when…
config settings get updated
a system module is installed
a system module is uninstalled
The forgebox endpoint used will be
The endpoint configured in config settings for autosync
the configured default forgebox endpoint
“forgebox”
The following autosync settings can be used to control this.
configAutoSync.enable
Enable or disable autosync entirely.
configAutoSync.endpoint
Name of the ForgeBox endpoint to sync to. Only use this if you have a ForgeBox Enterprise account with your own custom ForgeBox URL.
configAutoSync.overwrite
Enable to disable whether syncing overwrites changes. See the docs for the overwrite
parameter to the config push and pull commands for more details. This setting basically just defaults that parameter.
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 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!
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 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.
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.
These are some one-off settings that doesn'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 overridden 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)
Note, the preferred browser can also be overridden on a per-server basis in the server.json
for that server like so:
This will override the browser which auto-opens on server start as well as the server open
command.
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.
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.
Terminal width can be overridden for entire CLI. This will affect ASCII art, interactive job output, progress bars, and the table printer.
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 progressible downloader class