relay CLI reference

The client now covers bootstrap, deploys, controls, and admin work.

relay.js already ships much more than a thin deploy command. It supports socket and HTTP transport, an interactive setup wizard, sync-based deploys, rollout inspection, rollback, app control, secrets, and buildpack plugin operations.

First local run

relay init --socket ./data/relay.sock --app demo
relay deploy --host-port 3005
relay status
relay projects

If .relay.json is missing and stdin is a TTY, any command can start the setup wizard automatically.

Command groups

The CLI surface breaks into four concrete jobs.

This matches what relay.js actually exposes today: setup, deploy and inspect, slot control, and admin operations.

Bootstrap

Set project defaults with relay init, or just run a command and let the interactive wizard write .relay.json for you.

Bootstrap

relay init --socket ./data/relay.sock --app demo
relay deploy

Ship and inspect

Deploy with sync-first uploads, then inspect the latest slot with status, logs, list, and projects. Build logs stream by default; pass --no-stream to suppress.

Ship and inspect

relay deploy --host-port 3005
relay status
relay logs <deploy-id>
relay logs <deploy-id> --no-stream
relay list --app demo --limit 10
relay projects

Control the slot

Rollback or directly start, stop, and restart the running container for one app, env, and branch.

Control the slot

relay rollback
relay stop
relay start
relay restart

Version and updates

Check relay, relayd, and station versions from one command, then update agent binaries in place when a new release lands.

Version and updates

relay version
relay agent status
relay agent update

Admin surfaces

Manage app secrets and buildpack plugins from the CLI without opening the dashboard.

Admin surfaces

relay secrets list
relay secrets add --key DATABASE_URL --value postgres://...
relay plugin list
relay plugin install ./astro-static.json

Transport modes

Use the socket locally. Use HTTP remotely.

The command set is the same either way. Only the transport and auth model change.

Socket transport

Use --socket or RELAY_SOCKET when the CLI runs on the same machine as relayd. No token is required because the socket is protected by filesystem permissions.

Socket transport

{
  "socket": "./data/relay.sock",
  "app": "demo",
  "env": "preview",
  "branch": "main"
}

HTTP transport

Use --url plus --token, or RELAY_URL and RELAY_TOKEN, when the CLI runs remotely. The client sends X-Relay-Token on each request.

HTTP transport

{
  "url": "http://127.0.0.1:8080",
  "token": "YOUR_TOKEN",
  "app": "demo",
  "env": "preview",
  "branch": "main"
}

Deploy path

relay deploy is a sync pipeline first, then a rollout.

The client does not tar the whole repo by default. It computes local state, asks the agent what changed, uploads only the diff, then triggers the build and container swap.

Start a sync session

relay deploy calls /api/sync/start, receives a session_id, and prepares a staging area on the agent.

Hash, diff, upload

The CLI walks the workspace, computes a manifest, asks /api/sync/plan what changed, uploads only needed files, and posts deletes for stale paths.

Finish and stream

The final /api/sync/finish call triggers the build and rollout. With --stream, the CLI follows /api/logs/stream/<id> until a terminal status arrives.

Deploy flags

relay deploy \
  --dir . \
  --mode port \
  --host-port 3005 \
  --service-port 3000 \
  --public-host demo.preview.example.com \
  --install-cmd "npm ci" \
  --build-cmd "npm run build" \
  --start-cmd "node server.js" \
  --no-stream

Build logs stream by default. Pass --no-stream to suppress live output and just print the log ID. mode is validated by the agent as port or traefik.

Important implementation detail

traffic_mode exists on the server as edge or session, but it is stored through app config, not as a relay deploy flag.

preview_url comes back from the deploy record after rollout, and relay deploy prints it when streaming finishes.

status, list, and projects are read-only views over the same deploy and app state tables the dashboard uses.

Streaming log flow

GET /api/logs/stream/<deploy-id>

event: message
data: {"message":"selected buildpack: node-next"}

event: deploy-status
data: {"status":"running"}

Streaming is on by default. The client renders progress lines in place and exits with the final deploy status. Use --no-stream on either relay deploy or relay logs to get static output instead.

Config resolution

Flags win, then project config, then environment variables.

resolveDeployArgs and resolveTransport both follow the same layered model, which keeps debugging straightforward.

CLI flags

Explicit flags like --socket, --url, --token, --app, and --branch override everything else for one invocation.

.relay.json

Project-local defaults written by relay init or the interactive setup wizard.

Environment variables

RELAY_SOCKET, RELAY_URL, RELAY_TOKEN, RELAY_APP, RELAY_ENV, and RELAY_BRANCH.

Compiled defaults

url defaults to http://127.0.0.1:8080, env to preview, and branch to main.

Build hints

relay.config.json is read for install_cmd, build_cmd, start_cmd, and service_port when deploying.

.relay.json

{
  "socket": "./data/relay.sock",
  "app": "demo",
  "env": "preview",
  "branch": "main",
  "dir": "."
}

When no config exists and stdin is interactive, relay.js launches the setup wizard instead of failing immediately.

Recent additions

The docs now cover the newer commands and the real transport model.

Interactive setup wizard

Any command can bootstrap .relay.json when config is missing and stdin is a TTY.

Socket-first local auth

The CLI can skip tokens entirely on the same machine by targeting relay.sock.

Version visibility

relay version reports CLI, installed binaries, latest release, and server version data from /api/version when reachable.

One-command updates

relay agent update compares installed and latest releases, then downloads the correct OS archive only when you are behind.

status, list, and projects

Read deploy history and project inventory without opening the dashboard. list accepts --limit to cap results.

Secrets and plugin admin

Manage app secrets and buildpack plugins directly from the CLI.

Streaming on by default

relay deploy and relay logs stream build output without any flag. Pass --no-stream to suppress live output and print the log ID instead.

Read the agent reference Read the plugin guide