Relay

https://docs.relay.md
Admin
Relay is an Obsidian plugin that enables real-time multiplayer collaboration on notes and Canvases,...
Tokens:10,022
Snippets:99
Trust Score:7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Relay Beta Installation Script

Source: https://docs.relay.md/guides/install-relay-beta

A reference shell script for automating the download, verification, and installation of Relay beta assets.

```bash
# Agents: set VAULT to the absolute path of the target Obsidian vault before running.
VAULT="/absolute/path/to/your/vault"
REPO="No-Instructions/Relay"

set -euo pipefail

if [ "$VAULT" = "/absolute/path/to/your/vault" ]; then
  echo "Set VAULT to the absolute path of the Obsidian vault before running." >&2
  exit 1
fi

if [ ! -d "$VAULT/.obsidian" ]; then
  echo "Refusing to continue: $VAULT does not contain a .obsidian folder" >&2
  exit 1
fi

for tool in curl jq; do
  if ! command -v "$tool" >/dev/null 2>&1; then
    echo "Missing required tool: $tool" >&2
    exit 1
  fi
done

if command -v sha256sum >/dev/null 2>&1; then
  SHA256_CMD="sha256sum"
elif command -v shasum >/dev/null 2>&1; then
  SHA256_CMD="shasum -a 256"
else
  echo "Missing SHA-256 utility: need sha256sum or shasum" >&2
  exit 1
fi

sha256_of() {
  $SHA256_CMD "$1" | awk '{print $1}'
}

PLUGIN_DIR="$VAULT/.obsidian/plugins/system3-relay"
BACKUP_ROOT="$VAULT/.obsidian/.relay-beta-backups"
STAMP="$(date +%Y%m%d-%H%M%S)"
BACKUP_DIR="$BACKUP_ROOT/system3-relay-$STAMP"
TMPDIR="$(mktemp -d)"
STAGING=""

cleanup() {
  [ -n "${TMPDIR:-}" ] && rm -rf "$TMPDIR"
  [ -n "${STAGING:-}" ] && [ -d "$STAGING" ] && rm -rf "$STAGING"
  return 0
}
trap cleanup EXIT

DRY_RUN="${RELAY_DRY_RUN:-0}"

RELEASES_JSON="$TMPDIR/releases.json"
curl -fsSL "https://api.github.com/repos/$REPO/releases?per_page=50" -o "$RELEASES_JSON"

VERSION="$(jq -r '
  map(select(.draft == false and .prerelease == true))
  | map(select(
      ([.assets[].name] | contains(["main.js"]))
      and ([.assets[].name] | contains(["styles.css"]))
      and ([.assets[].name] | (contains(["manifest.json"]) or contains(["manifest-beta.json"])))
    ))
  | sort_by(.published_at)
  | reverse
  | .[0].tag_name // empty
' "$RELEASES_JSON")"

if [ -z "$VERSION" ]; then
  echo "No prerelease found with required Relay beta assets" >&2
  exit 1
fi

PUBLISHED_AT="$(jq -r --arg version "$VERSION" '
  (.[] | select(.tag_name == $version) | .published_at) // "unknown"
' "$RELEASES_JSON")"
```

--------------------------------

### Relay Beta Installation Script

Source: https://docs.relay.md/guides/install-relay-beta

A comprehensive shell script for verifying asset digests, downloading files, and performing a safe installation with backup capabilities.

```bash
asset_digest() {
  local asset_name="$1"
  jq -r --arg version "$VERSION" --arg asset "$asset_name" '
    (.[] | select(.tag_name == $version) | .assets[] | select(.name == $asset) | .digest) // empty
  ' "$RELEASES_JSON"
}

# Prefer the modern manifest.json asset; fall back to the older manifest-beta.json.
MANIFEST_ASSET="manifest.json"
if [ -z "$(asset_digest "$MANIFEST_ASSET")" ]; then
  MANIFEST_ASSET="manifest-beta.json"
fi

EXPECTED_DIGEST_MAIN="$(asset_digest main.js)"
EXPECTED_DIGEST_STYLES="$(asset_digest styles.css)"
EXPECTED_DIGEST_MANIFEST="$(asset_digest "$MANIFEST_ASSET")"

for pair in "main.js:$EXPECTED_DIGEST_MAIN" "styles.css:$EXPECTED_DIGEST_STYLES" "$MANIFEST_ASSET:$EXPECTED_DIGEST_MANIFEST"; do
  digest="${pair#*:}"
  asset="${pair%%:*}"
  if [ -z "$digest" ] || [ "${digest#sha256:}" = "$digest" ]; then
    echo "Missing or non-sha256 digest for $asset: '$digest'" >&2
    exit 1
  fi
done

echo "Relay beta release: $VERSION"
echo "Published: $PUBLISHED_AT"
echo "Vault: $VAULT"
echo "Plugin folder: $PLUGIN_DIR"
echo "Backup folder: $BACKUP_DIR"
echo "Expected digests:"
printf "  %-18s %s\n" "main.js" "$EXPECTED_DIGEST_MAIN"
printf "  %-18s %s\n" "styles.css" "$EXPECTED_DIGEST_STYLES"
printf "  %-18s %s\n" "$MANIFEST_ASSET" "$EXPECTED_DIGEST_MANIFEST"
echo "Will write: main.js, styles.css, manifest.json"
echo "Will preserve: data.json"
if [ -d "$PLUGIN_DIR" ]; then
  echo "Will back up (selective, only these files if present):"
  for f in main.js styles.css manifest.json data.json; do
    [ -f "$PLUGIN_DIR/$f" ] && echo "  $PLUGIN_DIR/$f"
  done
else
  echo "Will back up: nothing (fresh install)"
fi

if [ "$DRY_RUN" = "1" ]; then
  echo "RELAY_DRY_RUN=1; downloading and verifying without writing to the plugin folder."
elif [ "${RELAY_CONFIRM:-}" = "INSTALL" ]; then
  echo "RELAY_CONFIRM=INSTALL detected; proceeding without interactive prompt."
else
  printf "Type INSTALL to continue: "
  read -r CONFIRM
  if [ "$CONFIRM" != "INSTALL" ]; then
    echo "Cancelled."
    exit 1
  fi
fi

BASE="https://github.com/$REPO/releases/download/$VERSION"

curl -fsSL "$BASE/main.js" -o "$TMPDIR/main.js"
curl -fsSL "$BASE/styles.css" -o "$TMPDIR/styles.css"
curl -fsSL "$BASE/$MANIFEST_ASSET" -o "$TMPDIR/$MANIFEST_ASSET"

verify_digest() {
  local file="$1"
  local expected="$2"
  local expected_hex="${expected#sha256:}"
  local actual
  actual="$(sha256_of "$file")"
  if [ "$actual" != "$expected_hex" ]; then
    echo "SHA-256 mismatch for $(basename "$file"):" >&2
    echo "  expected $expected_hex" >&2
    echo "  actual   $actual" >&2
    exit 1
  fi
  echo "Verified $(basename "$file") $actual"
}

verify_digest "$TMPDIR/main.js" "$EXPECTED_DIGEST_MAIN"
verify_digest "$TMPDIR/styles.css" "$EXPECTED_DIGEST_STYLES"
verify_digest "$TMPDIR/$MANIFEST_ASSET" "$EXPECTED_DIGEST_MANIFEST"

jq --arg expected "$VERSION" '
  if .id == "system3-relay"
  then .version = $expected
  else error("Unexpected plugin id: \(.id)")
  end
' "$TMPDIR/$MANIFEST_ASSET" > "$TMPDIR/manifest.staged.json"
mv -f "$TMPDIR/manifest.staged.json" "$TMPDIR/manifest.json"
echo "Verified id=system3-relay; wrote manifest.json with version $VERSION (from $MANIFEST_ASSET)"

if [ "$DRY_RUN" = "1" ]; then
  echo "DRY RUN: all assets downloaded and verified. Would have installed:"
  echo "  $PLUGIN_DIR/main.js"
  echo "  $PLUGIN_DIR/styles.css"
  echo "  $PLUGIN_DIR/manifest.json"
  echo "Plugin folder was not modified. No backup was taken. Exiting."
  exit 0
fi

if [ -d "$PLUGIN_DIR" ]; then
  mkdir -p "$BACKUP_DIR"
  echo "Backing up to $BACKUP_DIR:"
  for f in main.js styles.css manifest.json data.json; do
    if [ -f "$PLUGIN_DIR/$f" ]; then
      cp "$PLUGIN_DIR/$f" "$BACKUP_DIR/$f"
      echo "  $f"
    fi
  done
else
  echo "Fresh install: no existing plugin folder, no backup taken."
fi

STAGING="$PLUGIN_DIR/.relay-install-staging-$STAMP"
mkdir -p "$STAGING"

cp "$TMPDIR/main.js" "$STAGING/main.js"
cp "$TMPDIR/styles.css" "$STAGING/styles.css"
cp "$TMPDIR/manifest.json" "$STAGING/manifest.json"

mv -f "$STAGING/main.js" "$PLUGIN_DIR/main.js"
mv -f "$STAGING/styles.css" "$PLUGIN_DIR/styles.css"
mv -f "$STAGING/manifest.json" "$PLUGIN_DIR/manifest.json"
rmdir "$STAGING"
STAGING=""
```

--------------------------------

### Relay Beta Installation Script

Source: https://docs.relay.md/guides/install-relay-beta

A reference shell script to automate the installation of the Relay beta. Set RELAY_DRY_RUN=1 for a preview or RELAY_CONFIRM=INSTALL to proceed.

```bash
# Agents: set VAULT to the absolute path of the target Obsidian vault before running.
VAULT="/absolute/path/to/your/vault"
REPO="No-Instructions/Relay"
set -euo pipefail

if [ "$VAULT" = "/absolute/path/to/your/vault" ]; then
  echo "Set VAULT to the absolute path of the Obsidian vault before running." >&2
  exit 1
fi

if [ ! -d "$VAULT/.obsidian" ]; then
  echo "Refusing to continue: $VAULT does not contain a .obsidian folder" >&2
  exit 1
fi

for tool in curl jq; do
  if ! command -v "$tool" >/dev/null 2>&1; then
    echo "Missing required tool: $tool" >&2
    exit 1
  fi
done

if command -v sha256sum >/dev/null 2>&1; then
  SHA256_CMD="sha256sum"
elif command -v shasum >/dev/null 2>&1; then
  SHA256_CMD="shasum -a 256"
else
  echo "Missing SHA-256 utility: need sha256sum or shasum" >&2
  exit 1
fi

sha256_of() {
  $SHA256_CMD "$1" | awk '{print $1}'
}

PLUGIN_DIR="$VAULT/.obsidian/plugins/system3-relay"
BACKUP_ROOT="$VAULT/.obsidian/.relay-beta-backups"
STAMP="$(date +%Y%m%d-%H%M%S)"
BACKUP_DIR="$BACKUP_ROOT/system3-relay-$STAMP"
TMPDIR="$(mktemp -d)"
STAGING=""

cleanup() {
  [ -n "${TMPDIR:-}" ] && rm -rf "$TMPDIR"
  [ -n "${STAGING:-}" ] && [ -d "$STAGING" ] && rm -rf "$STAGING"
  return 0
}
trap cleanup EXIT

DRY_RUN="${RELAY_DRY_RUN:-0}"
RELEASES_JSON="$TMPDIR/releases.json"

curl -fsSL "https://api.github.com/repos/$REPO/releases?per_page=50" -o "$RELEASES_JSON"

VERSION="$(jq -r ' map(select(.draft == false and .prerelease == true)) | map(select( ([.assets[].name] | contains(["main.js"])) and ([.assets[].name] | contains(["styles.css"])) and ([.assets[].name] | (contains(["manifest.json"]) or contains(["manifest-beta.json"]))) )) | sort_by(.published_at) | reverse | .[0].tag_name // empty ' "$RELEASES_JSON")"

if [ -z "$VERSION" ]; then
  echo "No prerelease found with required Relay beta assets" >&2
  exit 1
fi

PUBLISHED_AT="$(jq -r --arg version "$VERSION" ' (.[] | select(.tag_name == $version) | .published_at) // "unknown" ' "$RELEASES_JSON")"

asset_digest() {
  local asset_name="$1"
  jq -r --arg version "$VERSION" --arg asset "$asset_name" ' (.[] | select(.tag_name == $version) | .assets[] | select(.name == $asset) | .digest) // empty ' "$RELEASES_JSON"
}

# Prefer the modern manifest.json asset; fall back to the older manifest-beta.json.
```

--------------------------------

### Relay beta installation script

Source: https://docs.relay.md/guides/install-relay-beta

A comprehensive shell script that handles asset verification, backup of existing files, and installation of the Relay beta plugin.

```bash
MANIFEST_ASSET="manifest.json" if [ -z "$(asset_digest "$MANIFEST_ASSET")" ]; then MANIFEST_ASSET="manifest-beta.json" fi EXPECTED_DIGEST_MAIN="$(asset_digest main.js)" EXPECTED_DIGEST_STYLES="$(asset_digest styles.css)" EXPECTED_DIGEST_MANIFEST="$(asset_digest "$MANIFEST_ASSET")" for pair in "main.js:$EXPECTED_DIGEST_MAIN" "styles.css:$EXPECTED_DIGEST_STYLES" "$MANIFEST_ASSET:$EXPECTED_DIGEST_MANIFEST"; do digest="${pair#*:}" asset="${pair%%:*}" if [ -z "$digest" ] || [ "${digest#sha256:}" = "$digest" ]; then echo "Missing or non-sha256 digest for $asset: '$digest'" >&2 exit 1 fi done echo "Relay beta release: $VERSION" echo "Published: $PUBLISHED_AT" echo "Vault: $VAULT" echo "Plugin folder: $PLUGIN_DIR" echo "Backup folder: $BACKUP_DIR" echo "Expected digests:" printf " %-18s %s\n" "main.js" "$EXPECTED_DIGEST_MAIN" printf " %-18s %s\n" "styles.css" "$EXPECTED_DIGEST_STYLES" printf " %-18s %s\n" "$MANIFEST_ASSET" "$EXPECTED_DIGEST_MANIFEST" echo "Will write: main.js, styles.css, manifest.json" echo "Will preserve: data.json" if [ -d "$PLUGIN_DIR" ]; then echo "Will back up (selective, only these files if present):" for f in main.js styles.css manifest.json data.json; do [ -f "$PLUGIN_DIR/$f" ] && echo " $PLUGIN_DIR/$f" done else echo "Will back up: nothing (fresh install)" fi if [ "$DRY_RUN" = "1" ]; then echo "RELAY_DRY_RUN=1; downloading and verifying without writing to the plugin folder." elif [ "${RELAY_CONFIRM:-}" = "INSTALL" ]; then echo "RELAY_CONFIRM=INSTALL detected; proceeding without interactive prompt." else printf "Type INSTALL to continue: " read -r CONFIRM if [ "$CONFIRM" != "INSTALL" ]; then echo "Cancelled." exit 1 fi fi BASE="https://github.com/$REPO/releases/download/$VERSION" curl -fsSL "$BASE/main.js" -o "$TMPDIR/main.js" curl -fsSL "$BASE/styles.css" -o "$TMPDIR/styles.css" curl -fsSL "$BASE/$MANIFEST_ASSET" -o "$TMPDIR/$MANIFEST_ASSET" verify_digest() { local file="$1" local expected="$2" local expected_hex="${expected#sha256:}" local actual actual="$(sha256_of "$file")" if [ "$actual" != "$expected_hex" ]; then echo "SHA-256 mismatch for $(basename "$file"):" >&2 echo " expected $expected_hex" >&2 echo " actual $actual" >&2 exit 1 fi echo "Verified $(basename "$file") $actual" } verify_digest "$TMPDIR/main.js" "$EXPECTED_DIGEST_MAIN" verify_digest "$TMPDIR/styles.css" "$EXPECTED_DIGEST_STYLES" verify_digest "$TMPDIR/$MANIFEST_ASSET" "$EXPECTED_DIGEST_MANIFEST" jq --arg expected "$VERSION" ' if .id == "system3-relay" then .version = $expected else error("Unexpected plugin id: \(.id)") end ' "$TMPDIR/$MANIFEST_ASSET" > "$TMPDIR/manifest.staged.json" mv -f "$TMPDIR/manifest.staged.json" "$TMPDIR/manifest.json" echo "Verified id=system3-relay; wrote manifest.json with version $VERSION (from $MANIFEST_ASSET)" if [ "$DRY_RUN" = "1" ]; then echo "DRY RUN: all assets downloaded and verified. Would have installed:" echo " $PLUGIN_DIR/main.js" echo " $PLUGIN_DIR/styles.css" echo " $PLUGIN_DIR/manifest.json" echo "Plugin folder was not modified. No backup was taken. Exiting." exit 0 fi if [ -d "$PLUGIN_DIR" ]; then mkdir -p "$BACKUP_DIR" echo "Backing up to $BACKUP_DIR:" for f in main.js styles.css manifest.json data.json; do if [ -f "$PLUGIN_DIR/$f" ]; then cp "$PLUGIN_DIR/$f" "$BACKUP_DIR/$f" echo " $f" fi done else echo "Fresh install: no existing plugin folder, no backup taken." fi STAGING="$PLUGIN_DIR/.relay-install-staging-$STAMP" mkdir -p "$STAGING" cp "$TMPDIR/main.js" "$STAGING/main.js" cp "$TMPDIR/styles.css" "$STAGING/styles.css" cp "$TMPDIR/manifest.json" "$STAGING/manifest.json" mv -f "$STAGING/main.js" "$PLUGIN_DIR/main.js" mv -f "$STAGING/styles.css" "$PLUGIN_DIR/styles.css" mv -f "$STAGING/manifest.json" "$PLUGIN_DIR/manifest.json" rmdir "$STAGING" STAGING="" echo "Installed Relay $VERSION in $PLUGIN_DIR" if [ -d "$BACKUP_DIR" ]; then echo "Backup of replaced files is in $BACKUP_DIR" fi echo "This did not replace Relay settings stored in data.json." if command -v obsidian >/dev/null 2>&1; then ( cd "$VAULT" RELAY_ENABLED="$(obsidian plugin id=system3-relay 2>/dev/null | awk -F '\t' '$1 == "enabled" { print $2 }' || true)" if [ "$RELAY_ENABLED" = "true" ]; then obsidian plugin:disable id=system3-relay sleep 2 else echo "Relay was not enabled before install; enabling it now." fi obsidian plugin:enable id=system3-relay ) && echo "Restarted Relay via Obsidian CLI." && exit 0 echo "Obsidian CLI exists, but the plugin disable/enable cycle failed." fi
```

--------------------------------

### Install Relay Beta and Restart Plugin

Source: https://docs.relay.md/guides/install-relay-beta

This script confirms the installation, checks for existing backups, and attempts to restart the Relay plugin using the Obsidian CLI if available.

```bash
echo "Installed Relay $VERSION in $PLUGIN_DIR"
if [ -d "$BACKUP_DIR" ]; then
  echo "Backup of replaced files is in $BACKUP_DIR"
fi
echo "This did not replace Relay settings stored in data.json."
if command -v obsidian >/dev/null 2>&1; then
  (
    cd "$VAULT"
    RELAY_ENABLED="$(obsidian plugin id=system3-relay 2>/dev/null | awk -F '\t' '$1 == "enabled" { print $2 }' || true)"
    if [ "$RELAY_ENABLED" = "true" ]; then
      obsidian plugin:disable id=system3-relay
      sleep 2
    else
      echo "Relay was not enabled before install; enabling it now."
    fi
    obsidian plugin:enable id=system3-relay
  ) && echo "Restarted Relay via Obsidian CLI." && exit 0
  echo "Obsidian CLI exists, but the plugin disable/enable cycle failed. Obsidian may not be running with this vault open, the CLI may not be enabled, or Relay may need manual activation." >&2
fi
echo "In Obsidian, disable then re-enable Relay in Community plugins (or run 'Reload app without saving' from the command palette)."
```

--------------------------------

### Roll back an agent install

Source: https://docs.relay.md/guides/install-relay-beta

Restores plugin files from a specific timestamped backup directory into the active plugin folder.

```bash
BACKUP_DIR="<vault>/.obsidian/.relay-beta-backups/system3-relay-<timestamp>"
PLUGIN_DIR="<vault>/.obsidian/plugins/system3-relay"
[ -f "$BACKUP_DIR/main.js" ] && cp "$BACKUP_DIR/main.js" "$PLUGIN_DIR/main.js"
[ -f "$BACKUP_DIR/styles.css" ] && cp "$BACKUP_DIR/styles.css" "$PLUGIN_DIR/styles.css"
[ -f "$BACKUP_DIR/manifest.json" ] && cp "$BACKUP_DIR/manifest.json" "$PLUGIN_DIR/manifest.json"
[ -f "$BACKUP_DIR/data.json" ] && cp "$BACKUP_DIR/data.json" "$PLUGIN_DIR/data.json"
```

--------------------------------

### Roll Back Relay Beta Installation

Source: https://docs.relay.md/guides/install-relay-beta

Restores plugin files from a specific timestamped backup directory to the active plugin folder.

```bash
BACKUP_DIR="<vault>/.obsidian/.relay-beta-backups/system3-relay-<timestamp>"
PLUGIN_DIR="<vault>/.obsidian/plugins/system3-relay"

[ -f "$BACKUP_DIR/main.js" ]       && cp "$BACKUP_DIR/main.js"       "$PLUGIN_DIR/main.js"
[ -f "$BACKUP_DIR/styles.css" ]    && cp "$BACKUP_DIR/styles.css"    "$PLUGIN_DIR/styles.css"
[ -f "$BACKUP_DIR/manifest.json" ] && cp "$BACKUP_DIR/manifest.json" "$PLUGIN_DIR/manifest.json"
[ -f "$BACKUP_DIR/data.json" ]     && cp "$BACKUP_DIR/data.json"     "$PLUGIN_DIR/data.json"
```

--------------------------------

### Obsidian CLI Plugin Commands

Source: https://docs.relay.md/guides/install-relay-beta

Use these commands to disable and enable the Relay plugin to ensure proper unloading of old code.

```bash
obsidian plugin:disable id=system3-relay
```

```bash
obsidian plugin:enable id=system3-relay
```
Tokens:
Raw