Commands

Every command accepts --state-dir <DIR>, which picks the directory holding the device’s key, allowlist and saved peers. It defaults to REX_IROH_DIR if that’s set, and otherwise to your platform’s default location. The first command you run creates the directory and a new key.

rex-iroh help <command> prints the same options shown here.

rex-iroh serve

rex-iroh serve [--rex-server <URL>] [--allowlist <FILE>]

Accepts connections from devices on the allowlist and forwards them to the local Rex server. It also handles pairing, so rex-iroh pair and the live parts of rex-iroh peers only work while it runs. It runs until it gets Ctrl-C or SIGTERM.

--rex-server <URL>

The Rex server to forward to, as a unix:// URL. Also read from REX_SERVER. Without it, serve looks for Rex on its own.

--allowlist <FILE>

The allowlist to use instead of the one in the state directory.

On startup it prints the Rex socket and allowlist it’s using, then this device’s endpoint id and, once it’s reachable, its ticket:

forwarding to /home/you/.local/state/rex/run/server.sock
allowlist   /home/you/.local/share/rex-iroh/allowlist
id     c33be3af4267c19d409e48f837c269ff429cb0fbd8ab4ae0562d9dd584707e18
ticket endpointadbtxy5pijt4dhkatzepqn6cnh7ufhfq7pmk...

If no Rex server is listening on the chosen socket, serve exits with an error instead of starting.

rex-iroh pair

rex-iroh pair [--accept]

Asks the running serve for an invite and prints it, both as a QR code and as a rexpair: URI, then asks whether to accept the device that uses it.

--accept

Accept whoever uses the invite first, without asking. This skips the word check, so only use it when you’re confident nobody else can see the invite.

rex-iroh join

rex-iroh join <INVITE> [--label <LABEL>] [--host <NAME>] [--no-host]

Uses an invite from rex-iroh pair to pair this device with the issuer, and saves the issuer’s ticket under a name so connect can reach it later. It also adds the socket connect serves the issuer on to the Rex host of that name, making the host if there isn’t one. Put quotes around the invite, since it contains & and ?.

--label <LABEL>

The name the issuer sees for this device in the pairing prompt and in peers list.

--host <NAME>

What this device calls the issuer, which also names its socket under connect and its Rex host. A name is up to 32 lowercase letters, digits, - and _, starting with a letter or digit. Without it, an issuer joined before keeps its name, and a new one goes by its short id. Joining an issuer again with a new name renames it, and moves a file from before names to its named file.

--no-host

Leave Rex’s hosts alone. join prints the rex -S unix://… form to use instead.

Before pairing starts, join refuses a name already used for a different issuer or by a file in peers/ that can’t be read, and a name whose socket path would be too long for Unix.

Joining an issuer again under a new name also takes this device’s socket off the Rex host of the old name.

If rex can’t be found or fails, the pairing still stands. join says what went wrong and prints the rex hosts add command to run yourself. It looks for rex the same way serve does. rex-iroh never has Rex start a server, so on a device where no Rex server is running, join says so and leaves the host to you.

rex-iroh forget

rex-iroh forget <ISSUER>

Forgets an issuer this device joined: deletes its ticket, takes this device’s socket off its Rex host, and deletes the socket. If the socket was the host’s only endpoint, the host is removed; other devices’ endpoints are left alone. A running connect stops serving the issuer and removes the socket itself within a couple of seconds.

ISSUER is the issuer’s exact name or its full id; the start of an id isn’t enough. If no joined issuer has that name, forget still cleans up after it: this device’s socket on the Rex host of that name, and the socket itself. That finishes off a forget that was cut short, or an issuer whose file you deleted or renamed by hand.

If rex fails, the issuer is still forgotten, and forget says how to take the socket off the host yourself. The issuer still lists this device until it’s revoked there.

rex-iroh connect

rex-iroh connect
rex-iroh connect <PEER> --socket <PATH>

Opens a local socket that leads to an issuer’s Rex server. Use it with rex -S unix://PATH, or by setting REX_SERVER to that URL. Only your user can connect to the socket.

Without arguments, connect opens sockets/<name>-<id>.sock in the state directory for every joined issuer, where <id> is this device’s short id, and prints each name and socket. It checks peers/ every two seconds, so issuers you join or forget while it runs gain or lose their socket without a restart. Forgetting an issuer, or joining it again, ends any session still open through its socket. Only one connect without arguments can run per state directory. On startup it removes sockets an earlier one left behind for issuers you’ve since forgotten.

If an issuer turns this device away, connect logs it once and goes on serving the other issuers. The issuer’s socket stays open, and each new client on it tries the issuer again, closing as soon as it’s refused. Once the issuer lets this device back in, its socket works again and connect logs that too.

With PEER and --socket, it serves just that one peer:

<PEER>

A joined issuer’s name, its id, or the start of its id if that matches only one issuer; or any ticket, as printed by serve. A bare endpoint id of an issuer you haven’t joined also works, but then iroh has to look up the issuer’s address, which can be slower or fail where a ticket wouldn’t.

--socket <PATH>

Where to create the local socket. The path has to be short enough for a Unix socket: 107 bytes on Linux, 103 on macOS. If a socket is left over at that path from a process that has exited, it’s replaced; if something is still listening on it, connect refuses to start.

In this form, if the issuer turns this device away, connect exits with status 1.

Either way, connect only dials an issuer when a client uses its socket. If the connection drops for any reason but the issuer turning this device away, it redials the next time something uses the socket.

rex-iroh peers list

rex-iroh peers list

Lists the devices on the allowlist, with their labels and pairing dates. If serve is running, it also shows each device’s open connections.

rex-iroh peers joined

rex-iroh peers joined

Lists the issuers this device has joined, which are the ones it can reach, with the socket connect serves each on:

HOST        ID          SOCKET
desktop     c33be3af42  /home/you/.local/share/rex-iroh/sockets/desktop-695cc6e6d2.sock

rex-iroh peers revoke

rex-iroh peers revoke <PEER>

Removes a device from the allowlist. PEER is the device’s exact label, its full endpoint id, or the start of its id if that matches only one device. If serve is running, the device’s open connections close right away.

rex-iroh id

rex-iroh id

Prints this device’s endpoint id: 64 hex characters that identify the device to others. It’s derived from the device’s key, so it stays the same until that key is deleted.