Many commands accept parameters to control how they function. Parameters are entered on the same line as the command and separated by a space and can be provided as named OR positional, similar to how CFML functions can be called. You cannot mix named and positional parameters in the same command though or an error will be thrown. There is also a concept of "flag" for boolean parameters that can be combined with named or positional parameters for brevity and readability.

Named Parameters

Named parameters can be specified in any order and follow the format name=value. Multiple named parameters are separated by a space.

coldbox create app name=myApp skeleton=AdvancedScript directory=myDir init=true

Positional Parameters

Positional parameters omit the name= part and only use the value. They must be supplied in the order shown in the Command API docs or help command. We try to place the most common parameters at the beginning so you can use named parameters easily. Here is the equivalent of the named command above:

coldbox create app myApp AdvancedScript myDir true

Of course, only the required parameters must be specified. I'm only including all of them here for the completeness of the example.

Required Parameters

If you do not provide a parameter that is required for the command execution, the shell will stop and ask you for each of the missing parameters before the command will execute.

CommandBox> mkdir
Enter directory (The directory to create) : myDir
Created C:\myDir
CommandBox>

Info It is not necessary to escape special characters in parameter values that are collected in this manner since the shell doesn't need to parse them. The exact value you enter is used.

Flags

Any parameter that is a boolean type can be specified as a flag in the format --name. Flags can be mixed with named or positional parameters and can appear anywhere in the list. Putting the flag in the parameter list sets that parameter to true. This can be very handy if you want to use positional parameters on a command with a large amount of optional parameters, but you don't want to specify all the in-between ones.

coldbox create app myApp --init --installColdBox

You can also negate a flag by putting an exclamation point or the word "no" before the name in the format --no{paramName}. This sets the parameter to false which can be handy to turn off features that default to true.

coldbox create app myApp --noInit

If a value is a single word with no special characters, you don't need to escape anything. Certain characters are reserved as special characters though for parameters since they demarcate the beginning and end of the actual parameter and you'll need to escape them properly. These rules apply the same to named and positional parameters.

Spaces

If a parameter has any white space in it, you'll need to wrap the value in single or double quotes. It doesn't matter which kind you use and it can vary from one parameter to another as long as they match properly.

echo 'Hello World'
echo "Good Morning Vietnam"

Quotes

Quotes are actually allowed unescaped in a value like so:

echo O'reilly

However, if the parameter contains whitespace and is surrounded by quotes, you'll need to escape them with a backslash.

echo 'O\'reilly Auto Parts'
echo "Luis \"The Dev\" Majano"

Hint Only like quotes need to be escaped. Single quotes can exist inside of double and vice versa without issue. These examples below are perfectly valid.

echo "O'reilly Auto Parts"
echo 'Luis "The Dev" Majano'

Backticks

Backticks are used in parameter values to demarcate an expression to be parsed. Escape them with a backslash. All backticks need escaped regardless of whether they are encased on single or double quotes.

echo "Nothing to \`see\` here"

Equals Signs

If you have an equals sign in your value, you'll need to escape it with a backslash unless you've quoted the entire string.

echo 2+2\=4
echo "2+2=4"

Line Breaks

Line breaks can't be escaped directly as of Commandbox 4.0. Instead, most terminals let you enter a carriage return by pressing Ctrl-V and pressing enter. To enter a line feed, press Ctrl-V followed by Ctrl-J.

On ConEMU, which performs a paste operation with Ctrl-V, use Ctrl-Shift-V instead.

Tabs

A tab character can't be escaped directly as of CommandBox 4.0. Instead, most terminals let you enter a tab char by pressing Ctrl-V followed by tab. In ConEMU which allows pasting via Ctrl-V, you can use Ctrl-Shift-V and then press tab.

Backslash

Since the backslash is used as our escape character you'll need to escape any legitimate backslash that happens to precede a single quote, double quote, equals sign, or letter n.

echo foo\\\=bar

This will print foo\=bar

Many Commands accept a path to a folder or file on your hard drive. You can specify a fully qualified path that starts at your drive root, or a relative path that starts in your current working directory. To find your current working directory, use the pwd command (Print Working Directory). To change your current working directory, use the cd command.

Absolute

Here are examples of fully qualified paths in Windows and *nix-based:

Windows:

mkdir C:/sites/test
mkdir /sites/test
mkdir \\server/share/test

Info Note that if you start a path with a single leading slash in Windows, it will be an absolute path using the drive letter of the current working directory.

*nix:

mkdir /opt/var/sites/test

Relative

For a relative path, do not begin with a slash.

mkdir test

File system paths will be canonicalized automatically which means the following is also valid:

mkdir ../../sites/test

UNC Server paths

If you are on Windows, CommandBox supports UNC server shares bu accessing the name of the server or the IP address. Note, you can use forward or backslashes in Windows, but a UNC path MUST start with two backslashes.

\\server/share/sites/test
\\10.10.1.205/webroot/logs

Backslashes need to be escaped from the command line and in JSON, so most usage of UNC server paths will require you to type four slashes like \\\\ which will properly escape to \\

cd \\\\server/share/sites/test
mkdir \\\\10.10.1.205/webroot/logs

You cannot directly list the contents of a server like \\webdev01 as that is not a true directory. You always need to access a specific share like \\webdev01/webroot.

Permissions

By default, CommandBox will access UNC paths using the same permissions of the user that the box process was started with. There's no way to specify a user, so if you need to use a custom user, you'll need to run native NET USE command from the CLI first to change how it is authenticating. Unfortunately, this is a limitation of how Java accesses UNC paths so CommandBox has little control over it.

Parameter values passed into a CommandBox command don't have to be static. Any part of the parameter which is enclosed in backticks (`) will be evaluated as a CommandBox expression. That means that the enclosed text will be first executed as though it were a separate command and the output will be substituted in its place.

Any valid command can be used as an expression, including calls to native OS binaries, CFML functions, or REPL one-liners. Note that any text that a command immediately flushes to the console during its execution (like a download progress bar) will not be returned by the expression, though it will display on the console.

Entire Parameter

Take for instance, this simple command that prints out the contents of a file:

It can be used as a dynamic parameter like so:

In the example above, the contents of the defaultServer.txt file will be passed in as the value of the "name" parameter to the "server start" command. If the contents of the file was the text myServer, the equivalent final command would be:

Inside Parameters

There can be more than one expression in a single parameter value. Expressions can also be combined with static text and they will all be evaluated in the order they appear:

That would output something similar to:

If you need to use an actual backtick in a parameter value, escape it with a backslash.

Which outputs

Express Yourself

This unlocks a new world of scripting potential when combined with other abilities like native OS binary execution and CFML functions from the CLI. Here's some examples to get your gears turning:

Set a package property in box.json equal to the current date passed through a CFML date mask

Set properties based on manipulations of previous values:

Perform CFML operations on local files:

Execute environment-aware install scripts based on local files. (isProduction.txt would contain the text true or false in this ex.)

The CommandBox interactive shell already allows for a command to pipe data into another Command.

cat myfile.txt | grep "find me"

Since CommandBox commands don't have a "standard input", the output of the previous command is passed into the second command as its first parameter. In this instance, the grep command's first parameter is called input so it receives the value returned by the cat command. The "find me" text becomes the second parameter-- in this case, expression.

Examples

There is nothing special about a parameter that can received piped input. In fact, any command can receive piped input for its first parameter. The following commands all accomplish the same thing.

coldbox create app "My App"

echo "My App" | coldbox create app

echo "My App" > appName.txt
cat appName.txt | coldbox create app

This allows you to get creative by combining commands together like so:

package set name="hello world"
package show name | sed s/hello/goodbye/

This takes a package name and replaces some text on output. One benefit is that Windows users don't have a native sed command in their OS, but those commands inside a CommandBox Recipe will execute consistently on any machine.

Piping From The OS

What if you aren't using the interactive shell and you want to pipe into CommandBox from your OS's native shell? This is also supported, and as long as there is a command specified, the piped input will become the first parameter as before.

C:\> echo coldbox | box install
C:\> echo reverse('this is a test') | box repl

If you pipe text directly into the box executable with no command specified in the parameters, each line of your piped text will be read from the standard input as a command.

C:\> echo version | box
C:\> box < commands.txt

When a command has an argument with a type of Globber for a file path, that means you can use file globbing patterns to affect more than one file at a time. Globbing patterns are common in Bash as well as places like your .gitignore file. They use common wildcard patterns to provide a partial path that can match zero or hundreds of files all at the same time.

"?" matches a single character

If a globbing pattern contains a question mark, that will match any single character. So a pattern of ca?.txt would match car.txt, and cat.txt, but not cart.txt. You can use a wildcard more than once. p?p?.cf? would match files named papa.cfm and pipe.cfc.

"*" matches any number of characters within name

If a globbing pattern contains a single asterisks, that will match zero or more characters inside a filename or folder name. So d*o matches doodoo, dao, and just do. The wildcard only counts inside a file or folder name, so models/*.cfc will only match cfc files in the root of the models folder.

"**" matches any number of characters across all directories

To extend the previous example, if we did models/**.cfc that would match any cfc file in any subdirectory, no matter how deep.

Globbing examples

Here's some examples of what file globbing might look like:

CommandBox> rm temp*.txt
CommandBox> cp *.cfm backup/
CommandBox> touch build/*.properties

Here's some more examples of how the wildcards work

// Match any file or folder starting with "foo"
foo*

// Match any file or folder starting with "foo" and ending with .txt
foo*.txt

// Match any file or folder ending with "foo"
*foo 

// Match a/b/z but not a/b/c/z
a/*/z

// Match a/z and a/b/z and a/b/c/z
a/**/z

// Matches hat but not ham or h/t
/h?t

Since the Globber library can handle more than one globbing pattern, any command that uses a Globber type can accept a comma-delimited list of patterns. The following will list any .cfm AND .md files in the directory.

dir *.cfm,*.md