---
name: "rex"
section: "1p"
platform: "linux"
package: "rex"
version: "1.16.0-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/rex/1p"
---

# rex(1p)

execute tasks defined in a Rexfile

## NAME

rex - execute tasks defined in a Rexfile

## DESCRIPTION

The `"rex"` script can be used to execute tasks defined in a Rexfile from the command line.

## 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
```

## USAGE

```
 rex [<options>] [-H <host>] [-G <group>] <task> [<task-options>]
 rex -T[m|y|v] [<string>]
 -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
 -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
 -d     Show debug output
 -ddd   Show more debug output (includes profiling output)
 -m     Monochrome output: no colors
 -o     Output format
 -q     Quiet mode: no log output
 -qw    Quiet mode: only output warnings and errors
 -Q     Really quiet: output nothing
 -T     List tasks
 -Ta    List all tasks, including hidden
 -Tm    List tasks in machine-readable format
 -Tv    List tasks verbosely
 -Ty    List tasks in YAML format
 -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 consists of 2 major parts: configuration and task definitions.

### 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.

### 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.

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
```

## TAB COMPLETION

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