@vellumai/cli 0.4.56 → 0.4.57

package/AGENTS.md

@@ -6,14 +6,11 @@ The `cli/` package (`@vellumai/cli`) manages the **lifecycle of Vellum assistant
 
 This contrasts with `assistant/src/cli/`, where commands are scoped to a **single running assistant** and operate on its local state (config, memory, contacts, etc.).
 
-## When a command belongs here vs `assistant/src/cli/`
+## Scope
 
-| `cli/` (this package)                           | `assistant/src/cli/`                                |
-| ----------------------------------------------- | --------------------------------------------------- |
-| Operates on or across assistant instances       | Operates within a single assistant's workspace      |
-| Manages lifecycle (create, start, stop, delete) | Manages instance-local state (config, memory, etc.) |
-| Requires specifying which assistant to target   | Implicitly scoped to the running assistant          |
-| Works without an assistant process running      | May require or start the daemon                     |
+Commands here operate on or across **assistant instances** — creating, starting, stopping, connecting to, and deleting them. They require specifying which assistant to target and work without an assistant process running.
+
+For commands scoped to a **single running assistant's** local state (config, memory, contacts), see `assistant/src/cli/AGENTS.md`.
 
 Examples: `hatch`, `wake`, `sleep`, `retire`, `ps`, `ssh` belong here. `config`, `contacts`, `memory` belong in `assistant/src/cli/`.
 
@@ -30,9 +27,7 @@ Commands that act on a specific assistant should accept an assistant name or ID
 
 ## Help Text Standards
 
-Every command must have high-quality `--help` output optimized for AI/LLM
-consumption. Help text is a primary interface — both humans and AI agents read
-it to understand what a command does and how to use it.
+Every command must have high-quality `--help` output. Follow the same standards as `assistant/src/cli/AGENTS.md` § Help Text Standards, adapted for this package's manual argv parsing (no Commander.js).
 
 ### Requirements
 

package/package.json

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

package/src/commands/client.ts

@@ -6,6 +6,7 @@ import {
   loadLatestAssistant,
 } from "../lib/assistant-config";
 import { DAEMON_INTERNAL_ASSISTANT_ID, GATEWAY_PORT, type Species } from "../lib/constants";
+import { loadGuardianToken } from "../lib/guardian-token";
 import { getLocalLanIPv4, getMacLocalHostname } from "../lib/local";
 
 const ANSI = {
@@ -83,7 +84,7 @@ function parseArgs(): ParsedArgs {
 
   let runtimeUrl = entry?.localUrl || entry?.runtimeUrl || FALLBACK_RUNTIME_URL;
   let assistantId = entry?.assistantId || DAEMON_INTERNAL_ASSISTANT_ID;
-  const bearerToken = entry?.bearerToken || undefined;
+  const bearerToken = loadGuardianToken(entry?.assistantId ?? "")?.accessToken ?? undefined;
   const species: Species = (entry?.species as Species) ?? "vellum";
 
   for (let i = 0; i < flagArgs.length; i++) {

package/src/commands/hatch.ts

@@ -383,7 +383,7 @@ export async function watchHatching(
         );
         console.log(`   Monitor with: vel logs ${instanceName}`);
         console.log("");
-        resolve({ success: true, errorContent: lastErrorContent });
+        resolve({ success: false, errorContent: lastErrorContent });
         return;
       }
 
@@ -428,7 +428,7 @@ function watchHatchingDesktop(
           `Timed out after ${formatElapsed(elapsed)}. Instance is still running.`,
         );
         desktopLog(`Monitor with: vel logs ${instanceName}`);
-        resolve({ success: true, errorContent: lastErrorContent });
+        resolve({ success: false, errorContent: lastErrorContent });
         return;
       }
 

package/src/commands/pair.ts

@@ -7,6 +7,8 @@ import { PNG } from "pngjs";
 import { saveAssistantEntry } from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
 import type { Species } from "../lib/constants";
+import { saveGuardianToken } from "../lib/guardian-token";
+import type { GuardianTokenData } from "../lib/guardian-token";
 import { generateInstanceName } from "../lib/random-name";
 
 interface QRPairingPayload {
@@ -168,13 +170,27 @@ export async function pair(): Promise<void> {
     const customEntry: AssistantEntry = {
       assistantId: instanceName,
       runtimeUrl,
-      bearerToken,
       cloud: "custom",
       species,
       hatchedAt: new Date().toISOString(),
     };
     saveAssistantEntry(customEntry);
 
+    if (bearerToken) {
+      const tokenData: GuardianTokenData = {
+        guardianPrincipalId: "",
+        accessToken: bearerToken,
+        accessTokenExpiresAt: "",
+        refreshToken: "",
+        refreshTokenExpiresAt: "",
+        refreshAfter: "",
+        isNew: true,
+        deviceId: getDeviceId(),
+        leasedAt: new Date().toISOString(),
+      };
+      saveGuardianToken(instanceName, tokenData);
+    }
+
     console.log("");
     console.log("Successfully paired with remote assistant!");
     console.log("Instance details:");

package/src/commands/ps.ts

@@ -6,7 +6,9 @@ import {
   loadAllAssistants,
   type AssistantEntry,
 } from "../lib/assistant-config";
+import { loadGuardianToken } from "../lib/guardian-token";
 import { checkHealth, checkManagedHealth } from "../lib/health-check";
+import { dockerResourceNames } from "../lib/docker";
 import {
   classifyProcess,
   detectOrphanedProcesses,
@@ -248,6 +250,73 @@ async function getLocalProcesses(entry: AssistantEntry): Promise<TableRow[]> {
   }));
 }
 
+async function getDockerContainerState(
+  containerName: string,
+): Promise<string | null> {
+  try {
+    const output = await execOutput("docker", [
+      "inspect",
+      "--format",
+      "{{.State.Status}}",
+      containerName,
+    ]);
+    return output.trim() || "unknown";
+  } catch {
+    return null;
+  }
+}
+
+function isLocalProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function getDockerProcesses(entry: AssistantEntry): Promise<TableRow[]> {
+  const res = dockerResourceNames(entry.assistantId);
+
+  const containers: { name: string; containerName: string }[] = [
+    { name: "assistant", containerName: res.assistantContainer },
+    { name: "gateway", containerName: res.gatewayContainer },
+    { name: "credential-executor", containerName: res.cesContainer },
+  ];
+
+  const results = await Promise.all(
+    containers.map(async ({ name, containerName }) => {
+      const state = await getDockerContainerState(containerName);
+      if (!state) {
+        return {
+          name,
+          status: withStatusEmoji("not found"),
+          info: `container ${containerName}`,
+        };
+      }
+      return {
+        name,
+        status: withStatusEmoji(state === "running" ? "running" : state),
+        info: `container ${containerName}`,
+      };
+    }),
+  );
+
+  // Show the file watcher process if the instance was hatched with --watch.
+  const watcherPid =
+    typeof entry.watcherPid === "number" ? entry.watcherPid : null;
+  if (watcherPid !== null) {
+    const alive = isLocalProcessAlive(watcherPid);
+    results.push({
+      name: "file-watcher",
+      status: withStatusEmoji(alive ? "running" : "not running"),
+      info: alive ? `PID ${watcherPid}` : "not detected",
+    });
+  }
+
+  return results;
+}
+
 async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
   const cloud = resolveCloud(entry);
 
@@ -259,6 +328,12 @@ async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
     return;
   }
 
+  if (cloud === "docker") {
+    const rows = await getDockerProcesses(entry);
+    printTable(rows);
+    return;
+  }
+
   let output: string;
   try {
     if (cloud === "gcp") {
@@ -357,12 +432,23 @@ async function listAllAssistants(): Promise<void> {
         if (!alive) {
           health = { status: "sleeping", detail: null };
         } else {
-          health = await checkHealth(a.localUrl ?? a.runtimeUrl, a.bearerToken);
+          const token = loadGuardianToken(a.assistantId)?.accessToken;
+          health = await checkHealth(a.localUrl ?? a.runtimeUrl, token);
+        }
+      } else if (a.cloud === "docker") {
+        const res = dockerResourceNames(a.assistantId);
+        const state = await getDockerContainerState(res.assistantContainer);
+        if (!state || state !== "running") {
+          health = { status: "sleeping", detail: null };
+        } else {
+          const token = loadGuardianToken(a.assistantId)?.accessToken;
+          health = await checkHealth(a.localUrl ?? a.runtimeUrl, token);
         }
       } else if (a.cloud === "vellum") {
         health = await checkManagedHealth(a.runtimeUrl, a.assistantId);
       } else {
-        health = await checkHealth(a.localUrl ?? a.runtimeUrl, a.bearerToken);
+        const token = loadGuardianToken(a.assistantId)?.accessToken;
+        health = await checkHealth(a.localUrl ?? a.runtimeUrl, token);
       }
 
       const infoParts = [a.runtimeUrl];

package/src/commands/upgrade.ts

@@ -0,0 +1,366 @@
+import cliPkg from "../../package.json";
+
+import {
+  findAssistantByName,
+  getActiveAssistant,
+  loadAllAssistants,
+} from "../lib/assistant-config";
+import type { AssistantEntry } from "../lib/assistant-config";
+import {
+  DOCKERHUB_IMAGES,
+  DOCKER_READY_TIMEOUT_MS,
+  GATEWAY_INTERNAL_PORT,
+  dockerResourceNames,
+  startContainers,
+  stopContainers,
+} from "../lib/docker";
+import type { ServiceName } from "../lib/docker";
+import {
+  fetchOrganizationId,
+  getPlatformUrl,
+  readPlatformToken,
+} from "../lib/platform-client";
+import { exec, execOutput } from "../lib/step-runner";
+
+interface UpgradeArgs {
+  name: string | null;
+  version: string | null;
+}
+
+function parseArgs(): UpgradeArgs {
+  const args = process.argv.slice(3);
+  let name: string | null = null;
+  let version: string | null = null;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      console.log("Usage: vellum upgrade [<name>] [options]");
+      console.log("");
+      console.log("Upgrade an assistant to the latest version.");
+      console.log("");
+      console.log("Arguments:");
+      console.log(
+        "  <name>               Name of the assistant to upgrade (default: active or only assistant)",
+      );
+      console.log("");
+      console.log("Options:");
+      console.log(
+        "  --version <version>  Target version to upgrade to (default: latest)",
+      );
+      console.log("");
+      console.log("Examples:");
+      console.log(
+        "  vellum upgrade                              # Upgrade the active assistant to the latest version",
+      );
+      console.log(
+        "  vellum upgrade my-assistant                  # Upgrade a specific assistant by name",
+      );
+      console.log(
+        "  vellum upgrade my-assistant --version v1.2.3 # Upgrade to a specific version",
+      );
+      process.exit(0);
+    } else if (arg === "--version") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("-")) {
+        console.error("Error: --version requires a value");
+        process.exit(1);
+      }
+      version = next;
+      i++;
+    } else if (!arg.startsWith("-")) {
+      name = arg;
+    } else {
+      console.error(`Error: Unknown option '${arg}'.`);
+      process.exit(1);
+    }
+  }
+
+  return { name, version };
+}
+
+function resolveCloud(entry: AssistantEntry): string {
+  if (entry.cloud) {
+    return entry.cloud;
+  }
+  if (entry.project) {
+    return "gcp";
+  }
+  if (entry.sshUser) {
+    return "custom";
+  }
+  return "local";
+}
+
+/**
+ * Resolve which assistant to target for the upgrade command. Priority:
+ * 1. Explicit name argument
+ * 2. Active assistant set via `vellum use`
+ * 3. Sole assistant (when exactly one exists)
+ */
+function resolveTargetAssistant(nameArg: string | null): AssistantEntry {
+  if (nameArg) {
+    const entry = findAssistantByName(nameArg);
+    if (!entry) {
+      console.error(`No assistant found with name '${nameArg}'.`);
+      process.exit(1);
+    }
+    return entry;
+  }
+
+  const active = getActiveAssistant();
+  if (active) {
+    const entry = findAssistantByName(active);
+    if (entry) return entry;
+  }
+
+  const all = loadAllAssistants();
+  if (all.length === 1) return all[0];
+
+  if (all.length === 0) {
+    console.error("No assistants found. Run 'vellum hatch' first.");
+  } else {
+    console.error(
+      "Multiple assistants found. Specify a name or set an active assistant with 'vellum use <name>'.",
+    );
+  }
+  process.exit(1);
+}
+
+/**
+ * Capture environment variables from a running Docker container so they
+ * can be replayed onto the replacement container after upgrade.
+ */
+async function captureContainerEnv(
+  containerName: string,
+): Promise<Record<string, string>> {
+  const captured: Record<string, string> = {};
+  try {
+    const raw = await execOutput("docker", [
+      "inspect",
+      "--format",
+      "{{json .Config.Env}}",
+      containerName,
+    ]);
+    const entries = JSON.parse(raw) as string[];
+    for (const entry of entries) {
+      const eqIdx = entry.indexOf("=");
+      if (eqIdx > 0) {
+        captured[entry.slice(0, eqIdx)] = entry.slice(eqIdx + 1);
+      }
+    }
+  } catch {
+    // Container may not exist or not be inspectable
+  }
+  return captured;
+}
+
+/**
+ * Poll the gateway `/readyz` endpoint until it returns 200 or the timeout
+ * elapses. Returns whether the assistant became ready.
+ */
+async function waitForReady(runtimeUrl: string): Promise<boolean> {
+  const readyUrl = `${runtimeUrl}/readyz`;
+  const start = Date.now();
+
+  while (Date.now() - start < DOCKER_READY_TIMEOUT_MS) {
+    try {
+      const resp = await fetch(readyUrl, {
+        signal: AbortSignal.timeout(5000),
+      });
+      if (resp.ok) {
+        const elapsedSec = ((Date.now() - start) / 1000).toFixed(1);
+        console.log(`Assistant ready after ${elapsedSec}s`);
+        return true;
+      }
+      let detail = "";
+      try {
+        const body = await resp.text();
+        const json = JSON.parse(body);
+        const parts = [json.status];
+        if (json.upstream != null) parts.push(`upstream=${json.upstream}`);
+        detail = ` — ${parts.join(", ")}`;
+      } catch {
+        // ignore parse errors
+      }
+      console.log(`Readiness check: ${resp.status}${detail} (retrying...)`);
+    } catch {
+      // Connection refused / timeout — not up yet
+    }
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+
+  return false;
+}
+
+async function upgradeDocker(
+  entry: AssistantEntry,
+  version: string | null,
+): Promise<void> {
+  const instanceName = entry.assistantId;
+  const res = dockerResourceNames(instanceName);
+
+  const versionTag =
+    version ?? (cliPkg.version ? `v${cliPkg.version}` : "latest");
+  const imageTags: Record<ServiceName, string> = {
+    assistant: `${DOCKERHUB_IMAGES.assistant}:${versionTag}`,
+    "credential-executor": `${DOCKERHUB_IMAGES["credential-executor"]}:${versionTag}`,
+    gateway: `${DOCKERHUB_IMAGES.gateway}:${versionTag}`,
+  };
+
+  console.log(
+    `🔄 Upgrading Docker assistant '${instanceName}' to ${versionTag}...\n`,
+  );
+
+  console.log("📦 Pulling new Docker images...");
+  await exec("docker", ["pull", imageTags.assistant]);
+  await exec("docker", ["pull", imageTags.gateway]);
+  await exec("docker", ["pull", imageTags["credential-executor"]]);
+  console.log("✅ Docker images pulled\n");
+
+  console.log("💾 Capturing existing container environment...");
+  const capturedEnv = await captureContainerEnv(res.assistantContainer);
+  console.log(
+    `   Captured ${Object.keys(capturedEnv).length} env var(s) from ${res.assistantContainer}\n`,
+  );
+
+  console.log("🛑 Stopping existing containers...");
+  await stopContainers(res);
+  console.log("✅ Containers stopped\n");
+
+  // Parse gateway port from entry's runtimeUrl, fall back to default
+  let gatewayPort = GATEWAY_INTERNAL_PORT;
+  try {
+    const parsed = new URL(entry.runtimeUrl);
+    const port = parseInt(parsed.port, 10);
+    if (!isNaN(port)) {
+      gatewayPort = port;
+    }
+  } catch {
+    // use default
+  }
+
+  // Build the set of extra env vars to replay on the new assistant container.
+  // Captured env vars serve as the base; keys already managed by
+  // serviceDockerRunArgs are excluded to avoid duplicates.
+  const envKeysSetByRunArgs = new Set([
+    "VELLUM_ASSISTANT_NAME",
+    "RUNTIME_HTTP_HOST",
+    "PATH",
+  ]);
+  // Only exclude keys that serviceDockerRunArgs will actually set
+  for (const envVar of ["ANTHROPIC_API_KEY", "VELLUM_PLATFORM_URL"]) {
+    if (process.env[envVar]) {
+      envKeysSetByRunArgs.add(envVar);
+    }
+  }
+  const extraAssistantEnv: Record<string, string> = {};
+  for (const [key, value] of Object.entries(capturedEnv)) {
+    if (!envKeysSetByRunArgs.has(key)) {
+      extraAssistantEnv[key] = value;
+    }
+  }
+
+  console.log("🚀 Starting upgraded containers...");
+  await startContainers(
+    {
+      extraAssistantEnv,
+      gatewayPort,
+      imageTags,
+      instanceName,
+      res,
+    },
+    (msg) => console.log(msg),
+  );
+  console.log("✅ Containers started\n");
+
+  console.log("Waiting for assistant to become ready...");
+  const ready = await waitForReady(entry.runtimeUrl);
+  if (ready) {
+    console.log(
+      `\n✅ Docker assistant '${instanceName}' upgraded to ${versionTag}.`,
+    );
+  } else {
+    console.log(
+      `\n⚠️  Containers are running but the assistant did not become ready within the timeout.`,
+    );
+    console.log(`   Check logs with: docker logs -f ${res.assistantContainer}`);
+  }
+}
+
+interface UpgradeApiResponse {
+  detail: string;
+  version: string | null;
+}
+
+async function upgradePlatform(
+  entry: AssistantEntry,
+  version: string | null,
+): Promise<void> {
+  console.log(
+    `🔄 Upgrading platform-hosted assistant '${entry.assistantId}'...\n`,
+  );
+
+  const token = readPlatformToken();
+  if (!token) {
+    console.error(
+      "Error: Not logged in. Run `vellum login --token <token>` first.",
+    );
+    process.exit(1);
+  }
+
+  const orgId = await fetchOrganizationId(token);
+
+  const url = `${getPlatformUrl()}/v1/assistants/upgrade/`;
+  const body: { assistant_id?: string; version?: string } = {
+    assistant_id: entry.assistantId,
+  };
+  if (version) {
+    body.version = version;
+  }
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Session-Token": token,
+      "Vellum-Organization-Id": orgId,
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    console.error(
+      `Error: Platform upgrade failed (${response.status}): ${text}`,
+    );
+    process.exit(1);
+  }
+
+  const result = (await response.json()) as UpgradeApiResponse;
+  console.log(`✅ ${result.detail}`);
+  if (result.version) {
+    console.log(`   Version: ${result.version}`);
+  }
+}
+
+export async function upgrade(): Promise<void> {
+  const { name, version } = parseArgs();
+  const entry = resolveTargetAssistant(name);
+  const cloud = resolveCloud(entry);
+
+  if (cloud === "docker") {
+    await upgradeDocker(entry, version);
+    return;
+  }
+
+  if (cloud === "vellum") {
+    await upgradePlatform(entry, version);
+    return;
+  }
+
+  console.error(
+    `Error: Upgrade is not supported for '${cloud}' assistants. Only 'docker' and 'vellum' assistants can be upgraded via the CLI.`,
+  );
+  process.exit(1);
+}

package/src/index.ts

@@ -13,6 +13,7 @@ import { setup } from "./commands/setup";
 import { sleep } from "./commands/sleep";
 import { ssh } from "./commands/ssh";
 import { tunnel } from "./commands/tunnel";
+import { upgrade } from "./commands/upgrade";
 import { use } from "./commands/use";
 import { wake } from "./commands/wake";
 import {
@@ -21,6 +22,7 @@ import {
   loadLatestAssistant,
   setActiveAssistant,
 } from "./lib/assistant-config";
+import { loadGuardianToken } from "./lib/guardian-token";
 import { checkHealth } from "./lib/health-check";
 
 const commands = {
@@ -37,6 +39,7 @@ const commands = {
   sleep,
   ssh,
   tunnel,
+  upgrade,
   use,
   wake,
   whoami,
@@ -63,6 +66,7 @@ function printHelp(): void {
   console.log("  sleep    Stop the assistant process");
   console.log("  ssh      SSH into a remote assistant instance");
   console.log("  tunnel   Create a tunnel for a locally hosted assistant");
+  console.log("  upgrade  Upgrade an assistant to the latest version");
   console.log("  use      Set the active assistant for commands");
   console.log("  wake     Start the assistant and gateway");
   console.log("  whoami   Show current logged-in user");
@@ -103,7 +107,8 @@ async function tryLaunchClient(): Promise<boolean> {
   const url = entry.localUrl || entry.runtimeUrl;
   if (!url) return false;
 
-  const result = await checkHealth(url, entry.bearerToken);
+  const token = loadGuardianToken(entry.assistantId)?.accessToken;
+  const result = await checkHealth(url, token);
   if (result.status !== "healthy") return false;
 
   // Ensure the resolved assistant is active so client() can find it

package/src/lib/assistant-config.ts

@@ -54,6 +54,8 @@ export interface AssistantEntry {
   volume?: string;
   /** Per-instance resource config. Present for local entries in multi-instance setups. */
   resources?: LocalInstanceResources;
+  /** PID of the file watcher process for docker instances hatched with --watch. */
+  watcherPid?: number;
   [key: string]: unknown;
 }
 

package/src/lib/aws.ts

@@ -529,9 +529,7 @@ export async function hatchAws(
         }
 
         try {
-          const tokenData = await leaseGuardianToken(runtimeUrl, instanceName);
-          awsEntry.bearerToken = tokenData.accessToken;
-          saveAssistantEntry(awsEntry);
+          await leaseGuardianToken(runtimeUrl, instanceName);
         } catch (err) {
           console.warn(
             `\u26a0\ufe0f  Could not lease guardian token: ${err instanceof Error ? err.message : err}`,