There are two ways to run commands via CommandBox: inside the CommandBox interactive shell, or one-at-a-time commands from your native shell.
If you open the interactive shell, you will see the CommandBox splash screen (ASCII art) and then you'll be presented with the
CommandBox> prompt. You can enter as many commands as you wish in order and after each command is finished executing, you will be returned to the CommandBox prompt. If you have multiple commands you want to execute manually, this is the fastest method since CommandBox only loads once. This is also the only way to make use of features like tab complete and command history.
C:\>box.exe_____ _ ____/ ____| | | _ \| | ___ _ __ ___ _ __ ___ __ _ _ __ __| | |_) | _____ __| | / _ \| '_ ` _ \| '_ ` _ \ / _` | '_ \ / _` | _ < / _ \ \/ /| |___| (_) | | | | | | | | | | | (_| | | | | (_| | |_) | (_) > <\_____\___/|_| |_| |_|_| |_| |_|\__,_|_| |_|\__,_|____/ \___/_/\_\ v1.2.3.00000Welcome to CommandBox!Type "help" for help, or "help [command]" to be more specific.CommandBox> versionCommandBox 1.2.3.00000CommandBox> pwdC:\CommandBox> echo "Hello World!"Hello World!CommandBox> exitC:\>
You can also spin up CommandBox from your native shell to execute a single command inline. You can do this if you only have one command to run, or you want to automate a command from a Unix shell script or Windows batch file. This mode will not show the ASCII splash screen, but keep in mind it still loads CommandBox up and unloads it in the background. Any output from the command will be left on your screen, and you will be returned to your native OS prompt.
Here is an example of running the version command from a Windows DOS screen. Note, you'll need to either do this from the directory that holds the box executable, or add the executable to your default command path so it is found.
C:\>box versionCommandBox 1.2.3.00000C:\>
box text is calling the CommandBox binary, and the
version bit is passed along to the CommandBox shell to execute once it loads.
You can also activate CommandBox in debug mode by passing the
-clidebug flag in the command line. This will give you much more verbose information about the running CommandBox environment. This only one-off commands
Output from commands will be ANSI-formatted text which, by default, streams directly to the console. When in the interactive shell, you can capture the output of commands and manipulate it, search it, or write it to a file. Use a pipe (
|) to pass the output of one command into another command as its first input. Output can be piped between more than one command. Use a right bracket (
>) and double right bracket (
>>) to redirect output to the file system.
cat myLogFile.txt | grep "variable .* undefined"
Pipe output into the more command to output it line-by-line or page-by-page. Press the spacebar to advance one line at a time. Press the Enter key to advance one page at a time. Press ESC or “q” to abort output.
forgebox show | more
Redirect output into a file, overwriting if it exits like so:
dir > fileList.txt
Use the double arrows to append to an existing file.
echo "Step 3 complete" >> log.txt
You can pipe a large amount of text or a file name into the
tail command to only output the few lines of the text/file. Adding the
--follow flag when tailing a file will live-stream changes to the file to your console until you press Ctrl-C to stop.
forgebox search luis | tailsystem-log | tail lines=50tail myLogFile.txt --follow
If you want to add ad-hoc Java Properties to the actual CLI process, you can set an environment variable in your OS called
BOX_JAVA_PROPS in this format:
That would create a property called
foo and a property called
brad with the values
wood respectively. This environment variable works the same on all operating systems.
Similar to above, you may want to add ad-hoc JVM args to the java process that powers the CLI. The steps differ per operating system. For *nix (Linux, Mac), set an environment variable called
BOX_JAVA_ARGS in the environment that
box will run in.
BOX_JAVA_ARGS="-Xms1024m -Xmx2048m -Dfoo=bar"box
For Windows, create a file called
box.l4j.ini in the same directory as the
box.exe file and place a JVM arg on each line. Escape any backslashes with an additional backslash like a properties file format.
Both of those examples would set the min/max heap size of the CLI process and also set a Java System Property called "foo" equal to "bar". There is no effective difference between setting system properties this way as opposed to using
BOX_JAVA_PROPS as shown in the previous section, but actual JVM
-X settings must be set as described in this section.
If you are using CommandBox in a continuous integration server such as Jenkins or Travis-CI, you may find that features like the progress bar which redraw the screen many times create hundreds of lines of output in the console log for your builds. You can enable a non interactive mode that will bypass the output from interactive jobs and the download progress bar.
config set nonInteractiveShell=true
If there is no
nonInteractiveShell setting, CommandBox will automatically default it to true if there is an environment variable named
CI present, which is standard for many build servers such as Travis-CI.
CommandBox will start its current working directory in the same folder that you started the box process from. Once you are in the interactive shell, you can always change the current working directory with the
cd command. If you want to change the default working directory or just want to run a one-off command in another folder, you can use the
-cliworkingdir flag to the box binary when you start it.
box -cliworkingdir=C:/my/path/here/# This works toobox -cliworkingdir C:/my/path/here/# And can be coupled with a command to runbox -cliworkingdir C:/my/path/here/ install