The CLI

rex is the command-line interface to Rex.

rex is both an administrative tool for Rex as well as a foundation for automation. As an administrative tool, it can create sessions, split panes, list active clients, force disconnect a client, etc. As an automation tool, it has a complete, powerful Lua scripting interface.

Every terminal you open in Rex has rex on its PATH automatically, and the context is setup so that the CLI already knows what session you’re in, block you’re looking at, etc.

Open a terminal and try it:

rex ls                 # list your sessions
rex session inspect    # show details of the session you are in
rex block inspect      # show details of the terminal you are typing in

Run rex help for every command, or rex help <command> for the details of one.

Taxonomy

Rex organizes work into four kinds of things. Every command acts on one or more of them.

• A session is a group of related work, such as one project. The server keeps a session running whether or not anything is looking at it.
• A window is a tab within a session. It holds a layout of blocks.
• A block is one application in a window. Today that means a terminal.
• A client is a program connected to the server, such as the app. Clients matter when you ask the app itself to do something, like open its command palette.

Each one has an ID that never changes and is never reused, such as block:01a10d99-0c06-7795-bf67-798ce4c36a33. Sessions, windows, blocks, and clients can also have a label, which is a name you choose and can change.

Command Targets

With no options, a CLI command acts based on its context. Inside a Rex terminal that is the terminal’s own block and session, so rex split splits the terminal you typed it in. Rex knows where you are from three environment variables it sets in every terminal:

To act somewhere else, specify it with a flag:

rex send -s build -w 2 'make test'   # type into window 2 of the "build" session
rex capture -b logs                  # print the screen of the block labeled "logs"
rex -S studio ls                     # list the sessions on the host labeled "studio"

Targets

Rex tries to match a session, window, block, or client target (such as -C) in this order and stops at the first kind of match it finds:

1. A full ID, such as session:01a10cf3-2655-7e48-9b9c-43dd6612bef5.
2. A case-insensitive label, such as build.
3. A position, counting from one. Windows are numbered in tab order, so -w 2 is the second tab.
4. The end of an ID, at least four characters long, such as 12bef5. Listing commands print these short IDs.

If a target matches more than one thing, the command stops without changing anything, lists what matched, and exits with status 3:

Error: session target "work" is ambiguous
  first   …001234
  second  …00abcd

A server is the exception. -S takes only a host label or an address, and a value with a port is always an address.

Labels are convenient at a prompt, but they can change and two things can share one. In a script that has to keep working, save the ID a command returns and use that.

Machine-Readable Output

Most commands print a table meant for reading. Pass --json to get JSON instead, which is stable to parse and includes full IDs:

$ rex ls --json
{
  "sessions": [
    {
      "session_id": "session:01a10cf3-2655-7e48-9b9c-43dd6612bef5",
      "label": "Research"
    },
    {
      "session_id": "session:01a10d97-414b-79ee-9988-4d96d804ef90",
      "label": "SL Website"
    }
  ]
}

The exit status says how a command ended:

Commands that wait for a program, such as rex wait and rex run --wait, exit with that program’s status instead.