If you want to execute a native binary from inside the interactive shell or as part of a CommandBox recipe, we allow this via the
run command. You can read the API docs for
Hint This behavior is dependent on your operating system.
Execute an operation system level command using the native shell. For Windows users,
cmd.exe is used. For Unix,
/bin/bash is used. Command will wait for the OS command to finish.
The binary must be in the PATH, or you can specify the full path to it. Your keyboard will pass through to the standard input stream of the process if it blocks for input and the standard output and error streams of the process will be bound to your terminal so you see output as soon as it is flushed by the process.
run myApp.exerun /path/to/myApp
A shortcut for running OS binaries is to prefix the binary with
!. In this mode, any other params need to be positional. There is no CommandBox parsing applied to the command's arguments. They are passed straight to the native shell. As such, you don't need to escape any of the parameters for CommandBox when using this syntax.
!myApp.exe!/path/to/myApp!dir!netstat -pan!npm ll!ipconfig!ping google.com -c 4!java -jar myLib.jar
OS Commands you run are executed in the same working directory as CommandBox. This means you can seamlessly invoke other CLIs without ever leaving the interactive shell.
!git inittouch index.cfm!git add .!git commit -m "Initial Commit"
The output of native calls can be used in expressions or piped into other commands. Here's a Unix example that uses CFML functions from the command line to parse the parent folder from the current working directory:
#listlast `!pwd` /
When passing a command string for native execution, ALL REMAINING TEXT in the line will be "eaten" by the native execution and passed to the OS for processing. This is so the CommandBox parser doesn't "'screw up" any special syntax that your OS command processor is expecting. That means any use of piping or
&& will get passed straight to the OS. On Windows, the following string will run the
ver command twice in Windows.
!ver && ver
In the event you want to pipe the result of an OS binary to another CommandBox command or chain another CommandBox command on the end, you can workaround this by echoing out the string and then piping that to the
run command. This example will run the Windows
ver command followed by the CommandBox
echo "ver" | run && ver
Additionally, any expansions you put in your command string with backticks or System Setting placeholders will not be processed by CommandBox, but will be passed to the native OS directly. This Windows example won't do what you might think since the backticks are passed, untouched to the OS (so the OS can expand them if it needs):
!git status | find "`package show name`"
Instead, you can pass the command text through
echo to have CommandBox process the backtick expansions first before sending it off to the OS for processing.
echo 'git status | find "`package show name`"' | run
In the above example, written for Windows, the output of the
echo command has the
package show name expression expanded into the string and then the ENTIRE string is piped to
run where the pipe and the
find command are processed by Windows. Note, there is no need for preceding the command with
! when passing to
! is just an alias for
When you prepare the native binary ahead of time and then pipe it into the
run command, you are allowed to pipe the result back into another CommandBox command in that specific case. This is only possible when
run appears with nothing after it.
echo 'git status | find "`package show name`"' | run | #ucase
You can pipe the output of a previous command in CommandBox directly to a native binary like so:
#createguid | !clipor#createguid | run clip
In this case,
clip is a Windows binary that will read the standard input and place that text on the clipboard. When the
run command receives two inputs, it will assume the first input is the piped input and the second input is the actual command to run.
You can even pipe commands to an interpreter that normally reads from a keyboard on the standard input, but be aware that some binaries such as Windows
cmd require line breaks after the input or it won't process. In the specific case of Windows
cmd it seems to require at least two line breaks for some reason (this is also true outside of CommandBox)
echo "ping google.com`#chr 10``#chr 10`" | !cmd
In the previous example we use a backtick expansion to grab a line feed from the CFML
There are limitations. When you pipe into the
run command, the command will not also be able to read from your keyboard (this is true of any shell) and it will execute in a non-interactive manner, which means the ping's output above would appear all at once as opposed to flowing in one line at a time.
When piping into the
run command you cannot also pipe the output of the run command like so:
#createguid | !clip | #ucase
As soon as any text appears after
!, then the rest of the line is "eaten" and passed to the native shell.
Also you cannot build up a command like so and also pipe input into the native binary at the same time:
echo "clip" | run
This is because only one parameter can be piped into a command at a time.
If you're having issues getting a native binary to run, you can turn on a config setting that will echo out the exact native command being run including the call to your OS's command interpreter.
config set debugNativeExecution=true
You can override the default native shell from
/bin/bash to any shell of your choosing, like zsh. This will let you use shell specific aliases. You can set your native shell property using the
config set command (i.e.,
config set nativeShell=/bin/zsh)
If the native binary errors, the exit code returned will become the exit code of the
run command itself and will be available via the usual mechanisms such as
Any environment variables you set in the CommandBox shell will be available to the native process that your OS binary runs in. Here's a Windows and *nix example of setting an env var in CommandBox and then using it from the native shell.
set name=brad!echo %name%
set name=brad!echo $name