@vellumai/cli 0.5.6 → 0.5.8

package/knip.json

@@ -3,7 +3,9 @@
     "src/**/*.test.ts",
     "src/**/__tests__/**/*.ts",
     "src/adapters/openclaw-http-server.ts",
-    "src/lib/version-compat.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.6",
+  "version": "0.5.8",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/commands/backup.ts

@@ -1,21 +1,16 @@
 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`;
-}
+import {
+  readPlatformToken,
+  fetchOrganizationId,
+  platformInitiateExport,
+  platformPollExportStatus,
+  platformDownloadExport,
+} from "../lib/platform-client.js";
 
 export async function backup(): Promise<void> {
   const args = process.argv.slice(3);
@@ -67,6 +62,14 @@ export async function backup(): Promise<void> {
     process.exit(1);
   }
 
+  // Detect topology and route platform assistants through Django export
+  const cloud =
+    entry.cloud || (entry.project ? "gcp" : entry.sshUser ? "custom" : "local");
+  if (cloud === "vellum") {
+    await backupPlatform(name, outputArg);
+    return;
+  }
+
   // Obtain an auth token
   let accessToken: string;
   const tokenData = loadGuardianToken(entry.assistantId);
@@ -104,6 +107,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.");
@@ -149,3 +179,112 @@ export async function backup(): Promise<void> {
     console.log(`Manifest SHA-256: ${manifestSha}`);
   }
 }
+
+// ---------------------------------------------------------------------------
+// Platform (Vellum-hosted) backup via Django async migration export
+// ---------------------------------------------------------------------------
+
+async function backupPlatform(name: string, outputArg?: string): Promise<void> {
+  // Step 1 — Authenticate
+  const token = readPlatformToken();
+  if (!token) {
+    console.error("Not logged in. Run 'vellum login' first.");
+    process.exit(1);
+  }
+
+  let orgId: string;
+  try {
+    orgId = await fetchOrganizationId(token);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("401") || msg.includes("403")) {
+      console.error("Authentication failed. Run 'vellum login' to refresh.");
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  // Step 2 — Initiate export job
+  let jobId: string;
+  try {
+    const result = await platformInitiateExport(token, orgId, "CLI backup");
+    jobId = result.jobId;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("401") || msg.includes("403")) {
+      console.error("Authentication failed. Run 'vellum login' to refresh.");
+      process.exit(1);
+    }
+    if (msg.includes("429")) {
+      console.error(
+        "Too many export requests. Please wait before trying again.",
+      );
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  console.log(`Export started (job ${jobId})...`);
+
+  // Step 3 — Poll for completion
+  const POLL_INTERVAL_MS = 2_000;
+  const TIMEOUT_MS = 5 * 60 * 1_000; // 5 minutes
+  const deadline = Date.now() + TIMEOUT_MS;
+  let downloadUrl: string | undefined;
+
+  while (Date.now() < deadline) {
+    let status: { status: string; downloadUrl?: string; error?: string };
+    try {
+      status = await platformPollExportStatus(jobId, token, orgId);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      // Let non-transient errors (e.g. 404 "job not found") propagate immediately
+      if (msg.includes("not found")) {
+        throw err;
+      }
+      console.warn(`Polling failed, retrying... (${msg})`);
+      await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+      continue;
+    }
+
+    if (status.status === "complete") {
+      downloadUrl = status.downloadUrl;
+      break;
+    }
+
+    if (status.status === "failed") {
+      console.error(`Export failed: ${status.error ?? "unknown error"}`);
+      process.exit(1);
+    }
+
+    // Still in progress — wait and retry
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+  }
+
+  if (!downloadUrl) {
+    console.error("Export timed out after 5 minutes.");
+    process.exit(1);
+  }
+
+  // Step 4 — Download bundle
+  const isoTimestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const outputPath =
+    outputArg || join(getBackupsDir(), `${name}-${isoTimestamp}.vbundle`);
+
+  mkdirSync(dirname(outputPath), { recursive: true });
+
+  const response = await platformDownloadExport(downloadUrl);
+  const arrayBuffer = await response.arrayBuffer();
+  const data = new Uint8Array(arrayBuffer);
+
+  writeFileSync(outputPath, data);
+
+  // Step 5 — Print success
+  console.log(`Backup saved to ${outputPath}`);
+  console.log(`Size: ${formatSize(data.byteLength)}`);
+
+  const manifestSha = response.headers.get("X-Vbundle-Manifest-Sha256");
+  if (manifestSha) {
+    console.log(`Manifest SHA-256: ${manifestSha}`);
+  }
+}

package/src/commands/hatch.ts

@@ -1,3 +1,4 @@
+import { randomBytes } from "crypto";
 import {
   appendFileSync,
   existsSync,
@@ -39,12 +40,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 +102,9 @@ export async function buildStartupScript(
   providerApiKeys: Record<string, string>,
   instanceName: string,
   cloud: RemoteHost,
-): Promise<string> {
-  const platformUrl = process.env.VELLUM_PLATFORM_URL ?? "https://vellum.ai";
+  configValues: Record<string, string> = {},
+): Promise<{ script: string; laptopBootstrapSecret: string }> {
+  const platformUrl = getPlatformUrl();
   const logPath =
     cloud === "custom"
       ? "/tmp/vellum-startup.log"
@@ -112,25 +116,57 @@ export async function buildStartupScript(
   const ownershipFixup = buildOwnershipFixup();
 
   if (species === "openclaw") {
-    return await buildOpenclawStartupScript(
+    const script = await buildOpenclawStartupScript(
       sshUser,
       providerApiKeys,
       timestampRedirect,
       userSetup,
       ownershipFixup,
     );
+    return { script, laptopBootstrapSecret: "" };
   }
 
+  // Generate a bootstrap secret for the laptop that initiated this remote
+  // hatch. The startup script exports it as GUARDIAN_BOOTSTRAP_SECRET so
+  // that when `vellum hatch --remote docker` runs on the VM, the docker
+  // hatch detects the pre-set env var and appends its own secret.
+  const laptopBootstrapSecret = randomBytes(32).toString("hex");
+
   // Build bash lines that set each provider API key as a shell variable
   // and corresponding dotenv lines for the env file.
-  const envSetLines = Object.entries(providerApiKeys)
+  // Include the laptop bootstrap secret so that when the remote runs
+  // `vellum hatch --remote docker`, the docker hatch detects the pre-set
+  // env var and appends its own secret for multi-secret guardian init.
+  const allEnvEntries: Record<string, string> = {
+    ...providerApiKeys,
+    GUARDIAN_BOOTSTRAP_SECRET: laptopBootstrapSecret,
+  };
+  const envSetLines = Object.entries(allEnvEntries)
     .map(([envVar, value]) => `${envVar}=${value}`)
     .join("\n");
   const dotenvLines = Object.keys(providerApiKeys)
     .map((envVar) => `${envVar}=\$${envVar}`)
     .join("\n");
 
-  return `#!/bin/bash
+  // 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 {
+    laptopBootstrapSecret,
+    script: `#!/bin/bash
 set -e
 
 ${timestampRedirect}
@@ -146,16 +182,19 @@ RUNTIME_HTTP_PORT=7821
 DOTENV_EOF
 
 ${ownershipFixup}
-
+${configWriteBlock}
+export GUARDIAN_BOOTSTRAP_SECRET
 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)"
 chmod +x ${INSTALL_SCRIPT_REMOTE_PATH}
 echo "Running install script..."
 source ${INSTALL_SCRIPT_REMOTE_PATH}
-`;
+`,
+  };
 }
 
 const DEFAULT_REMOTE: RemoteHost = "local";
@@ -166,9 +205,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 +217,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 +238,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 +247,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 +285,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 +318,9 @@ function parseArgs(): HatchArgs {
     keepAlive,
     name,
     remote,
-    daemonOnly,
     restart,
     watch,
+    configValues,
   };
 }
 
@@ -574,10 +628,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 +763,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 +813,7 @@ async function hatchLocal(
     serviceGroupVersion: cliPkg.version ? `v${cliPkg.version}` : undefined,
     resources,
   };
-  if (!daemonOnly && !restart) {
+  if (!restart) {
     saveAssistantEntry(localEntry);
     setActiveAssistant(instanceName);
     syncConfigToLockfile();
@@ -780,12 +832,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 +887,9 @@ export async function hatch(): Promise<void> {
     keepAlive,
     name,
     remote,
-    daemonOnly,
     restart,
     watch,
+    configValues,
   } = parseArgs();
 
   if (restart && remote !== "local") {
@@ -859,22 +907,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;
   }