@vellumai/cli 0.6.4 → 0.6.5

package/bun.lock

@@ -5,25 +5,25 @@
     "": {
       "name": "@vellumai/cli",
       "dependencies": {
-        "chalk": "^5.6.0",
-        "ink": "^6.7.0",
-        "jsqr": "^1.4.0",
-        "nanoid": "^5.1.7",
-        "pngjs": "^7.0.0",
-        "qrcode-terminal": "^0.12.0",
-        "react": "^19.2.4",
-        "react-devtools-core": "^6.1.2",
+        "chalk": "5.6.2",
+        "ink": "6.8.0",
+        "jsqr": "1.4.0",
+        "nanoid": "5.1.7",
+        "pngjs": "7.0.0",
+        "qrcode-terminal": "0.12.0",
+        "react": "19.2.4",
+        "react-devtools-core": "6.1.5",
       },
       "devDependencies": {
-        "@types/bun": "^1.2.4",
-        "@types/pngjs": "^6.0.5",
-        "@types/qrcode-terminal": "^0.12.2",
-        "@types/react": "^19.2.14",
-        "eslint": "^10.0.0",
-        "knip": "^5.86.0",
-        "prettier": "^3.8.1",
-        "typescript": "^5.9.3",
-        "typescript-eslint": "^8.55.0",
+        "@types/bun": "1.3.11",
+        "@types/pngjs": "6.0.5",
+        "@types/qrcode-terminal": "0.12.2",
+        "@types/react": "19.2.14",
+        "eslint": "10.1.0",
+        "knip": "5.88.1",
+        "prettier": "3.8.1",
+        "typescript": "5.9.3",
+        "typescript-eslint": "8.58.0",
       },
     },
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {
@@ -24,24 +24,24 @@
   "author": "Vellum AI",
   "license": "MIT",
   "dependencies": {
-    "chalk": "^5.6.0",
-    "ink": "^6.7.0",
-    "jsqr": "^1.4.0",
-    "nanoid": "^5.1.7",
-    "pngjs": "^7.0.0",
-    "qrcode-terminal": "^0.12.0",
-    "react": "^19.2.4",
-    "react-devtools-core": "^6.1.2"
+    "chalk": "5.6.2",
+    "ink": "6.8.0",
+    "jsqr": "1.4.0",
+    "nanoid": "5.1.7",
+    "pngjs": "7.0.0",
+    "qrcode-terminal": "0.12.0",
+    "react": "19.2.4",
+    "react-devtools-core": "6.1.5"
   },
   "devDependencies": {
-    "@types/bun": "^1.2.4",
-    "@types/pngjs": "^6.0.5",
-    "@types/qrcode-terminal": "^0.12.2",
-    "@types/react": "^19.2.14",
-    "eslint": "^10.0.0",
-    "knip": "^5.86.0",
-    "prettier": "^3.8.1",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.55.0"
+    "@types/bun": "1.3.11",
+    "@types/pngjs": "6.0.5",
+    "@types/qrcode-terminal": "0.12.2",
+    "@types/react": "19.2.14",
+    "eslint": "10.1.0",
+    "knip": "5.88.1",
+    "prettier": "3.8.1",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.58.0"
   }
 }

package/src/__tests__/guardian-token.test.ts

@@ -7,18 +7,20 @@ import {
   getOrCreatePersistedDeviceId,
   loadGuardianToken,
   saveGuardianToken,
+  seedGuardianTokenFromSiblingEnv,
   type GuardianTokenData,
 } from "../lib/guardian-token.js";
 
 function makeTokenData(suffix: string): GuardianTokenData {
   const now = new Date().toISOString();
+  const oneHourFromNow = new Date(Date.now() + 60 * 60 * 1000).toISOString();
   return {
     guardianPrincipalId: `principal-${suffix}`,
     accessToken: `access-${suffix}`,
-    accessTokenExpiresAt: now,
+    accessTokenExpiresAt: oneHourFromNow,
     refreshToken: `refresh-${suffix}`,
-    refreshTokenExpiresAt: now,
-    refreshAfter: now,
+    refreshTokenExpiresAt: oneHourFromNow,
+    refreshAfter: oneHourFromNow,
     isNew: true,
     deviceId: `device-${suffix}`,
     leasedAt: now,
@@ -169,4 +171,55 @@ describe("guardian-token paths are env-scoped", () => {
     const second = getOrCreatePersistedDeviceId();
     expect(first).toBe(second);
   });
+
+  test("seedGuardianTokenFromSiblingEnv copies a dev token into the current local env", () => {
+    // Write a token under the dev env.
+    process.env.VELLUM_ENVIRONMENT = "dev";
+    saveGuardianToken("alpha", makeTokenData("dev"));
+
+    // Switch to local env — no token present yet.
+    process.env.VELLUM_ENVIRONMENT = "local";
+    expect(loadGuardianToken("alpha")).toBeNull();
+
+    const seeded = seedGuardianTokenFromSiblingEnv("alpha");
+    expect(seeded).toBe(true);
+
+    const localPath = join(
+      tempHome,
+      "vellum-local",
+      "assistants",
+      "alpha",
+      "guardian-token.json",
+    );
+    expect(existsSync(localPath)).toBe(true);
+    const loaded = loadGuardianToken("alpha");
+    expect(loaded).not.toBeNull();
+    expect(loaded!.guardianPrincipalId).toBe("principal-dev");
+
+    // Idempotent — second call is a no-op.
+    expect(seedGuardianTokenFromSiblingEnv("alpha")).toBe(false);
+  });
+
+  test("seedGuardianTokenFromSiblingEnv returns false when no sibling token exists", () => {
+    process.env.VELLUM_ENVIRONMENT = "local";
+    expect(seedGuardianTokenFromSiblingEnv("nonexistent")).toBe(false);
+    expect(loadGuardianToken("nonexistent")).toBeNull();
+  });
+
+  test("seedGuardianTokenFromSiblingEnv does not overwrite an existing token", () => {
+    // Token already present in the current env.
+    process.env.VELLUM_ENVIRONMENT = "local";
+    saveGuardianToken("alpha", makeTokenData("local"));
+
+    // And a different sibling token in dev.
+    process.env.VELLUM_ENVIRONMENT = "dev";
+    saveGuardianToken("alpha", makeTokenData("dev"));
+
+    // Back to local — seed should no-op because a token is already present.
+    process.env.VELLUM_ENVIRONMENT = "local";
+    expect(seedGuardianTokenFromSiblingEnv("alpha")).toBe(false);
+    expect(loadGuardianToken("alpha")!.guardianPrincipalId).toBe(
+      "principal-local",
+    );
+  });
 });

package/src/__tests__/llm-provider-env-var-parity.test.ts

@@ -0,0 +1,64 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import {
+  LLM_PROVIDER_ENV_VAR_NAMES,
+  SEARCH_PROVIDER_ENV_VAR_NAMES,
+} from "../shared/provider-env-vars.js";
+
+/**
+ * Drift guard for the CLI-side LLM provider env-var mirror.
+ *
+ * `cli/src/shared/provider-env-vars.ts` hardcodes the LLM env-var names so the
+ * CLI doesn't need to import the assistant's `PROVIDER_CATALOG` (no CLI →
+ * assistant cross-package imports exist). This test pulls the catalog JSON at
+ * `meta/llm-provider-catalog.json` — which is kept in sync with
+ * `PROVIDER_CATALOG` by `assistant/src/__tests__/llm-catalog-parity.test.ts` —
+ * and asserts the CLI's mirror matches the catalog's `envVar` entries.
+ *
+ * It also asserts the search-provider mirror matches `meta/provider-env-vars.json`.
+ */
+
+const REPO_ROOT = join(import.meta.dir, "..", "..", "..");
+
+interface LlmCatalogEntry {
+  id: string;
+  envVar?: string;
+}
+
+interface LlmCatalog {
+  version: number;
+  providers: LlmCatalogEntry[];
+}
+
+interface SearchProviderRegistry {
+  version: number;
+  providers: Record<string, string>;
+}
+
+function loadLlmCatalog(): LlmCatalog {
+  const path = join(REPO_ROOT, "meta", "llm-provider-catalog.json");
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+
+function loadSearchProviderRegistry(): SearchProviderRegistry {
+  const path = join(REPO_ROOT, "meta", "provider-env-vars.json");
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+
+describe("CLI provider env-var parity", () => {
+  test("LLM_PROVIDER_ENV_VAR_NAMES matches meta/llm-provider-catalog.json entries with envVar", () => {
+    const catalog = loadLlmCatalog();
+    const expected: Record<string, string> = {};
+    for (const provider of catalog.providers) {
+      if (provider.envVar) expected[provider.id] = provider.envVar;
+    }
+    expect(LLM_PROVIDER_ENV_VAR_NAMES).toEqual(expected);
+  });
+
+  test("SEARCH_PROVIDER_ENV_VAR_NAMES matches meta/provider-env-vars.json", () => {
+    const registry = loadSearchProviderRegistry();
+    expect(SEARCH_PROVIDER_ENV_VAR_NAMES).toEqual(registry.providers);
+  });
+});

package/src/__tests__/multi-local.test.ts

@@ -159,6 +159,36 @@ describe("multi-local", () => {
       }
     });
 
+    test("allocation picks env-specific port bases for non-prod envs", async () => {
+      // Each non-prod env sits in its own 1000-port window (see
+      // environments/seeds.ts). Hatching under VELLUM_ENVIRONMENT=dev should
+      // produce ports in the dev block (18000+), not the production defaults.
+      const prevEnv = process.env.VELLUM_ENVIRONMENT;
+      const prevXdg = process.env.XDG_DATA_HOME;
+      const xdgDataHome = mkdtempSync(join(tmpdir(), "cli-multi-xdg-ports-"));
+      process.env.VELLUM_ENVIRONMENT = "dev";
+      process.env.XDG_DATA_HOME = xdgDataHome;
+      try {
+        const res = await allocateLocalResources("dev-a");
+        expect(res.daemonPort).toBe(18000);
+        expect(res.gatewayPort).toBe(18100);
+        expect(res.qdrantPort).toBe(18200);
+        expect(res.cesPort).toBe(18300);
+      } finally {
+        if (prevEnv !== undefined) {
+          process.env.VELLUM_ENVIRONMENT = prevEnv;
+        } else {
+          delete process.env.VELLUM_ENVIRONMENT;
+        }
+        if (prevXdg !== undefined) {
+          process.env.XDG_DATA_HOME = prevXdg;
+        } else {
+          delete process.env.XDG_DATA_HOME;
+        }
+        rmSync(xdgDataHome, { recursive: true, force: true });
+      }
+    });
+
     test("second instance gets distinct ports and dir when first instance is saved", async () => {
       // GIVEN a first local assistant already exists in the lockfile
       saveAssistantEntry(makeEntry("instance-a"));

package/src/commands/exec.ts

@@ -0,0 +1,186 @@
+import { spawn } from "child_process";
+
+import {
+  findAssistantByName,
+  loadLatestAssistant,
+  resolveCloud,
+} from "../lib/assistant-config";
+import { dockerResourceNames } from "../lib/docker";
+import type { ServiceName } from "../lib/docker";
+import { execAppleContainer } from "../lib/exec-apple-container";
+import { sshAppleContainer } from "../lib/ssh-apple-container";
+
+const SERVICE_ALIASES: Record<string, ServiceName> = {
+  assistant: "assistant",
+  "vellum-assistant": "assistant",
+  gateway: "gateway",
+  "vellum-gateway": "gateway",
+  "credential-executor": "credential-executor",
+  "vellum-credential-executor": "credential-executor",
+};
+
+function normalizeService(raw: string): ServiceName {
+  const normalized = SERVICE_ALIASES[raw];
+  if (!normalized) {
+    console.error(
+      `Unknown service '${raw}'. Valid services: assistant, gateway, credential-executor`,
+    );
+    process.exit(1);
+  }
+  return normalized;
+}
+
+function resolveDockerContainer(
+  instanceName: string,
+  service: ServiceName,
+): string {
+  const res = dockerResourceNames(instanceName);
+  switch (service) {
+    case "assistant":
+      return res.assistantContainer;
+    case "gateway":
+      return res.gatewayContainer;
+    case "credential-executor":
+      return res.cesContainer;
+  }
+}
+
+export async function exec(): Promise<void> {
+  const rawArgs = process.argv.slice(3);
+
+  // Only check for help flags before the -- separator so that
+  // `vellum exec -- curl --help` passes through correctly.
+  const dashDashIndex = rawArgs.indexOf("--");
+  const preArgs =
+    dashDashIndex === -1 ? rawArgs : rawArgs.slice(0, dashDashIndex);
+
+  if (
+    preArgs.includes("--help") ||
+    preArgs.includes("-h") ||
+    rawArgs.length === 0
+  ) {
+    console.log(
+      "Usage: vellum exec [<name>] [--service <svc>] [-it] -- <command...>",
+    );
+    console.log("");
+    console.log("Execute a command inside an assistant's container.");
+    console.log("");
+    console.log("Arguments:");
+    console.log(
+      "  <name>              Name of the assistant (defaults to active)",
+    );
+    console.log(
+      "  <command...>        Command and arguments to run (after --)",
+    );
+    console.log("");
+    console.log("Options:");
+    console.log(
+      "  --service <svc>     Target service (default: assistant)",
+    );
+    console.log(
+      "  -it                 Interactive mode with TTY (like docker exec -it)",
+    );
+    console.log("");
+    console.log("Services:");
+    console.log("  assistant (or vellum-assistant)");
+    console.log("  gateway (or vellum-gateway)");
+    console.log("  credential-executor (or vellum-credential-executor)");
+    console.log("");
+    console.log("Examples:");
+    console.log("  vellum exec -- ls -la /workspace");
+    console.log("  vellum exec -- cat /workspace/NOW.md");
+    console.log("  vellum exec -it -- /bin/bash");
+    console.log(
+      "  vellum exec --service gateway -- cat /tmp/gateway.log",
+    );
+    process.exit(0);
+  }
+
+  if (dashDashIndex === -1) {
+    console.error(
+      "Error: missing '--' separator before command.\n" +
+        "Usage: vellum exec [<name>] -- <command...>",
+    );
+    process.exit(1);
+  }
+
+  const command = rawArgs.slice(dashDashIndex + 1);
+
+  if (command.length === 0) {
+    console.error("Error: no command specified after '--'.");
+    process.exit(1);
+  }
+
+  let nameArg: string | undefined;
+  let serviceRaw = "assistant";
+  let interactive = false;
+
+  for (let i = 0; i < preArgs.length; i++) {
+    if (preArgs[i] === "--service" && preArgs[i + 1]) {
+      serviceRaw = preArgs[++i];
+    } else if (preArgs[i] === "-it" || preArgs[i] === "-ti") {
+      interactive = true;
+    } else if (!preArgs[i].startsWith("-")) {
+      nameArg = preArgs[i];
+    }
+  }
+
+  const service = normalizeService(serviceRaw);
+
+  const entry = nameArg
+    ? findAssistantByName(nameArg)
+    : loadLatestAssistant();
+
+  if (!entry) {
+    if (nameArg) {
+      console.error(`No assistant instance found with name '${nameArg}'.`);
+    } else {
+      console.error("No assistant instance found. Run `vellum hatch` first.");
+    }
+    process.exit(1);
+  }
+
+  const cloud = resolveCloud(entry);
+
+  if (cloud === "local") {
+    console.error(
+      "Cannot exec into a local assistant — it runs directly on this machine.",
+    );
+    process.exit(1);
+  }
+
+  if (cloud === "apple-container") {
+    const fullServiceName = `vellum-${service}`;
+    if (interactive) {
+      await sshAppleContainer(entry, command, fullServiceName);
+    } else {
+      await execAppleContainer(entry, command, fullServiceName);
+    }
+    return;
+  }
+
+  if (cloud === "docker") {
+    const container = resolveDockerContainer(entry.assistantId, service);
+    const dockerArgs = interactive
+      ? ["exec", "-it", container, ...command]
+      : ["exec", container, ...command];
+
+    const child = spawn("docker", dockerArgs, { stdio: "inherit" });
+    await new Promise<void>((resolve, reject) => {
+      child.on("close", (code) => {
+        if (code === 0) resolve();
+        else {
+          process.exitCode = code ?? 1;
+          resolve();
+        }
+      });
+      child.on("error", reject);
+    });
+    return;
+  }
+
+  console.error(
+    `Error: 'vellum exec' is not supported for ${cloud} instances.`,
+  );
+  process.exit(1);
+}

package/src/commands/login.ts

@@ -15,7 +15,9 @@ import {
   fetchOrganizationId,
   getPlatformUrl,
   injectCredentialsIntoAssistant,
+  readGatewayCredential,
   readPlatformToken,
+  reprovisionAssistantApiKey,
   savePlatformToken,
 } from "../lib/platform-client";
 
@@ -193,12 +195,41 @@ export async function login(): Promise<void> {
           `Registered assistant: ${registration.assistant.name} (${registration.assistant.id})`,
         );
 
+        // Resolve the API key to inject, mirroring the macOS app's
+        // LocalAssistantBootstrapService 3-step flow:
+        // 1. Use fresh key from registration (first-time only)
+        // 2. Use existing key from the daemon's credential store
+        // 3. Reprovision (rotate) as a last resort — this revokes the
+        //    old key server-side, so we only do it when the gateway
+        //    confirms no key exists (not when it's merely unreachable).
+        let assistantApiKey = registration.assistant_api_key;
+        if (!assistantApiKey) {
+          const cached = await readGatewayCredential(
+            entry.runtimeUrl,
+            "vellum:assistant_api_key",
+            entry.bearerToken,
+          );
+          if (cached.value) {
+            assistantApiKey = cached.value;
+          } else if (!cached.unreachable) {
+            console.log("No API key available locally — reprovisioning...");
+            const reprovision = await reprovisionAssistantApiKey(
+              token,
+              orgId,
+              clientInstallationId,
+              entry.assistantId,
+              "cli",
+            );
+            assistantApiKey = reprovision.provisioning.assistant_api_key;
+          }
+        }
+
         // Inject credentials into the running assistant via the gateway,
         // mirroring the desktop app's LocalAssistantBootstrapService flow.
         const allInjected = await injectCredentialsIntoAssistant({
           gatewayUrl: entry.runtimeUrl,
           bearerToken: entry.bearerToken,
-          assistantApiKey: registration.assistant_api_key,
+          assistantApiKey,
           platformAssistantId: registration.assistant.id,
           platformBaseUrl: getPlatformUrl(),
           organizationId: orgId,

package/src/commands/ssh.ts

@@ -6,7 +6,7 @@ import {
 } from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
 import { dockerResourceNames } from "../lib/docker";
-import { sshAppleContainer } from "./ssh-apple-container";
+import { sshAppleContainer } from "../lib/ssh-apple-container";
 
 const SSH_OPTS = [
   "-o",

package/src/commands/teleport.ts

@@ -27,6 +27,8 @@ import {
   platformImportBundleFromGcs,
   platformPollImportStatus,
   ensureSelfHostedLocalRegistration,
+  readGatewayCredential,
+  reprovisionAssistantApiKey,
   injectCredentialsIntoAssistant,
   fetchCurrentUser,
   fetchOrganizationId,
@@ -1135,10 +1137,35 @@ async function tryInjectPlatformCredentials(
       "cli",
     );
 
+    // Resolve the API key: 1) fresh from registration, 2) existing from
+    // daemon credential store, 3) reprovision as last resort (revokes old key).
+    // Only reprovision when the gateway confirms no key exists — not when
+    // the gateway is merely unreachable (would revoke without injecting).
+    let assistantApiKey = registration.assistant_api_key;
+    if (!assistantApiKey) {
+      const cached = await readGatewayCredential(
+        entry.runtimeUrl,
+        "vellum:assistant_api_key",
+        entry.bearerToken,
+      );
+      if (cached.value) {
+        assistantApiKey = cached.value;
+      } else if (!cached.unreachable) {
+        const reprovision = await reprovisionAssistantApiKey(
+          token,
+          orgId,
+          clientInstallationId,
+          entry.assistantId,
+          "cli",
+        );
+        assistantApiKey = reprovision.provisioning.assistant_api_key;
+      }
+    }
+
     const allInjected = await injectCredentialsIntoAssistant({
       gatewayUrl: entry.runtimeUrl,
       bearerToken: entry.bearerToken,
-      assistantApiKey: registration.assistant_api_key,
+      assistantApiKey,
       platformAssistantId: registration.assistant.id,
       platformBaseUrl: getPlatformUrl(),
       organizationId: orgId,

package/src/commands/wake.ts

@@ -6,6 +6,7 @@ import {
   saveAssistantEntry,
 } from "../lib/assistant-config.js";
 import { dockerResourceNames, wakeContainers } from "../lib/docker.js";
+import { seedGuardianTokenFromSiblingEnv } from "../lib/guardian-token.js";
 import { isProcessAlive, stopProcessByPidFile } from "../lib/process";
 import {
   generateLocalSigningKey,
@@ -182,6 +183,16 @@ export async function wake(): Promise<void> {
     }
   }
 
+  // Self-heal the guardian token when the current environment's config dir
+  // is missing it. Hatch cross-writes the lockfile across env dirs but the
+  // guardian token is only persisted under the hatch-time env, so a desktop
+  // app built under a different VELLUM_ENVIRONMENT can't find a bearer and
+  // cascades into 401 → auth-rate-limit → 429. A sibling env copy is cheap
+  // and strictly additive.
+  if (seedGuardianTokenFromSiblingEnv(entry.assistantId)) {
+    console.log("   Seeded guardian token from sibling environment.");
+  }
+
   // Auto-start ngrok if webhook integrations (e.g. Telegram) are configured.
   // Scope BASE_DATA_DIR to the woken instance so ngrok reads the correct
   // instance config, then restore on any exit path.

package/src/index.ts

@@ -5,6 +5,7 @@ import { backup } from "./commands/backup";
 import { clean } from "./commands/clean";
 import { client } from "./commands/client";
 import { events } from "./commands/events";
+import { exec } from "./commands/exec";
 import { hatch } from "./commands/hatch";
 import { login, logout, whoami } from "./commands/login";
 import { logs } from "./commands/logs";
@@ -37,6 +38,7 @@ const commands = {
   clean,
   client,
   events,
+  exec,
   hatch,
   login,
   logout,
@@ -69,6 +71,7 @@ function printHelp(): void {
   console.log("  clean    Kill orphaned vellum processes");
   console.log("  client   Connect to a hatched assistant");
   console.log("  events   Stream events from a running assistant");
+  console.log("  exec     Execute a command inside an assistant's container");
   console.log("  hatch    Create a new assistant instance");
   console.log("  logs     View logs from an assistant instance");
   console.log("  login    Log in to the Vellum platform");