CLI Commands

All commands follow the pattern relay [options] <command>. URLs are printed to stdout, status messages to stderr (POSIX convention).

Session commands

relay <command>

Create a session and attach locally.

relay bash                    # interactive shell
relay htop                    # run any command
relay -- python3 -m http.server  # use -- for commands with flags

Running relay with no command in a terminal opens the TUI (see relay tui).

relay attach <id>

Reattach to an existing session in raw TTY mode.

• Press Ctrl+] to detach
• Session continues running after detach

relay list

List all active sessions with their IDs, commands, and status.

relay info [id]

Show information about a session. Without an id it describes the current relay session (where RELAY_SESSION_ID is set).

relay info            # pretty-printed details for the current session
relay info a1b2c3d4   # any session by id
relay info --json     # machine-readable JSON output

Displays: session ID, command, CWD, status, PID, terminal size, title, throughput, timestamps, and the pty-host binary path with its build date.

If run outside a relay session, prints "Not a relay session" to stderr.

relay stop <id>

Kill a session and its underlying process.

relay send <id> [text...]

Write text to a session's stdin. With no text, stdin is read until EOF. Data goes straight to the pty, so quote shell metacharacters.

relay send a1b2c3d4 --enter "make test"     # type a command and press Enter
echo "y" | relay send a1b2c3d4              # answer a prompt from a pipe

relay rename <id> <title...>

Set a session title. A title set this way is pinned: programs that update the terminal title (shells, editors, agents) no longer overwrite it until you --unpin.

relay kill <id>

Deliver a signal to the session's foreground process group. Defaults to INT, which interrupts the running command and returns you to the shell prompt. The session itself keeps running; use relay stop to end it.

relay wait <id> --state <state>

Block until the session reaches an agent state or exits. States: blocked, working, done, idle, unknown, exited. Exit code 0 when the state is reached, 2 on timeout, 1 when the session does not exist.

relay wait a1b2c3d4 --state blocked --timeout 600   # wake me when the agent needs input
relay wait a1b2c3d4 --state exited && echo finished

relay events

Stream session events as JSON lines: session.created, session.exited, session.removed, session.agent_state, session.title, session.cwd, session.foreground. Each line carries the full session object. Pass --all to also get session.updated for metric-only changes.

relay events | jq -r 'select(.event=="session.agent_state") | "\(.session.id) \(.session.agentState)"'

relay share <id>

Generate a read-only share link.

Output: share URL to stdout, metadata to stderr.

relay tui

The terminal client. relay with no arguments opens it too. It has two modes:

Picker. Running sessions in a list with a live preview of the selected one. Sessions whose agent is waiting on you (BLOCKED) sort first, then WORKING, then the rest by age. The list updates as sessions come and go; no manual refresh needed.

Attached. Pressing Enter attaches to a session in raw mode, exactly like relay attach, except that a prefix key (default Ctrl+B, configurable in relayrc) switches sessions, creates shells, renames, and returns to the picker without leaving the terminal. Think of it as the tmux workflow on top of relay sessions: detach, reattach from any machine or browser, switch between sessions with Ctrl+B n. The outer terminal's title follows the active session and its agent state.

See Keyboard Shortcuts for the full key list. Mouse: click to select, click the selected row to attach, wheel to move; while attached, mouse events go to the program.

Server commands

relay server start

Start the web server in the foreground.

relay server install

Install as a system service (launchd on macOS, systemd on Linux).

relay server uninstall

Remove and stop the system service.