@vellumai/cli 0.5.5 → 0.5.7

package/knip.json

@@ -2,7 +2,10 @@
   "entry": [
     "src/**/*.test.ts",
     "src/**/__tests__/**/*.ts",
-    "src/adapters/openclaw-http-server.ts"
+    "src/adapters/openclaw-http-server.ts",
+    "src/lib/version-compat.ts",
+    "src/lib/platform-releases.ts",
+    "src/lib/cli-error.ts"
   ],
   "project": ["src/**/*.ts", "src/**/*.tsx"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/health-check.test.ts

@@ -10,6 +10,7 @@ describe("checkHealth", () => {
   test("returns unreachable for non-existent host", async () => {
     const result = await checkHealth("http://127.0.0.1:1");
     expect(["unreachable", "timeout"]).toContain(result.status);
+    expect(result.version).toBeUndefined();
   });
 
   test("returns healthy for a mock healthy endpoint", async () => {
@@ -24,6 +25,24 @@ describe("checkHealth", () => {
       const result = await checkHealth(`http://localhost:${server.port}`);
       expect(result.status).toBe("healthy");
       expect(result.detail).toBeNull();
+      expect(result.version).toBeUndefined();
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("returns version when present in response", async () => {
+    const server = Bun.serve({
+      port: 0,
+      fetch() {
+        return Response.json({ status: "healthy", version: "1.2.3" });
+      },
+    });
+
+    try {
+      const result = await checkHealth(`http://localhost:${server.port}`);
+      expect(result.status).toBe("healthy");
+      expect(result.version).toBe("1.2.3");
     } finally {
       server.stop(true);
     }
@@ -33,7 +52,11 @@ describe("checkHealth", () => {
     const server = Bun.serve({
       port: 0,
       fetch() {
-        return Response.json({ status: "degraded", message: "high latency" });
+        return Response.json({
+          status: "degraded",
+          message: "high latency",
+          version: "0.9.0",
+        });
       },
     });
 
@@ -41,6 +64,7 @@ describe("checkHealth", () => {
       const result = await checkHealth(`http://localhost:${server.port}`);
       expect(result.status).toBe("degraded");
       expect(result.detail).toBe("high latency");
+      expect(result.version).toBe("0.9.0");
     } finally {
       server.stop(true);
     }
@@ -57,6 +81,7 @@ describe("checkHealth", () => {
     try {
       const result = await checkHealth(`http://localhost:${server.port}`);
       expect(result.status).toBe("error (500)");
+      expect(result.version).toBeUndefined();
     } finally {
       server.stop(true);
     }

package/src/commands/backup.ts

@@ -1,22 +1,10 @@
 import { mkdirSync, writeFileSync } from "fs";
-import { homedir } from "os";
 import { dirname, join } from "path";
 
 import { findAssistantByName } from "../lib/assistant-config";
+import { getBackupsDir, formatSize } from "../lib/backup-ops.js";
 import { loadGuardianToken, leaseGuardianToken } from "../lib/guardian-token";
 
-function getBackupsDir(): string {
-  const dataHome =
-    process.env.XDG_DATA_HOME?.trim() || join(homedir(), ".local", "share");
-  return join(dataHome, "vellum", "backups");
-}
-
-function formatSize(bytes: number): string {
-  if (bytes < 1024) return `${bytes} B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
-  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-}
-
 export async function backup(): Promise<void> {
   const args = process.argv.slice(3);
 
@@ -104,6 +92,33 @@ export async function backup(): Promise<void> {
       body: JSON.stringify({ description: "CLI backup" }),
       signal: AbortSignal.timeout(120_000),
     });
+
+    // Retry once with a fresh token on 401 — the cached token may be stale
+    // after a container restart that generated a new gateway signing key.
+    if (response.status === 401) {
+      let refreshedToken: string | null = null;
+      try {
+        const freshToken = await leaseGuardianToken(
+          entry.runtimeUrl,
+          entry.assistantId,
+        );
+        refreshedToken = freshToken.accessToken;
+      } catch {
+        // If token refresh fails, fall through to the !response.ok handler below
+      }
+      if (refreshedToken) {
+        accessToken = refreshedToken;
+        response = await fetch(`${entry.runtimeUrl}/v1/migrations/export`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${accessToken}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({ description: "CLI backup" }),
+          signal: AbortSignal.timeout(120_000),
+        });
+      }
+    }
   } catch (err) {
     if (err instanceof Error && err.name === "TimeoutError") {
       console.error("Error: Export request timed out after 2 minutes.");

package/src/commands/hatch.ts

@@ -39,12 +39,14 @@ import type { RemoteHost, Species } from "../lib/constants";
 import { hatchDocker } from "../lib/docker";
 import { hatchGcp } from "../lib/gcp";
 import type { PollResult, WatchHatchingResult } from "../lib/gcp";
+import { buildNestedConfig, writeInitialConfig } from "../lib/config-utils";
 import {
   startLocalDaemon,
   startGateway,
   stopLocalProcesses,
 } from "../lib/local";
 import { maybeStartNgrokTunnel } from "../lib/ngrok";
+import { getPlatformUrl } from "../lib/platform-client";
 import { httpHealthCheck } from "../lib/http-client";
 import { detectOrphanedProcesses } from "../lib/orphan-detection";
 import { isProcessAlive, stopProcess } from "../lib/process";
@@ -99,8 +101,9 @@ export async function buildStartupScript(
   providerApiKeys: Record<string, string>,
   instanceName: string,
   cloud: RemoteHost,
+  configValues: Record<string, string> = {},
 ): Promise<string> {
-  const platformUrl = process.env.VELLUM_PLATFORM_URL ?? "https://vellum.ai";
+  const platformUrl = getPlatformUrl();
   const logPath =
     cloud === "custom"
       ? "/tmp/vellum-startup.log"
@@ -130,6 +133,22 @@ export async function buildStartupScript(
     .map((envVar) => `${envVar}=\$${envVar}`)
     .join("\n");
 
+  // Write --config key=value pairs to a temp JSON file on the remote host
+  // and export the env var so the daemon reads it on first boot.
+  let configWriteBlock = "";
+  if (Object.keys(configValues).length > 0) {
+    const configJson = JSON.stringify(buildNestedConfig(configValues), null, 2);
+    configWriteBlock = `
+echo "Writing default workspace config..."
+VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH="/tmp/vellum-initial-config-$$.json"
+cat > "\$VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH" << 'VELLUM_CONFIG_EOF'
+${configJson}
+VELLUM_CONFIG_EOF
+export VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH
+echo "Default workspace config written to \$VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH"
+`;
+  }
+
   return `#!/bin/bash
 set -e
 
@@ -146,9 +165,10 @@ RUNTIME_HTTP_PORT=7821
 DOTENV_EOF
 
 ${ownershipFixup}
-
+${configWriteBlock}
 export VELLUM_SSH_USER="\$SSH_USER"
 export VELLUM_ASSISTANT_NAME="\$VELLUM_ASSISTANT_NAME"
+export VELLUM_CLOUD="${cloud}"
 echo "Downloading install script from ${platformUrl}/install.sh..."
 curl -fsSL ${platformUrl}/install.sh -o ${INSTALL_SCRIPT_REMOTE_PATH}
 echo "Install script downloaded (\$(wc -c < ${INSTALL_SCRIPT_REMOTE_PATH}) bytes)"
@@ -166,9 +186,9 @@ interface HatchArgs {
   keepAlive: boolean;
   name: string | null;
   remote: RemoteHost;
-  daemonOnly: boolean;
   restart: boolean;
   watch: boolean;
+  configValues: Record<string, string>;
 }
 
 function parseArgs(): HatchArgs {
@@ -178,9 +198,9 @@ function parseArgs(): HatchArgs {
   let keepAlive = false;
   let name: string | null = null;
   let remote: RemoteHost = DEFAULT_REMOTE;
-  let daemonOnly = false;
   let restart = false;
   let watch = false;
+  const configValues: Record<string, string> = {};
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -199,9 +219,6 @@ function parseArgs(): HatchArgs {
       console.log(
         "  --remote <host>           Remote host (local, gcp, aws, docker, custom)",
       );
-      console.log(
-        "  --daemon-only             Start assistant only, skip gateway",
-      );
       console.log(
         "  --restart                 Restart processes without onboarding side effects",
       );
@@ -211,11 +228,12 @@ function parseArgs(): HatchArgs {
       console.log(
         "  --keep-alive              Stay alive after hatch, exit when gateway stops",
       );
+      console.log(
+        "  --config <key=value>      Set a workspace config value (repeatable)",
+      );
       process.exit(0);
     } else if (arg === "-d") {
       detached = true;
-    } else if (arg === "--daemon-only") {
-      daemonOnly = true;
     } else if (arg === "--restart") {
       restart = true;
     } else if (arg === "--watch") {
@@ -248,11 +266,28 @@ function parseArgs(): HatchArgs {
       }
       remote = next as RemoteHost;
       i++;
+    } else if (arg === "--config") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("-")) {
+        console.error("Error: --config requires a key=value argument");
+        process.exit(1);
+      }
+      const eqIndex = next.indexOf("=");
+      if (eqIndex <= 0) {
+        console.error(
+          `Error: --config value must be in key=value format, got '${next}'`,
+        );
+        process.exit(1);
+      }
+      const key = next.slice(0, eqIndex);
+      const value = next.slice(eqIndex + 1);
+      configValues[key] = value;
+      i++;
     } else if (VALID_SPECIES.includes(arg as Species)) {
       species = arg as Species;
     } else {
       console.error(
-        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --daemon-only, --restart, --watch, --keep-alive, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>`,
+        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --restart, --watch, --keep-alive, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>, --config <key=value>`,
       );
       process.exit(1);
     }
@@ -264,9 +299,9 @@ function parseArgs(): HatchArgs {
     keepAlive,
     name,
     remote,
-    daemonOnly,
     restart,
     watch,
+    configValues,
   };
 }
 
@@ -574,10 +609,10 @@ function installCLISymlink(): void {
 async function hatchLocal(
   species: Species,
   name: string | null,
-  daemonOnly: boolean = false,
   restart: boolean = false,
   watch: boolean = false,
   keepAlive: boolean = false,
+  configValues: Record<string, string> = {},
 ): Promise<void> {
   if (restart && !name && !process.env.VELLUM_ASSISTANT_NAME) {
     console.error(
@@ -709,46 +744,44 @@ async function hatchLocal(
     process.env.APP_VERSION = cliPkg.version;
   }
 
-  await startLocalDaemon(watch, resources);
+  const defaultWorkspaceConfigPath = writeInitialConfig(configValues);
+
+  await startLocalDaemon(watch, resources, { defaultWorkspaceConfigPath });
 
-  // When daemonOnly is set, skip gateway and ngrok — the caller only wants
-  // the daemon restarted (e.g. macOS app bootstrap retry).
   let runtimeUrl = `http://127.0.0.1:${resources.gatewayPort}`;
-  if (!daemonOnly) {
-    try {
-      runtimeUrl = await startGateway(watch, resources);
-    } catch (error) {
-      // Gateway failed — stop the daemon we just started so we don't leave
-      // orphaned processes with no lock file entry.
-      console.error(
-        `\n❌ Gateway startup failed — stopping assistant to avoid orphaned processes.`,
-      );
-      await stopLocalProcesses(resources);
-      throw error;
-    }
+  try {
+    runtimeUrl = await startGateway(watch, resources);
+  } catch (error) {
+    // Gateway failed — stop the daemon we just started so we don't leave
+    // orphaned processes with no lock file entry.
+    console.error(
+      `\n❌ Gateway startup failed — stopping assistant to avoid orphaned processes.`,
+    );
+    await stopLocalProcesses(resources);
+    throw error;
+  }
 
-    // Lease a guardian token so the desktop app can import it on first launch
-    // instead of hitting /v1/guardian/init itself.
-    try {
-      await leaseGuardianToken(runtimeUrl, instanceName);
-    } catch (err) {
-      console.error(`⚠️  Guardian token lease failed: ${err}`);
-    }
+  // Lease a guardian token so the desktop app can import it on first launch
+  // instead of hitting /v1/guardian/init itself.
+  try {
+    await leaseGuardianToken(runtimeUrl, instanceName);
+  } catch (err) {
+    console.error(`⚠️  Guardian token lease failed: ${err}`);
+  }
 
-    // Auto-start ngrok if webhook integrations (e.g. Telegram, Twilio) are configured.
-    // Set BASE_DATA_DIR so ngrok reads the correct instance config.
-    const prevBaseDataDir = process.env.BASE_DATA_DIR;
-    process.env.BASE_DATA_DIR = resources.instanceDir;
-    const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort);
-    if (ngrokChild?.pid) {
-      const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
-      writeFileSync(ngrokPidFile, String(ngrokChild.pid));
-    }
-    if (prevBaseDataDir !== undefined) {
-      process.env.BASE_DATA_DIR = prevBaseDataDir;
-    } else {
-      delete process.env.BASE_DATA_DIR;
-    }
+  // Auto-start ngrok if webhook integrations (e.g. Telegram, Twilio) are configured.
+  // Set BASE_DATA_DIR so ngrok reads the correct instance config.
+  const prevBaseDataDir = process.env.BASE_DATA_DIR;
+  process.env.BASE_DATA_DIR = resources.instanceDir;
+  const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort);
+  if (ngrokChild?.pid) {
+    const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
+    writeFileSync(ngrokPidFile, String(ngrokChild.pid));
+  }
+  if (prevBaseDataDir !== undefined) {
+    process.env.BASE_DATA_DIR = prevBaseDataDir;
+  } else {
+    delete process.env.BASE_DATA_DIR;
   }
 
   const localEntry: AssistantEntry = {
@@ -761,7 +794,7 @@ async function hatchLocal(
     serviceGroupVersion: cliPkg.version ? `v${cliPkg.version}` : undefined,
     resources,
   };
-  if (!daemonOnly && !restart) {
+  if (!restart) {
     saveAssistantEntry(localEntry);
     setActiveAssistant(instanceName);
     syncConfigToLockfile();
@@ -780,12 +813,8 @@ async function hatchLocal(
   }
 
   if (keepAlive) {
-    // When --daemon-only is set, no gateway is running — poll the daemon
-    // health endpoint instead of the gateway to avoid self-termination.
-    const healthUrl = daemonOnly
-      ? `http://127.0.0.1:${resources.daemonPort}/healthz`
-      : `http://127.0.0.1:${resources.gatewayPort}/healthz`;
-    const healthTarget = daemonOnly ? "Assistant" : "Gateway";
+    const healthUrl = `http://127.0.0.1:${resources.gatewayPort}/healthz`;
+    const healthTarget = "Gateway";
     const POLL_INTERVAL_MS = 5000;
     const MAX_FAILURES = 3;
     let consecutiveFailures = 0;
@@ -839,9 +868,9 @@ export async function hatch(): Promise<void> {
     keepAlive,
     name,
     remote,
-    daemonOnly,
     restart,
     watch,
+    configValues,
   } = parseArgs();
 
   if (restart && remote !== "local") {
@@ -859,22 +888,29 @@ export async function hatch(): Promise<void> {
   }
 
   if (remote === "local") {
-    await hatchLocal(species, name, daemonOnly, restart, watch, keepAlive);
+    await hatchLocal(species, name, restart, watch, keepAlive, configValues);
     return;
   }
 
   if (remote === "gcp") {
-    await hatchGcp(species, detached, name, buildStartupScript, watchHatching);
+    await hatchGcp(
+      species,
+      detached,
+      name,
+      buildStartupScript,
+      watchHatching,
+      configValues,
+    );
     return;
   }
 
   if (remote === "aws") {
-    await hatchAws(species, detached, name);
+    await hatchAws(species, detached, name, configValues);
     return;
   }
 
   if (remote === "docker") {
-    await hatchDocker(species, detached, name, watch);
+    await hatchDocker(species, detached, name, watch, configValues);
     return;
   }
 

package/src/commands/ps.ts

@@ -4,6 +4,7 @@ import {
   findAssistantByName,
   getActiveAssistant,
   loadAllAssistants,
+  updateServiceGroupVersion,
   type AssistantEntry,
 } from "../lib/assistant-config";
 import { loadGuardianToken } from "../lib/guardian-token";
@@ -424,7 +425,7 @@ async function listAllAssistants(): Promise<void> {
       // hitting the health endpoint. If the PID file is missing or the
       // process isn't running, the assistant is sleeping — skip the
       // network health check to avoid a misleading "unreachable" status.
-      let health: { status: string; detail: string | null };
+      let health: { status: string; detail: string | null; version?: string };
       const resources = a.resources;
       if (a.cloud === "local" && resources) {
         const pid = readPidFile(resources.pidFile);
@@ -451,6 +452,10 @@ async function listAllAssistants(): Promise<void> {
         health = await checkHealth(a.localUrl ?? a.runtimeUrl, token);
       }
 
+      if (health.status === "healthy" && health.version) {
+        updateServiceGroupVersion(a.assistantId, health.version);
+      }
+
       const infoParts = [a.runtimeUrl];
       if (a.cloud) infoParts.push(`cloud: ${a.cloud}`);
       if (a.species) infoParts.push(`species: ${a.species}`);

package/src/commands/restore.ts

@@ -89,28 +89,39 @@ interface PreflightFileEntry {
   action: string;
 }
 
+interface StructuredError {
+  code: string;
+  message: string;
+  path?: string;
+}
+
 interface PreflightResponse {
   can_import: boolean;
-  errors?: string[];
+  validation?: {
+    is_valid: false;
+    errors: StructuredError[];
+  };
   files?: PreflightFileEntry[];
   summary?: {
-    create: number;
-    overwrite: number;
-    unchanged: number;
-    total: number;
+    files_to_create: number;
+    files_to_overwrite: number;
+    files_unchanged: number;
+    total_files: number;
   };
-  conflicts?: string[];
+  conflicts?: StructuredError[];
 }
 
 interface ImportResponse {
   success: boolean;
   reason?: string;
-  errors?: string[];
+  errors?: StructuredError[];
+  message?: string;
   warnings?: string[];
   summary?: {
-    created: number;
-    overwritten: number;
-    skipped: number;
+    total_files: number;
+    files_created: number;
+    files_overwritten: number;
+    files_skipped: number;
     backups_created: number;
   };
 }
@@ -201,30 +212,38 @@ export async function restore(): Promise<void> {
     const result = (await response.json()) as PreflightResponse;
 
     if (!result.can_import) {
-      console.error("Import blocked by validation errors:");
-      for (const err of result.errors ?? []) {
-        console.error(`  - ${err}`);
+      if (result.validation?.errors?.length) {
+        console.error("Import blocked by validation errors:");
+        for (const err of result.validation.errors) {
+          console.error(`  - ${err.message}${err.path ? ` (${err.path})` : ""}`);
+        }
+      }
+      if (result.conflicts?.length) {
+        console.error("Import blocked by conflicts:");
+        for (const conflict of result.conflicts) {
+          console.error(`  - ${conflict.message}${conflict.path ? ` (${conflict.path})` : ""}`);
+        }
       }
       process.exit(1);
     }
 
     // Print summary table
     const summary = result.summary ?? {
-      create: 0,
-      overwrite: 0,
-      unchanged: 0,
-      total: 0,
+      files_to_create: 0,
+      files_to_overwrite: 0,
+      files_unchanged: 0,
+      total_files: 0,
     };
     console.log("Preflight analysis:");
-    console.log(`  Files to create:    ${summary.create}`);
-    console.log(`  Files to overwrite: ${summary.overwrite}`);
-    console.log(`  Files unchanged:    ${summary.unchanged}`);
-    console.log(`  Total:              ${summary.total}`);
+    console.log(`  Files to create:    ${summary.files_to_create}`);
+    console.log(`  Files to overwrite: ${summary.files_to_overwrite}`);
+    console.log(`  Files unchanged:    ${summary.files_unchanged}`);
+    console.log(`  Total:              ${summary.total_files}`);
     console.log("");
 
     const conflicts = result.conflicts ?? [];
     console.log(
-      `Conflicts: ${conflicts.length > 0 ? conflicts.join(", ") : "none"}`,
+      `Conflicts: ${conflicts.length > 0 ? conflicts.map((c) => c.message).join(", ") : "none"}`,
     );
 
     // List individual files with their action
@@ -276,25 +295,26 @@ export async function restore(): Promise<void> {
 
     if (!result.success) {
       console.error(
-        `Error: Import failed — ${result.reason ?? "unknown reason"}`,
+        `Error: Import failed — ${result.message ?? result.reason ?? "unknown reason"}`,
       );
       for (const err of result.errors ?? []) {
-        console.error(`  - ${err}`);
+        console.error(`  - ${err.message}${err.path ? ` (${err.path})` : ""}`);
       }
       process.exit(1);
     }
 
     // Print import report
     const summary = result.summary ?? {
-      created: 0,
-      overwritten: 0,
-      skipped: 0,
+      total_files: 0,
+      files_created: 0,
+      files_overwritten: 0,
+      files_skipped: 0,
       backups_created: 0,
     };
     console.log("✅ Restore complete.");
-    console.log(`  Files created:     ${summary.created}`);
-    console.log(`  Files overwritten: ${summary.overwritten}`);
-    console.log(`  Files skipped:     ${summary.skipped}`);
+    console.log(`  Files created:     ${summary.files_created}`);
+    console.log(`  Files overwritten: ${summary.files_overwritten}`);
+    console.log(`  Files skipped:     ${summary.files_skipped}`);
     console.log(`  Backups created:   ${summary.backups_created}`);
 
     // Print warnings if any

package/src/commands/retire.ts

@@ -1,10 +1,10 @@
 import { spawn } from "child_process";
 import { existsSync, mkdirSync, renameSync, writeFileSync } from "fs";
-import { homedir } from "os";
 import { basename, dirname, join } from "path";
 
 import {
   findAssistantByName,
+  getBaseDir,
   loadAllAssistants,
   removeAssistantEntry,
 } from "../lib/assistant-config";
@@ -109,10 +109,10 @@ async function retireLocal(name: string, entry: AssistantEntry): Promise<void> {
     await stopOrphanedDaemonProcesses();
   }
 
-  // For named instances (instanceDir differs from homedir), archive and
-  // remove the entire instance directory. For the default instance
-  // (instanceDir is homedir), archive only the .vellum subdirectory.
-  const isNamedInstance = resources.instanceDir !== homedir();
+  // For named instances (instanceDir differs from the base directory),
+  // archive and remove the entire instance directory. For the default
+  // instance, archive only the .vellum subdirectory.
+  const isNamedInstance = resources.instanceDir !== getBaseDir();
   const dirToArchive = isNamedInstance ? resources.instanceDir : vellumDir;
 
   // Move the data directory out of the way so the path is immediately available