@relay-org/relay

relay — Relay CLI

Zero-dependency Node 18+ CLI for the Relay self-hosted deployment platform.

• Syncs only changed files (sha256 diff)
• Auto-detects buildpacks (Node, Go, Python, Rust, .NET, Java, C/C++, WASM, static)
• Streams build + deploy logs in real time
• Downloads relayd plus the optional station runtime automatically

Requirements

• Node 18+
• A running relayd agent + token
• Works on Windows / macOS / Linux

Install

npm install -g @relay-org/relay

Quick Start

# 1. Download and install the agent binaries (one-time)
relay agent install

# 2. Start the agent on your server
relayd

# 3. Init your project (writes .relay.json)
relay init

# 4. Deploy
relay deploy --stream

Engine selection: when relay init asks which engine to use, choose docker. Docker is Relay's default engine and the supported path for production lanes. Station is still experimental — keep it as a secondary local/WSL workflow until a stable release is announced.

Commands

relay init                         Interactive setup → writes .relay.json
relay deploy [--stream]            Sync + build + rollout
relay status                       Latest deploy status
relay logs <id>                    Stream build logs
relay list                         Recent deploys
relay projects                     All projects and environments
relay rollback                     Roll back to previous image
relay start / stop / restart       Control a running container
relay secrets list/add/rm          Manage app secrets
relay plugin list/search           Inspect the server-side plugin catalog
relay plugin install/remove        Install or remove local plugin JSON
relay plugin install-url           Install a remote plugin over HTTPS with optional SHA256 pin
relay version                      Show relay/relayd/station versions
relay doctor                       Check agent connectivity, Docker, DNS, TLS, and socket state
relay agent install [--version v]  Download relayd and the optional station runtime
relay agent update                 Update relayd + station to latest release
relay agent status                 Show installed/latest versions and outdated status

Usage

deploy

relay deploy --stream

With explicit flags (overrides .relay.json):

relay deploy \
  --url http://127.0.0.1:8080 \
  --token YOURTOKEN \
  --app myapp \
  --env preview \
  --branch main \
  --dir . \
  --mode port \
  --host-port 3001 \
  --service-port 3000 \
  --public-host "" \
  --stream

Optional overrides

These override defaults from config files / agent buildpacks:

• --install-cmd "npm ci"
• --build-cmd "npm run build"
• --start-cmd "npm start"
• --service-port 3000

init

relay init
# or with flags:
relay init --url http://127.0.0.1:8080 --token YOURTOKEN --app myapp --env preview

start / stop / restart

relay restart --app myapp --env preview --branch main

plugin list / search / install / install-url / remove

relay plugin list
relay plugin search astro
relay plugin install ./plugins/astro-static.json
relay plugin install-url https://example.com/plugins/astro-static.json --sha256 <hex>
relay plugin remove astro-static

Plugin install and remove require RELAY_ENABLE_PLUGIN_MUTATIONS=true on the agent. Remote installs are HTTPS-only, and --sha256 lets you pin the exact plugin JSON you expect.

agent install

Downloads the correct relayd bundle for your platform from GitHub Releases, including the experimental station runtime when available:

relay agent install           # latest
relay agent install --version v0.1.7

Installs to ~/.relay/bin/ and prints the PATH line to add.

agent update

Checks GitHub Releases, compares with your installed .relay-version, and downloads the latest OS-specific archive only when you are behind:

relay agent update

version

Shows component versions in one place:

• relay CLI version
• installed agent version + latest release
• binary-reported relayd --version and station --version
• server-reported versions from /api/version when the agent is reachable

doctor

Runs local and server-side checks for the common setup failures:

• local agent binaries
• local socket access when using --socket
• local Docker reachability on same-machine installs
• agent health and server version
• server-side checks for data dir, secrets key, Docker, Caddy, ACME, DNS, TLS, and webhook URL

relay doctor

Flags

Flag	Required	Example	Notes
--url	usually	http://127.0.0.1:8080	Relay Agent base URL
--token	yes	abcd...	X-Relay-Token / Bearer auth
--app	yes	moneypasar	Workspace key
--env	yes	preview, dev, staging, or prod	Determines the lane policy used by the agent
--branch	yes	main	Included in workspace key
--dir	yes	.	Local folder to deploy
--mode	no	port	Agent supports port (and can later support traefik)
--host-port	no	3001	Host port mapping (mode=port)
--service-port	no	3000	Container port (if your app doesn’t use defaults)
--public-host	no	demo.local	Stored as metadata (useful with a reverse proxy)
--stream	no	true	Stream logs via SSE

Config resolution order

The CLI merges settings in this order (highest priority first):

1. CLI flags (--token, --app, etc.)
2. Local .relay.json (created by init)
3. relay.config.json (build hints and optional monorepo layout: install_cmd, build_cmd, start_cmd, service_port, project_root, build_context, dockerfile)
4. Environment variables (RELAY_URL, RELAY_TOKEN, RELAY_APP, RELAY_ENV, RELAY_BRANCH)
5. Fallback defaults (url=http://127.0.0.1:8080, env=preview, branch=main, dir=.)

relay.json is not part of CLI connection resolution. It is reserved for project companion services such as Postgres and Redis.

Monorepo build layout

relay.config.json can also steer where Relay builds from inside a larger repo:

{
  "project_root": "apps/web",
  "build_context": "apps/web",
  "dockerfile": "apps/web/Dockerfile"
}

• project_root selects the repo-relative app root for detection and generated assets.
• build_context selects the Docker build context when it differs from the app root.
• dockerfile points to a repo-relative Dockerfile or Containerfile.

If dockerfile is omitted, Relay can auto-detect root or nested Dockerfiles under the selected roots before it falls back to buildpack detection.

What gets uploaded

The CLI walks files under --dir and ignores common heavy/build output folders (must match the agent’s ignore list):

• node_modules, .git, .next, dist, .turbo, coverage, .relay, cache, bin, obj, target

It sends a manifest containing {path, size, mtime, sha256} and uploads only the files the agent requests.

Add a project-level .relayignore file when you want to exclude extra local files or directories from sync. Relay also reuses cached file hashes when size and mtime are unchanged, so repeat deploys do not re-hash the entire workspace.

The CLI also stores a local workspace fingerprint. If the server workspace changed but your local repo changed too, Relay can proceed with the newer local content instead of immediately forcing a relay pull or --force retry.

Security notes

• Treat the Relay token like a password. Don’t commit it.
• By default, the agent may be configured with permissive CORS and broad local access—keep the agent bound to 127.0.0.1 unless you’ve hardened it behind a proxy.

Troubleshooting

“Missing --token / --app”

Run init or provide the flags:

node relay-deploy.js init --url http://127.0.0.1:8080 --token YOURTOKEN --app myapp --env preview --branch main --dir .

Upload is slow on big repos

Right now the manifest computes sha256 for every file. Later on will improve.

License

Copyright 2026 babymonie

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.