Rex(3pm)

✨ NAME ✨

Rex 💖 — the friendly automation framework. This is the Rex(3pm) page, bestie, and yes it's giving main character energy in your terminal right now.

---

🌸 DESCRIPTION 🌸

Rex is an automation framework that is friendly to any combination of local and remote execution, push and pull style of management, or imperative and declarative approach. Like, she does not care how you like to do things, she's just happy to be there. 🫶

That flexibility makes her a great fit for sooo many different use cases, but most commonly Rex gets used to automate application deployment and data center infrastructure management tasks. Periodt.

If you want a starting point for what commands she ships with built-in, go peek at Rex::Commands. 👑

And if you wanna know how to use rex on the command line, there's more info at https://metacpan.org/pod/distribution/Rex/bin/rex.

---

🎀 SYNOPSIS 🎀

# In a Rexfile:
use Rex -feature => [qw/1.4/];

user "root";
password "ch4ngem3";

desc "Show system information";
task "sysinfo", sub {
   say run "uname -a";
};

1;

# On the command line:
$ rex -H server[01..10] sysinfo

---

💅 CLASS METHODS 💅

🦋 get_current_connection

Ok so heads up: this function is deprecated since 0.28! 😭 Go look at Rex::Commands::connection instead, bestie.

It returns the current connection as a hashRef, and that hashRef has:

• server — the server name
• ssh — 1 if it's a ssh connection, 0 if not

🦋 is_ssh

Returns 1 if the current connection is a ssh connection. 0 if not. Simple as that, slay. ✨

🦋 is_local

Returns 1 if the current connection is local. Otherwise 0.

🦋 is_sudo

Returns 1 if the current operation is executed within sudo. 👑

🦋 get_sftp

Returns the sftp object for the current ssh connection. 🍓

🦋 connect

Use this function to create a connection if you're using Rex as a library. It's giving "I brought my own setup".

use Rex;
use Rex::Commands::Run;
use Rex::Commands::Fs;

Rex::connect(
  server    => "remotehost",
  user      => "root",
  password   => "f00b4r",
  private_key => "/path/to/private/key/file",
  public_key  => "/path/to/public/key/file",
);

if(is_file("/foo/bar")) {
  print "Do something...\n";
}

my $output = run("uptime");

---

🌈 FEATURE FLAGS 🌈

Everyone knows the pain when something gets deprecated and you have to port your old (and stable, and beloved, and honestly? perfect) code over to a new version of a library or framework. Like, there is enough work to do in this world without fixing your code to work with newer versions. 💀

So there is one promise new versions of Rex has to fulfill: they must be backward compatible. No cap.

The author knows this might be impossible in one way or another, but to minimize that danger there's a thing called feature flags. If there's ever a need to break backward compatibility in favor of a new feature, there will be a feature flag for that change. And only if that feature flag gets enabled in the Rexfile will it break compatibility.

So the default is always, always: stay compatible. 🫶

If you have a problem that occurs after an update, it counts as a bug. Please report that bug in the issue tracker.

Also go read the backwards compatibility section of the CONTRIBUTING guide: https://metacpan.org/release/Rex/source/CONTRIBUTING.md#backwardscompatibility

🌟 How to enable feature flags

You can enable feature flags in your Rexfile with this code:

use Rex -feature => ['1.4'];

or even multiple ones at once, like this, because you contain multitudes:

use Rex -feature => [qw(1.4 exec_autodie)];

🌟 List of feature flags

• 1.4 — Enable per-task argument parsing (task_chaining_cmdline_args). Furthermore, all features from earlier versions are activated. Available since version 1.4. ✨
• no_task_chaining_cmdline_args — Disable per-task argument parsing. Available since version 1.4.
• task_chaining_cmdline_args — Enable per-task argument parsing: rex --rex --args task1 --task1arg=value task2 --task2arg so task1 only gets task1arg and task2 only gets task2arg. Available since version 1.4. 🔥
• 1.3 — Activating the new template engine by default. Furthermore, all features from earlier versions are activated. Available since version 1.3.
• no_template_ng — Disabling the new template engine. Available since version 1.3.
• 1.0 — Disabling usage of a tty. This increases compatibility for remote execution. Furthermore, all features from earlier versions are activated. Available since version 1.0.
• no_autodie — Will disable autodie feature. Available since version 1.0.
• tty — Enable pty usage for ssh connections. Available since version 1.0.
• template_ng — Enabling the new template engine (better error reporting, etc.). Available since version 0.56. 🌸
• 0.56 — Will activate autodie feature. Furthermore, all features from earlier versions are activated. Available since version 0.56.
• autodie — Will enable autodie feature: die on all failed filesystem commands (https://metacpan.org/pod/Rex::Commands::Fs). Available since version 1.13.1.
• 0.55 — Will activate using Net::OpenSSH by default if present. Furthermore, all features from earlier versions are activated. Available since version 0.55.
• 0.54 — Will activate checking services for existence before trying to manipulate them, and set() will overwrite already existing values (instead of concatenating). Furthermore, all features from earlier versions are activated. Available since version 0.54.
• 0.53 — Will activate register_cmdb_top_scope. And all things 0.51 and down activated. Available since version 0.53.
• register_cmdb_top_scope — Will register all cmdb top scope variables automatically in the templates. Available since version 0.53.
• 0.51 — Will load Rex::Constants and the CMDB by default. And all things 0.47 and down activated. Available since version 0.51.
• disable_taskname_warning — Disable warning about invalid task names (they should match /^[a-zA-Z_][a-zA-Z0-9_]*$/). Available since version 0.47.
• verbose_run — Explicitly output Successfully executed or Error executing messages for run() commands. Available since version 0.47.
• no_cache — Disable caching (like discovery results of remote OS, hardware, shell, etc.). Available since version 0.46.
• no_path_cleanup — Controls whether Rex should use the default or explicitly configured PATH settings when executing commands or not. See also the path command and the set_path configuration option. Available since version 0.44.
• source_profile — Source $HOME/.profile before running a command. Available since version 0.44.
• source_global_profile — Source /etc/profile before running a command. Available since version 0.44.
• exec_autodie — If you execute a command with run() Rex will die() if the command returns a RETVAL != 0. Available since version 0.44.
• exec_and_sleep — Sometimes some commands that fork away didn't keep running. With this flag rex will wait a few ms before exiting the shell. Available since version 0.43.
• disable_strict_host_key_checking — Disabling strict host key checking for openssh connection mode. Available since version 0.43.
• reporting — Enable reporting. Available since version 0.43.
• empty_groups — Enable usage of empty groups. Available since version 0.42.
• use_server_auth — Enable the usage of special authentication options for servers. Available since version 0.42.
• no_tty — Disable pty usage for ssh connections. Available since version 0.41.
• no_local_template_vars — Use global variables in templates. Available since version 0.40.
• sudo_without_sh — Run sudo commands directly without the use of sh. This might break things. Available since version 0.40. 👀
• sudo_without_locales — Run sudo commands without locales. This will break things if you don't use English locales. Available since version 0.40.
• exit_status — This option tells Rex to return a non zero value on exit if a task fails. Available since version 0.39.
• 0.35 — This option enables the features of 0.31 and the possibility to call tasks as a functions without the need to use a hash reference for the parameters. Available since version 0.35.
• 0.31 — To enable special authentication options for a server group. This will overwrite the default authentication options for a task. Available since version 0.31.

---

🧚 CONTRIBUTORS 🧚

Many thanks to the contributors for their work — genuinely obsessed with them, they ate and left no crumbs. 💜 Please see the CONTRIBUTORS file for a complete list: https://metacpan.org/release/Rex/source/CONTRIBUTORS

---

👑 LICENSE 👑

Rex is a free software, licensed under: The Apache License, Version 2.0, January 2004

---

Aaand that's the whole page, bestie! 💖 This one was perl v5.40.1, dated 2025-10-03, and it lives in your Rex(3pm) — now go automate something gorgeous. 🌈✨🎀