@vellumai/cli 0.5.6 → 0.5.7

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.7",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

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/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