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.
_____ _ ____
/ ____| | | _ \
| | ___ _ __ ___ _ __ ___ __ _ _ __ __| | |_) | _____ __
| | / _ \| '_ ` _ \| '_ ` _ \ / _` | '_ \ / _` | _ < / _ \ \/ /
| |___| (_) | | | | | | | | | | | (_| | | | | (_| | |_) | (_) > <
\_____\___/|_| |_| |_|_| |_| |_|\__,_|_| |_|\__,_|____/ \___/_/\_\ v1.2.3.00000
Welcome to CommandBox!
Type "help" for help, or "help [command]" to be more specific.
CommandBox> echo "Hello World!"
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.
boxtext is calling the CommandBox binary, and the
versionbit is passed along to the CommandBox shell to execute once it loads.
You can also activate CommandBox in debug mode by passing the
-clidebugflag 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
tailcommand to only output the few lines of the text/file. Adding the
--followflag when tailing a file will live-stream changes to the file to your console until you press Ctrl-C to stop.
forgebox search luis | tail
system-log | tail lines=50
tail myLogFile.txt --follow
Similar to the
tailcommand you can also capture the TOP x lines of a file.
# Pass file name
system-log | head
# Pass text directly
cat data.txt | head lines=5
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_PROPSin this format:
That would create a property called
fooand a property called
bradwith the values
woodrespectively. 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_ARGSin the environment that
boxwill run in.
BOX_JAVA_ARGS="-Xms1024m -Xmx2048m -Dfoo=bar"
For Windows, create a file called
box.l4j.iniin the same directory as the
box.exefile 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_PROPSas shown in the previous section, but actual JVM
-Xsettings 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
nonInteractiveShellsetting, CommandBox will automatically default it to true if there is an environment variable named
CIpresent, 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
cdcommand. 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
-cliworkingdirflag to the box binary when you start it.
# This works too
box -cliworkingdir C:/my/path/here/
# And can be coupled with a command to run
box -cliworkingdir C:/my/path/here/ install