@silicaclaw/cli 1.0.0-beta.2 → 1.0.0-beta.21

package/scripts/quickstart.sh

@@ -1,9 +1,17 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+INVOKE_PWD="${INIT_CWD:-$PWD}"
 ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 WORK_DIR="$ROOT_DIR"
 IS_NPX_MODE=0
+DEFAULT_MODE_PICK="${QUICKSTART_DEFAULT_MODE:-3}"
+CONNECT_MODE="${QUICKSTART_CONNECT_MODE:-0}"
+
+case "$DEFAULT_MODE_PICK" in
+  1|2|3) ;;
+  *) DEFAULT_MODE_PICK="1" ;;
+esac
 
 case "$ROOT_DIR" in
   *"/.npm/_npx/"*)
@@ -29,6 +37,103 @@ run_cmd() {
   eval "$cmd"
 }
 
+run_cmd_may_fail() {
+  local cmd="$1"
+  printf '→ %s\n' "$cmd"
+  set +e
+  eval "$cmd"
+  local code=$?
+  set -e
+  return $code
+}
+
+first_writable_path_dir() {
+  local path_value="${PATH:-}"
+  local old_ifs="$IFS"
+  IFS=':'
+  for d in $path_value; do
+    if [ -n "$d" ] && [ -d "$d" ] && [ -w "$d" ] && [ -x "$d" ]; then
+      printf '%s' "$d"
+      IFS="$old_ifs"
+      return 0
+    fi
+  done
+  IFS="$old_ifs"
+  return 1
+}
+
+install_command_shim() {
+  local bindir="$1"
+  local script_path="$WORK_DIR/scripts/silicaclaw-cli.mjs"
+  local target="$bindir/silicaclaw"
+  if [ ! -f "$script_path" ]; then
+    echo "未找到 CLI 脚本: $script_path"
+    return 1
+  fi
+  cat >"$target" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+exec node "$script_path" "\$@"
+EOF
+  chmod +x "$target"
+  return 0
+}
+
+default_system_bin_dir() {
+  if [ -d "/usr/local/bin" ]; then
+    printf '/usr/local/bin'
+    return 0
+  fi
+  if [ -d "/opt/homebrew/bin" ]; then
+    printf '/opt/homebrew/bin'
+    return 0
+  fi
+  printf '/usr/local/bin'
+}
+
+detect_shell_rc_file() {
+  local sh_name="${SHELL:-}"
+  case "$sh_name" in
+    */zsh) printf '%s' "$HOME/.zshrc" ;;
+    */bash) printf '%s' "$HOME/.bashrc" ;;
+    *)
+      if [ -n "${ZSH_VERSION:-}" ]; then
+        printf '%s' "$HOME/.zshrc"
+      else
+        printf '%s' "$HOME/.bashrc"
+      fi
+      ;;
+  esac
+}
+
+install_npx_alias() {
+  local rc_file
+  rc_file="$(detect_shell_rc_file)"
+  local begin_mark="# >>> silicaclaw npx alias >>>"
+  local end_mark="# <<< silicaclaw npx alias <<<"
+  local alias_line="alias silicaclaw='npx -y @silicaclaw/cli@beta'"
+
+  mkdir -p "$(dirname "$rc_file")"
+  touch "$rc_file"
+
+  if grep -Fq "$begin_mark" "$rc_file"; then
+    echo "已存在 silicaclaw alias 配置: $rc_file"
+    return 0
+  fi
+
+  {
+    echo ""
+    echo "$begin_mark"
+    echo "$alias_line"
+    echo "$end_mark"
+  } >>"$rc_file"
+
+  echo "已写入 alias 到: $rc_file"
+  echo "执行以下命令即可在当前 shell 立即生效："
+  echo "source \"$rc_file\""
+  return 0
+}
+
 ask_yes_no() {
   local prompt="$1"
   local default="${2:-Y}"
@@ -50,6 +155,40 @@ pause_continue() {
   read -r -p "按回车继续..." _ || true
 }
 
+detect_public_ip() {
+  local ip=""
+  if command -v curl >/dev/null 2>&1; then
+    ip="$(curl -fsSL --max-time 3 https://api.ipify.org 2>/dev/null || true)"
+  fi
+  if [ -z "$ip" ] && command -v curl >/dev/null 2>&1; then
+    ip="$(curl -fsSL --max-time 3 https://ifconfig.me 2>/dev/null || true)"
+  fi
+  if [ -z "$ip" ] && command -v wget >/dev/null 2>&1; then
+    ip="$(wget -qO- --timeout=3 https://api.ipify.org 2>/dev/null || true)"
+  fi
+  ip="$(printf '%s' "$ip" | tr -d '[:space:]')"
+  printf '%s' "$ip"
+}
+
+url_host() {
+  local raw="${1:-}"
+  if [ -z "$raw" ]; then
+    printf ''
+    return 0
+  fi
+  node -e "try{const u=new URL(process.argv[1]); process.stdout.write(u.hostname||'');}catch{process.stdout.write('');}" "$raw"
+}
+
+url_port_or_default() {
+  local raw="${1:-}"
+  local fallback="${2:-4510}"
+  if [ -z "$raw" ]; then
+    printf '%s' "$fallback"
+    return 0
+  fi
+  node -e "try{const u=new URL(process.argv[1]); process.stdout.write(String(u.port || '$fallback'));}catch{process.stdout.write('$fallback');}" "$raw"
+}
+
 title "SilicaClaw Quick Start 启动"
 echo "目录: $ROOT_DIR"
 echo "目标: 用终端一步步完成安装与启动（类似 OpenClaw Quick Start）"
@@ -57,7 +196,7 @@ pause_continue
 
 if [ "$IS_NPX_MODE" -eq 1 ]; then
   title "选择安装目录（npx 模式）"
-  DEFAULT_TARGET_DIR="$(pwd)/silicaclaw"
+  DEFAULT_TARGET_DIR="$INVOKE_PWD/silicaclaw"
   TARGET_DIR_INPUT=""
   read -r -p "请输入安装目录（默认: ${DEFAULT_TARGET_DIR:-$HOME/silicaclaw}）: " TARGET_DIR_INPUT || true
   TARGET_DIR="${TARGET_DIR_INPUT:-$DEFAULT_TARGET_DIR}"
@@ -117,6 +256,68 @@ else
   fi
 fi
 
+title "安装系统命令（silicaclaw）"
+if command -v silicaclaw >/dev/null 2>&1; then
+  echo "已检测到系统命令: $(command -v silicaclaw)"
+  echo "跳过命令安装。"
+else
+  echo "将尝试无 sudo 安装 silicaclaw 命令到 PATH 中可写目录。"
+  BIN_DIR="$(first_writable_path_dir || true)"
+  INSTALLED=0
+  if [ -n "${BIN_DIR:-}" ]; then
+    if install_command_shim "$BIN_DIR"; then
+      echo "命令已安装: $BIN_DIR/silicaclaw"
+      hash -r || true
+      if command -v silicaclaw >/dev/null 2>&1; then
+        echo "验证成功: $(command -v silicaclaw)"
+        INSTALLED=1
+      else
+        echo "命令已写入，但当前 shell 未立即识别。请新开终端后运行 silicaclaw。"
+      fi
+    else
+      echo "命令安装失败。可继续使用: npx @silicaclaw/cli@beta <command>"
+    fi
+  else
+    echo "当前 PATH 中没有可写目录，无法无 sudo 安装系统命令。"
+  fi
+
+  if [ "$INSTALLED" != "1" ]; then
+    SYS_BIN_DIR="$(default_system_bin_dir)"
+    echo "为保证开箱即用体验，建议安装到系统目录: $SYS_BIN_DIR/silicaclaw"
+    if ask_yes_no "是否使用 sudo 安装系统命令？" "Y"; then
+      run_cmd "sudo mkdir -p \"$SYS_BIN_DIR\""
+      run_cmd "sudo tee \"$SYS_BIN_DIR/silicaclaw\" >/dev/null <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+exec node \"$WORK_DIR/scripts/silicaclaw-cli.mjs\" \"\$@\"
+EOF"
+      run_cmd "sudo chmod +x \"$SYS_BIN_DIR/silicaclaw\""
+      hash -r || true
+      if command -v silicaclaw >/dev/null 2>&1; then
+        echo "验证成功: $(command -v silicaclaw)"
+        INSTALLED=1
+      else
+        echo "安装完成，但当前 shell 未刷新。请新开终端后运行 silicaclaw。"
+      fi
+    else
+      echo "已跳过 sudo 安装。"
+    fi
+  fi
+
+  if [ "$INSTALLED" != "1" ]; then
+    echo "无需改 PATH/环境变量，也可一键使用 silicaclaw。"
+    if ask_yes_no "是否自动写入 shell alias（silicaclaw -> npx @silicaclaw/cli@beta）？" "Y"; then
+      if install_npx_alias; then
+        echo "alias 安装完成。新开终端后可直接使用 silicaclaw。"
+      else
+        echo "alias 安装失败。可继续使用: npx @silicaclaw/cli@beta <command>"
+      fi
+    else
+      echo "你仍可继续使用: npx @silicaclaw/cli@beta <command>"
+    fi
+  fi
+fi
+
 title "准备 social.md"
 if [ -f "$WORK_DIR/social.md" ]; then
   echo "已存在 social.md，保留现有配置。"
@@ -132,14 +333,22 @@ fi
 title "选择网络模式"
 echo "1) local           单机预览（最快）"
 echo "2) lan             局域网预览（A/B 双机）"
-echo "3) global-preview  非局域网预览（WebRTC）"
-read -r -p "请输入模式编号 [1/2/3] (默认 1): " MODE_PICK || true
-MODE_PICK="${MODE_PICK:-1}"
+echo "3) global-preview  互联网预览（Relay，推荐）"
+echo "提示: 不确定就直接回车（默认 global-preview）。"
+echo "提示: 互联网场景需要一个所有节点都可访问的 relay/signaling 地址。"
+if [ "$CONNECT_MODE" = "1" ]; then
+  MODE_PICK="3"
+  echo "connect 模式：已自动选择 global-preview。"
+else
+  read -r -p "请输入模式编号 [1/2/3] (默认 ${DEFAULT_MODE_PICK}): " MODE_PICK || true
+  MODE_PICK="${MODE_PICK:-$DEFAULT_MODE_PICK}"
+fi
 
 NETWORK_MODE="local"
 NETWORK_ADAPTER="local-event-bus"
 WEBRTC_SIGNALING_URL_VALUE=""
-WEBRTC_ROOM_VALUE="silicaclaw-demo"
+WEBRTC_ROOM_VALUE="silicaclaw-global-preview"
+AUTO_START_SIGNALING=0
 
 case "$MODE_PICK" in
   2)
@@ -148,14 +357,40 @@ case "$MODE_PICK" in
     ;;
   3)
     NETWORK_MODE="global-preview"
-    NETWORK_ADAPTER="webrtc-preview"
-    read -r -p "请输入 signaling URL（例如 http://your-server:4510）: " WEBRTC_SIGNALING_URL_VALUE
+    NETWORK_ADAPTER="relay-preview"
+    PUBLIC_IP="$(detect_public_ip)"
+    SIGNALING_DEFAULT="${WEBRTC_SIGNALING_URL:-http://localhost:4510}"
+    if [ -n "$PUBLIC_IP" ]; then
+      SIGNALING_DEFAULT="http://$PUBLIC_IP:4510"
+    fi
+    echo "提示: signaling 地址需要“所有节点可访问”。"
+    if [ -n "$PUBLIC_IP" ]; then
+      echo "已检测到本机公网 IP: $PUBLIC_IP"
+      echo "如果你这台机器就是 signaling 服务器，可直接回车使用默认值。"
+    else
+      echo "未检测到公网 IP，将使用默认值: $SIGNALING_DEFAULT"
+      echo "如果 signaling 在其他机器，请输入该机器公网地址。"
+    fi
+    read -r -p "请输入 signaling URL（默认 ${SIGNALING_DEFAULT}）: " WEBRTC_SIGNALING_URL_INPUT || true
+    WEBRTC_SIGNALING_URL_VALUE="${WEBRTC_SIGNALING_URL_INPUT:-$SIGNALING_DEFAULT}"
     if [ -z "${WEBRTC_SIGNALING_URL_VALUE:-}" ]; then
-      echo "global-preview 必须提供 signaling URL"
+      echo "global-preview 必须提供公网可达的 signaling URL"
       exit 1
     fi
-    read -r -p "请输入 room（默认 silicaclaw-demo）: " WEBRTC_ROOM_VALUE_INPUT || true
-    WEBRTC_ROOM_VALUE="${WEBRTC_ROOM_VALUE_INPUT:-silicaclaw-demo}"
+
+    SIGNALING_HOST="$(url_host "$WEBRTC_SIGNALING_URL_VALUE")"
+    if [ "$SIGNALING_HOST" = "localhost" ] || [ "$SIGNALING_HOST" = "127.0.0.1" ]; then
+      echo "提示: 当前 signaling URL 是本机地址，仅本机可用，不适合跨网络双机演示。"
+    fi
+
+    if ask_yes_no "是否在当前机器自动后台启动 signaling server（用于演示）？" "Y"; then
+      AUTO_START_SIGNALING=1
+      SIGNALING_PORT_VALUE="$(url_port_or_default "$WEBRTC_SIGNALING_URL_VALUE" "4510")"
+      echo "将尝试以 PORT=$SIGNALING_PORT_VALUE 后台启动 signaling server"
+    fi
+
+    read -r -p "请输入 room（默认 silicaclaw-global-preview）: " WEBRTC_ROOM_VALUE_INPUT || true
+    WEBRTC_ROOM_VALUE="${WEBRTC_ROOM_VALUE_INPUT:-silicaclaw-global-preview}"
     ;;
   *)
     NETWORK_MODE="local"
@@ -166,16 +401,47 @@ esac
 echo "已选择: $NETWORK_MODE ($NETWORK_ADAPTER)"
 
 title "启动 local-console"
-if [ "$NETWORK_MODE" = "global-preview" ]; then
-  echo "将使用以下参数启动："
-  echo "NETWORK_ADAPTER=$NETWORK_ADAPTER"
-  echo "WEBRTC_SIGNALING_URL=$WEBRTC_SIGNALING_URL_VALUE"
-  echo "WEBRTC_ROOM=$WEBRTC_ROOM_VALUE"
-  pause_continue
-  run_cmd "cd \"$WORK_DIR\" && NETWORK_ADAPTER=$NETWORK_ADAPTER WEBRTC_SIGNALING_URL=$WEBRTC_SIGNALING_URL_VALUE WEBRTC_ROOM=$WEBRTC_ROOM_VALUE npm run local-console"
+echo "1) gateway（推荐）  后台服务模式，可用 start/stop/restart/status 管理"
+echo "2) dev watch        前台开发模式（tsx watch）"
+read -r -p "请选择启动方式 [1/2] (默认 1): " START_MODE_PICK || true
+START_MODE_PICK="${START_MODE_PICK:-1}"
+
+if [ "$START_MODE_PICK" = "2" ]; then
+  if [ "$NETWORK_MODE" = "global-preview" ]; then
+    if [ "$AUTO_START_SIGNALING" -eq 1 ]; then
+      mkdir -p "$WORK_DIR/.silicaclaw"
+      SIGNALING_LOG="$WORK_DIR/.silicaclaw/signaling.log"
+      SIGNALING_PID_FILE="$WORK_DIR/.silicaclaw/signaling.pid"
+      run_cmd "cd \"$WORK_DIR\" && PORT=${SIGNALING_PORT_VALUE:-4510} nohup npm run webrtc-signaling > \"$SIGNALING_LOG\" 2>&1 & echo \$! > \"$SIGNALING_PID_FILE\""
+      echo "已后台启动 signaling server，日志: $SIGNALING_LOG"
+      echo "停止 signaling: kill \$(cat \"$SIGNALING_PID_FILE\")"
+    fi
+    echo "将使用以下参数启动（dev watch）："
+    echo "NETWORK_ADAPTER=$NETWORK_ADAPTER"
+    echo "WEBRTC_SIGNALING_URL=$WEBRTC_SIGNALING_URL_VALUE"
+    echo "WEBRTC_ROOM=$WEBRTC_ROOM_VALUE"
+    pause_continue
+    run_cmd "cd \"$WORK_DIR\" && NETWORK_ADAPTER=$NETWORK_ADAPTER WEBRTC_SIGNALING_URL=$WEBRTC_SIGNALING_URL_VALUE WEBRTC_ROOM=$WEBRTC_ROOM_VALUE npm run local-console"
+  else
+    echo "将使用以下参数启动（dev watch）："
+    echo "NETWORK_ADAPTER=$NETWORK_ADAPTER"
+    pause_continue
+    run_cmd "cd \"$WORK_DIR\" && NETWORK_ADAPTER=$NETWORK_ADAPTER npm run local-console"
+  fi
 else
-  echo "将使用以下参数启动："
-  echo "NETWORK_ADAPTER=$NETWORK_ADAPTER"
+  GATEWAY_CMD="cd \"$WORK_DIR\" && npm run gateway -- start --mode=$NETWORK_MODE"
+  if [ "$NETWORK_MODE" = "global-preview" ]; then
+    GATEWAY_CMD="$GATEWAY_CMD --signaling-url=$WEBRTC_SIGNALING_URL_VALUE --room=$WEBRTC_ROOM_VALUE"
+  fi
+  echo "将使用 gateway 后台启动："
+  echo "$GATEWAY_CMD"
   pause_continue
-  run_cmd "cd \"$WORK_DIR\" && NETWORK_ADAPTER=$NETWORK_ADAPTER npm run local-console"
+  run_cmd "$GATEWAY_CMD"
+  echo ""
+  echo "已启动完成。常用命令："
+  echo "cd \"$WORK_DIR\" && npm run gateway -- status"
+  echo "cd \"$WORK_DIR\" && npm run gateway -- logs local-console"
+  echo "cd \"$WORK_DIR\" && npm run gateway -- stop"
+  echo ""
+  echo "打开: http://localhost:4310"
 fi

package/scripts/silicaclaw-cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { accessSync, constants, cpSync, existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -23,18 +23,254 @@ function run(cmd, args, extra = {}) {
   process.exit(result.status ?? 0);
 }
 
+function runCapture(cmd, args, extra = {}) {
+  const result = spawnSync(cmd, args, {
+    cwd: ROOT_DIR,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+    env: process.env,
+    ...extra,
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  return result;
+}
+
+function runInherit(cmd, args, extra = {}) {
+  const result = spawnSync(cmd, args, {
+    cwd: ROOT_DIR,
+    stdio: "inherit",
+    env: process.env,
+    ...extra,
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  return result;
+}
+
 function readVersion() {
   const versionFile = resolve(ROOT_DIR, "VERSION");
   if (!existsSync(versionFile)) return "unknown";
   return readFileSync(versionFile, "utf8").trim() || "unknown";
 }
 
+function readPackageVersion() {
+  const pkgFile = resolve(ROOT_DIR, "package.json");
+  if (!existsSync(pkgFile)) return "unknown";
+  try {
+    const pkg = JSON.parse(readFileSync(pkgFile, "utf8"));
+    return String(pkg.version || "unknown");
+  } catch {
+    return "unknown";
+  }
+}
+
+function isNpxRun() {
+  return ROOT_DIR.includes("/.npm/_npx/");
+}
+
+function canWriteGlobalPrefix() {
+  try {
+    const prefixResult = runCapture("npm", ["prefix", "-g"]);
+    if ((prefixResult.status ?? 1) !== 0) return false;
+    const prefix = String(prefixResult.stdout || "").trim();
+    if (!prefix) return false;
+    const targetDir = resolve(prefix, "lib", "node_modules");
+    accessSync(targetDir, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function showUpdateGuide(current, latest, beta) {
+  const npxRuntime = isNpxRun();
+  console.log("SilicaClaw update check");
+  console.log(`current: ${current}`);
+  console.log(`latest : ${latest || "-"}`);
+  console.log(`beta   : ${beta || "-"}`);
+  console.log("");
+
+  const upToDate = Boolean(beta) && current === beta;
+  if (upToDate) {
+    console.log("You are already on the latest beta.");
+  } else {
+    console.log("Update available.");
+  }
+  console.log("");
+  console.log("Quick next commands:");
+  console.log("1) Start internet gateway");
+  console.log("   silicaclaw start --mode=global-preview --signaling-url=https://your-relay.example");
+  console.log("2) Check gateway status");
+  console.log("   silicaclaw status");
+  console.log("3) npx one-shot (no alias/global install)");
+  console.log("   npx -y @silicaclaw/cli@beta start --mode=global-preview --signaling-url=https://your-relay.example");
+  console.log("");
+
+  const writableGlobal = canWriteGlobalPrefix();
+  if (!npxRuntime && writableGlobal) {
+    console.log("Optional global install:");
+    console.log("   npm i -g @silicaclaw/cli@beta");
+    console.log("   silicaclaw version");
+    console.log("");
+  } else if (!npxRuntime) {
+    console.log("Global install skipped: npm global directory is not writable (likely EACCES).");
+    console.log("");
+  }
+  if (npxRuntime) {
+    console.log("Detected npx runtime.");
+    console.log("If `silicaclaw` is unavailable in this shell, use the npx one-shot command above.");
+  }
+}
+
+function getGatewayStatus() {
+  try {
+    const result = runCapture("node", [resolve(ROOT_DIR, "scripts", "silicaclaw-gateway.mjs"), "status"], {
+      cwd: process.cwd(),
+    });
+    if ((result.status ?? 1) !== 0) return null;
+    const text = String(result.stdout || "").trim();
+    return text ? JSON.parse(text) : null;
+  } catch {
+    return null;
+  }
+}
+
+function isManagedAppDir(appDir) {
+  if (!appDir || !existsSync(resolve(appDir, "package.json"))) return false;
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(appDir, "package.json"), "utf8"));
+    const name = String(pkg?.name || "");
+    return name === "@silicaclaw/cli" || name === "silicaclaw";
+  } catch {
+    return false;
+  }
+}
+
+function syncCurrentPackageToAppDir(appDir) {
+  if (!appDir || resolve(appDir) === ROOT_DIR) return false;
+  if (!isManagedAppDir(appDir)) return false;
+
+  const entries = [
+    "apps/local-console",
+    "apps/public-explorer",
+    "packages/core",
+    "packages/network",
+    "packages/storage",
+    "scripts",
+    "README.md",
+    "INSTALL.md",
+    "CHANGELOG.md",
+    "ARCHITECTURE.md",
+    "ROADMAP.md",
+    "SOCIAL_MD_SPEC.md",
+    "DEMO_GUIDE.md",
+    "RELEASE_NOTES_v1.0.md",
+    "social.md.example",
+    "openclaw.social.md.example",
+    "VERSION",
+    "package.json",
+    "package-lock.json",
+  ];
+
+  for (const rel of entries) {
+    const src = resolve(ROOT_DIR, rel);
+    if (!existsSync(src)) continue;
+    const dst = resolve(appDir, rel);
+    cpSync(src, dst, { recursive: true, force: true });
+  }
+  return true;
+}
+
+function restartGatewayIfRunning() {
+  const status = getGatewayStatus();
+  const appDir = status?.app_dir ? String(status.app_dir) : "";
+  const synced = syncCurrentPackageToAppDir(appDir);
+  if (synced) {
+    console.log(`Synced runtime files to app_dir: ${appDir}`);
+  }
+
+  const localRunning = Boolean(status?.local_console?.running);
+  const signalingRunning = Boolean(status?.signaling?.running);
+  if (!localRunning && !signalingRunning) {
+    console.log("Gateway not running: no restart needed.");
+    return;
+  }
+
+  const mode = String(status?.mode || "local");
+  const args = [resolve(ROOT_DIR, "scripts", "silicaclaw-gateway.mjs"), "restart", `--mode=${mode}`];
+  if (mode === "global-preview" && status?.signaling?.url) {
+    args.push(`--signaling-url=${status.signaling.url}`);
+  }
+  if (mode === "global-preview" && status?.signaling?.room) {
+    args.push(`--room=${status.signaling.room}`);
+  }
+
+  console.log("Refreshing gateway services...");
+  runInherit("node", args, { cwd: process.cwd() });
+}
+
+function tryGlobalUpgrade(beta) {
+  const writableGlobal = canWriteGlobalPrefix();
+  if (!writableGlobal) return false;
+  console.log(`Installing @silicaclaw/cli@${beta} globally...`);
+  const result = runInherit("npm", ["i", "-g", `@silicaclaw/cli@${beta}`]);
+  return (result.status ?? 1) === 0;
+}
+
+function update() {
+  const current = readPackageVersion();
+  try {
+    const result = runCapture("npm", ["view", "@silicaclaw/cli", "dist-tags", "--json"]);
+    if ((result.status ?? 1) !== 0) {
+      console.error("Failed to query npm dist-tags.");
+      if (result.stderr) console.error(result.stderr.trim());
+      process.exit(result.status ?? 1);
+    }
+    const text = String(result.stdout || "").trim();
+    const tags = text ? JSON.parse(text) : {};
+    const latest = tags.latest ? String(tags.latest) : "";
+    const beta = tags.beta ? String(tags.beta) : "";
+    showUpdateGuide(current, latest, beta);
+    const hasNewBeta = Boolean(beta) && beta !== current;
+    const npxRuntime = isNpxRun();
+
+    if (hasNewBeta) {
+      if (npxRuntime) {
+        console.log(`New beta detected (${beta}). npx will use latest on next run.`);
+      } else if (tryGlobalUpgrade(beta)) {
+        console.log(`Global upgrade completed: ${beta}`);
+      } else {
+        console.log("Skipped global upgrade (no write permission or upgrade failed).");
+      }
+    }
+
+    restartGatewayIfRunning();
+    process.exit(0);
+  } catch (error) {
+    console.error(`Update check failed: ${error.message}`);
+    console.log("Try manually:");
+    console.log("npm view @silicaclaw/cli dist-tags --json");
+    process.exit(1);
+  }
+}
+
 function help() {
   console.log(`
 SilicaClaw CLI
 
 Usage:
   silicaclaw onboard
+  silicaclaw connect
+  silicaclaw update
+  silicaclaw start [--mode=local|lan|global-preview]
+  silicaclaw stop
+  silicaclaw restart [--mode=local|lan|global-preview]
+  silicaclaw status
+  silicaclaw logs [local-console|signaling]
+  silicaclaw gateway <start|stop|restart|status|logs>
   silicaclaw local-console
   silicaclaw explorer
   silicaclaw signaling
@@ -44,6 +280,14 @@ Usage:
 
 Commands:
   onboard        Interactive step-by-step onboarding (recommended)
+  connect        Cross-network connect wizard (global-preview first)
+  update         Check latest npm version and show upgrade commands
+  start          Start gateway-managed background services
+  stop           Stop gateway-managed background services
+  restart        Restart gateway-managed background services
+  status         Show gateway-managed service status
+  logs           Show gateway-managed service logs
+  gateway        Manage background services (start/stop/restart/status/logs)
   local-console  Start local console (http://localhost:4310)
   explorer       Start public explorer (http://localhost:4311)
   signaling      Start WebRTC signaling preview server
@@ -59,6 +303,32 @@ switch (cmd) {
   case "onboard":
     run("bash", [resolve(ROOT_DIR, "scripts", "quickstart.sh")]);
     break;
+  case "connect":
+    run("bash", [resolve(ROOT_DIR, "scripts", "quickstart.sh")], {
+      env: {
+        ...process.env,
+        QUICKSTART_DEFAULT_MODE: "3",
+        QUICKSTART_CONNECT_MODE: "1",
+      },
+    });
+    break;
+  case "update":
+    update();
+    break;
+  case "gateway":
+    run("node", [resolve(ROOT_DIR, "scripts", "silicaclaw-gateway.mjs"), ...process.argv.slice(3)], {
+      cwd: process.cwd(),
+    });
+    break;
+  case "start":
+  case "stop":
+  case "restart":
+  case "status":
+  case "logs":
+    run("node", [resolve(ROOT_DIR, "scripts", "silicaclaw-gateway.mjs"), cmd, ...process.argv.slice(3)], {
+      cwd: process.cwd(),
+    });
+    break;
   case "local-console":
   case "console":
     run("npm", ["run", "local-console"]);