This function will execute the given command and returns the output. In scalar context it returns the raw output as is, and in list context it returns the list of output lines. The exit value of the command is stored in the $? variable.

cwd => $path
sets the working directory of the executed command to $path
only_if => $condition_command
executes the command only if $condition_command completes successfully
unless => $condition_command
executes the command unless $condition_command completes successfully
only_notified => TRUE
queues the command, to be executed upon notification (see below)
env => { var1 => $value1, ..., varN => $valueN }
sets environment variables in the environment of the command
timeout => value
sets the timeout for the command to be run
auto_die => TRUE
die if the command returns with a non-zero exit code
it can be set globally via the exec_autodie feature flag
command => $command_to_run
if set, run tries to execute the specified command and the first argument
becomes an identifier for the run block (e.g. to be triggered with notify)
creates => $file_to_create
tries to create $file_to_create upon execution
skips execution if the file already exists

Examples:

If you only want to run a command in special cases, you can queue the command and notify it when you want to run it.