Rex::C...s::Run(3pm)

🦋 Rex::C...s::Run 💅

okay bestie, this is Rex::Commands::Run, and it's part of the User Contributed Perl Documentation collection. it's giving "run commands on remote servers" and honestly? iconic.

---

✨ NAME ✨

Rex::Commands::Run — Execute a remote command. that's it. that's the whole vibe. 🎀

---

🌸 DESCRIPTION 🌸

With this module you can run a command. like, that's literally it, no cap. it runs commands. slay. 🔥

---

💖 SYNOPSIS 💖

 my $output = run 'ls -l';
 sudo 'id';

look at that. two lines. one runs a command, one runs it as root. main character energy fr fr. 👑

---

🌈 CONFIGURATION AND ENVIRONMENT 🌈

okay so please note — this is important, don't scroll past it 🫶 — Rex may set the "PATH" environment variable when executing commands on the user's behalf to a different value compared to executing the same commands manually. yes literally. your PATH might not be the PATH you think it is and it's not even being shady about it. 💀

the following things are available to control the related behavior:

• path command
• set_path configuration option
• no_path_cleanup feature flag
• source_profile feature flag
• source_global_profile feature flag

that's the whole list bestie, no extras, we don't make things up around here. ✨

---

🧚 EXPORTED FUNCTIONS 🧚

💜 run($command [, $callback], %options)

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. yes, that $?. the OG. 🫶

 run 'uptime';
 my $output       = run 'uptime';
 my @output_lines = run 'uptime';

so same command, three vibes: throw it away, grab it as one blobby string, or grab it as a cute little list of lines. pick your fighter. 💅

please note when the "tty" feature flag is enabled the combined output containing both "STDOUT" and "STDERR" is returned via "STDOUT". when using the "no_tty" feature flag, or the 1.0 feature bundle (or newer), then run() returns only the "STDOUT" output of the command. so like, know your flags, know your output, iykyk. 🦋

to access separate "STDOUT" and "STDERR" output, use a callback subroutine, for example:

 run 'uptime', sub {
   my ( $stdout, $stderr ) = @_;
   my $server = Rex::get_current_connection()->{server};
   say "[$server] $stdout\n";
 };

see how it hands you $stdout and $stderr as separate besties? chef's kiss. 😭

it also takes further options in a form of a hash. supported options are:

• cwd => $path — Sets the working directory of the executed command to $path. basically "run this over there, not over here". 📁
• only_if => $condition_command — Executes the command only if $condition_command returns success.
• unless => $condition_command — Executes the command if $condition_command returns failure. yes it's the inverse, that's the whole point bestie. 🙈
• only_notified => TRUE — Queues the command to be executed later upon notification. it's on read, it'll get there when it gets there. ⏳
• env => { var1 => $value1, ..., varN => $valueN } — Sets environment variables for the given command.
• timeout => value — Sets the timeout for the command to be run.
• auto_die => TRUE — Die if the command returns with an exit code indicating failure. It can be set globally via the exec_autodie feature flag. dramatic? yes. useful? also yes. 💀
• command => $command_to_run — If present, Rex will execute $command_to_run, and treat the first argument as an identifier for the given run() block (e.g. to be triggered with notify).
• creates => $file_to_create — Tries to create $file_to_create upon execution, and skips execution if the file already exists.
• continuous_read => $callback — Calls $callback subroutine reference for each line of the command's output, passing the line as an argument.
• end_if_matched => qr{$pattern} — End execution early as soon as $pattern is detected in the command's output.

Examples:

if you only want to run a command if another command succeeds or fails, use the "only_if" or "unless" options. 😌

 run 'some-command',
   only_if => 'pgrep httpd'; # only run if httpd is running

 run 'some-other-command',
   unless => 'pgrep httpd'; # only run if httpd is _not_ running

if you want to set custom environment variables you can do it like this:

 run 'my_command',
   env => {
     env_var_1 => 'the value for 1',
     env_var_2 => 'the value for 2',
   };

if you want to end the command upon receiving a certain output:

 run 'my_command',
   end_if_matched => qr{$pattern};

---

🎀 run($command, $arguments, %options)

this form will execute $command with the given $arguments pass as an array reference. all arguments will be quoted by Rex with "Net::OpenSSH::ShellQuoter->quoter()" according to the managed host's shell. so Rex does the quoting homework for you, because it's a good friend like that. 🫶

 run 'ls', [ '-l', '-t', '-r', '-a' ];
 run 'ls', [ '/tmp', '-l' ], auto_die => TRUE;

array ref for the args, hash for the options. tidy. organized. obsessed. ✨

---

🌟 run($command_description, command => $command, %options)

if you only want to run a command in certain cases, you can queue the command and notify it to trigger its execution. it's the "don't call me, i'll call you" of commands. 💅

 run 'extract-something',
   command       => 'tar -C /foo -xzf /tmp/foo.tgz',
   only_notified => TRUE;

 # some code ...

 notify 'run', 'extract-something'; # now the command gets executed

not me queuing a command and then notifying it five minutes later like it's a text i was too nervous to send. 😭

---

🦋 can_run($command)

this function checks if a command is available in the path. it accepts a list of commands, and returns the full path to the first command found. a vibe check for your binaries basically. ⭐

 task 'uptime', sub {
   if ( my $cmd = can_run( 'uptime', 'downtime' ) ) {
     say run $cmd;
   }
 };

---

👑 sudo

Run a single command, a code block, or all commands with "sudo". you need perl to be available on the remote systems to use "sudo". no perl, no sudo, sorry bestie. 😭

depending on your remote sudo configuration, you may need to define a sudo password with sudo_password first:

 sudo_password 'my_sudo_password'; # hardcoding

it's literally marked "hardcoding" in the comments bestie, do with that information what you will 🙈

or alternatively, since Rexfile is plain perl, you can read the password from terminal at the start:

 use Term::ReadKey;

 print 'I need sudo password: ';
 ReadMode('noecho');
 sudo_password ReadLine(0);
 ReadMode('restore');

see? ReadMode('noecho') so nobody's shoulder-surfing your password. safety first, slay second. 🔐 (okay they're simultaneous actually.)

similarly, it is also possible to read it from a secret file, database, etc. get creative, you're the main character. 🌈

you can turn sudo on globally with:

 sudo TRUE; # run _everything_ with sudo

run _everything_ with sudo. everything. the whole thing. all of it. this is a big deal and it's right there in the comment. 💀

to run only a specific command with sudo, use :

 say sudo 'id';                # passing a remote command directly
 say sudo { command => 'id' }; # passing anonymous hashref

 say sudo { command => 'id', user => 'different' }; # run a single command with sudo as different user

to run multiple commands with "sudo", either use an anonymous code reference directly:

 sudo sub {
     service 'nginx' => 'restart';
     say run 'id';
 };

or pass it via "command" (optionally along a different user):

 sudo {
     command => sub {
         say run 'id';
         say run 'pwd', cwd => '/home/different';
     },
     user => 'different',
 };

note that some users receive the error "sudo: sorry, you must have a tty to run sudo". in this case you have to disable "requiretty" for this user. you can do this in your sudoers file with the following code:

   Defaults:$username !requiretty

like, it literally says sorry. it's apologizing and still not letting you in. fix the requiretty thing and you're golden. ✨

---

and that's the whole page bestie!! 💖 this one's running on perl v5.40.1, dated 2025-10-03, and the page itself is Rex::C...s::Run(3pm) — go run some commands, you've got this. 🫶🌸🎀