Relay CLI

Relay runs a local web development server through a short-lived LAN gateway so it can be opened and controlled from the Relay Android app.

Requirements

• Node.js 24 or newer
• A development server reachable on 127.0.0.1
• The development machine and Android device on the same LAN for Relay Local

The published executable uses #!/usr/bin/env node. Package runners such as bunx therefore launch the supported Node runtime unless explicitly forced to use Bun.

Run

Install globally:

npm install --global @paddy-systems/relay-cli
relay 3000

Run without a global installation:

npx --package @paddy-systems/relay-cli relay 3000

Bun can be used as the package runner while retaining the Node runtime:

bunx --package @paddy-systems/relay-cli relay 3000

Deno can run the npm package without a global install. Relay needs these exact permissions for filesystem access, environment variables, network access, and LAN interface discovery:

deno x --quiet --no-prompt --allow-read --allow-write=./relay-artifacts --allow-env --allow-net --allow-sys=networkInterfaces -p "npm:@paddy-systems/[email protected]" relay 3000

--allow-sys=networkInterfaces is required because Relay reads LAN/network interface information for local device discovery and gateway behaviour.

Replace 3000 with the port used by the local development server.

Running relay without arguments shows the command help:

relay
relay --help
relay --version

Invalid ports, unknown options, unexpected arguments, and unreachable HTTP development servers produce actionable errors before Relay opens the gateway.

Runtime support

Release smoke tests install the packed CLI into a clean project and execute it on Linux, macOS, and Windows with Node.js 24. Native execution under the Bun runtime (bunx --bun) is not part of the supported CLI runtime contract.

Relay Local remains anonymous and does not require a Paddy Systems account.

Relay Connect

Relay Connect uses the local network by default. It can also forward a TCP development service between machines through the authenticated Relay cloud when --cloud is explicitly requested.

Create and host a session from the machine running the development service:

relay share 3000

The terminal displays an L-XXXX-XXXX access code. On the second machine, use that code to open a local port:

relay connect <access-code> --port 3000

The sharing CLI registers the LAN endpoint with the Relay API, but application traffic still travels directly between the two machines. If the receiving machine cannot reach the API, use the host and remote port printed by the sharing CLI:

relay connect <access-code> --host 192.168.1.42 --remote-port 39732 --port 3000

For a connection between machines that are not on the same LAN, opt into the cloud transport. The sharing machine will open a browser authorization flow:

relay share 3000 --cloud

That produces an R-XXXX-XXXX code. relay connect needs no transport flag; the L- or R- prefix selects the correct path automatically. LAN sharing does not require an account. Cloud codes authorize only the requested session, expire automatically, and default to one hour; use --expires between 60 and 86400 seconds to change that lifetime.

Terminal behaviour

Relay uses a small presentation layer that adapts to the current terminal.

• Interactive TTY output uses a compact Relay-themed status layout with muted defaults and restrained blue/purple/pink accent colours when supported.
• Redirected, piped, CI or TERM=dumb output falls back to plain deterministic lines such as Relay: app found at localhost:3000 with no spinner frames or cursor-control escape sequences.
• NO_COLOR=1 disables colours even in a TTY, and the terminal cursor is restored on normal exit, errors, SIGINT, and SIGTERM.
• Narrow terminals shorten their status details and fall back to plain ASCII symbols when Unicode is unavailable.