REX(1p)

🌸 REX(1p) — ok bestie, let's talk about rex 🌸

User Contributed Perl Documentation energy, but make it a group chat. This is the manual page for rex, the lil command-line icon that runs the tasks you wrote in your Rexfile. Sit down, hydrate, we're doing infra. 💖

---

✨ NAME ✨

rex — execute tasks defined in a Rexfile. That's it, that's the whole vibe. 🎀

---

💅 DESCRIPTION 💅

So the rex script is literally your command-line bestie: it lets you execute tasks that you defined in a Rexfile, straight from the terminal. No GUI, no drama, just tasks. Slay. ✨

---

🦋 SYNOPSIS 🦋

rex -h                      # Show usage
rex -T                      # List tasks
rex uname                   # Run the 'uname' task
rex -H server[01..10] uname # Run the 'uname' task on all the specified hosts
rex -G production uname     # Run 'uname' on hosts on the 'production' hostgroup
rex deploy --gracefully     # Pass '--gracefully' to the 'deploy' task

Look at her. Six whole lines and she can do all of that. 💜

---

🌈 USAGE 🌈

rex [<options>] [-H <host>] [-G <group>] <task> [<task-options>]
rex -T[m|y|v] [<string>]

---

🫶 the options, one by one, no skipping (iykyk)

🔥 the "who am I running this on" options

• -b — Run batch.
• -e — Run the given code fragment.
• -E — Execute a task on the given environment.
• -G, -g — Execute a task on the given server groups.
• -H — Execute a task on the given hosts (space delimited).
• -z — Execute a task on hosts from this command's output.

🔑 the ssh options

• -K — Public key file for the ssh connection.
• -P — Private key file for the ssh connection.
• -p — Password for the ssh connection.
• -u — Username for the ssh connection.

🗣️ the "how much do you wanna hear from me" options

• -d — Show debug output.
• -ddd — Show more debug output (includes profiling output).
• -m — Monochrome output: no colors. (💀 a sad day but okay)
• -o — Output format.
• -q — Quiet mode: no log output.
• -qw — Quiet mode: only output warnings and errors.
• -Q — Really quiet: output nothing. not a single peep.

📋 the task-listing options

• -T — List tasks.
• -Ta — List all tasks, including hidden. (the hidden ones?? 👀)
• -Tm — List tasks in machine-readable format.
• -Tv — List tasks verbosely.
• -Ty — List tasks in YAML format.

⚙️ the rest of the lineup (all iconic, all required)

• -c — Turn cache ON.
• -C — Turn cache OFF.
• -f — Use this file instead of Rexfile.
• -F — Force: disregard lock file.
• -h — Display this help message.
• -M — Load this module instead of Rexfile.
• -O — Pass additional options, like CMDB path.
• -s — Use sudo for every command.
• -S — Password for sudo.
• -t — Number of threads to use (aka 'parallelism' param).
• -v — Display (R)?ex version.

---

🎀 Rexfile 🎀

When you run rex, it reads the file Rexfile in the current working directory. A Rexfile is made of 2 major parts: configuration and task definitions. Two parts. That's the whole structure. Periodt. 💅

---

🌸 Configuration 🌸

See all the available commands in Rex::Commands.

🔐 Simple authentication

user 'bruce';
password 'batman';
pass_auth;

🗝️ Key authentication

private_key '/path/to/your/private/key.file';
public_key '/path/to/your/public/key.file';
key_auth;

📝 Define logging

logging to_file   => 'rex.log';
logging to_syslog => 'local0';

👯 Group your servers

Rex gives you the ability to define groups of servers. Groups can be defined the Rexfile:

group 'frontends' => 'frontend01', 'frontend02', 'frontend[03..09]';

Groups can also be defined in separate files, like server.ini:

# server.ini
[frontends]
frontend[01..04]

# Rexfile
use Rex::Group::Lookup::INI;
groups_file 'file.ini'

See Rex::Group::Lookup::INI for more details, and check the Rex::Group::Lookup namespace for other formats. there are options, bestie, explore.

---

⏱️ Other configuration ⏱️

timeout 10;    # ssh timeout
parallelism 2; # execute tasks in parallel

---

🧚 Defining tasks 🧚

A basic task looks like this:

# task description
desc 'This task tells you how long since the server was rebooted';

# task definition
task 'shortname', sub {
  say run 'uptime';
};

By default it will be targeted at the same host where rex is being executed. Yes, she stays local until you tell her otherwise.

You can also set a default server as the task's target:

desc 'This is a long description of a task';
task 'shortname',
  'frontend01',
  sub {
    say run 'uptime';
  };

or even a default server group:

desc 'This is a long description of a task';
task 'shortname',
  group => 'frontends',
  sub {
    say run 'uptime';
  };

The task options from the command line will be passed to the task as well:

# Rexfile
desc 'Get task options';
task 'get_task_options', sub {
  my $task_options = shift;
  my $option1 = $task_options->{option1};
};

# command line
rex get_task_options --option1=yes

The way that the command line just hands your task its options?? Obsessed. 😭💖

---

🦄 TAB COMPLETION 🦄

Tab completion scripts are provided for Bash and Zsh in the share directory at <https://metacpan.org/release/Rex/source/share>. They provide completions for the available CLI options, hosts, groups, environments and tasks.

ngl, tab completion is the main character here. You press <TAB> and she just knows your hosts, your groups, your environments and your tasks. ate. 👑

---

okay that's the whole page, you made it, I'm so proud of you 🫶✨

This was brought to you by perl v5.40.1, dated 2025-10-03 — that's the version and the date, bestie, write them down, they're part of the lore. 💖🎀🦋