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

Flag	Description
`--detach`, `-d`	Create session without attaching. Prints session URL to stdout

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

Show information about the current relay session. Must be run from inside a relay session (where RELAY_SESSION_ID is set).

relay info          # pretty-printed session details
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.

Flag	Description
`--json`	Output session metadata as JSON (includes binary path and mtime)

`relay stop <id>`

Kill a session and its underlying process.

Generate a read-only share link.

Flag	Description
`--ttl <seconds>`	Link expiration (default: 3600, max: 86400)
`--password <pw>`	Require password to view

Output: share URL to stdout, metadata to stderr.

`relay tui`

Interactive session picker with a split-pane terminal UI. Shows running sessions in a navigable list with a live terminal preview. Exited sessions are hidden from the list.

Key	Action
`↑`/`↓` or `j`/`k`	Navigate sessions
`Enter`	Attach to selected session
`x`	Stop selected session (confirms first)
`r`	Refresh session list
`g` / `G`	Jump to top / bottom
`q` or `Esc`	Quit

Mouse support: click to select, scroll wheel to navigate, click selected session to attach.

Server commands

`relay server start`

Start the web server in the foreground.

Flag	Description
`--tunnel`	Enable public access via relaytty.com
`--port <port>`	Override server port (default: 7680)

`relay server install`

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

`relay server uninstall`

Remove and stop the system service.

CLI Commands

On this page