@vellumai/cli 0.4.48 → 0.4.50

package/README.md

@@ -62,21 +62,19 @@ vellum hatch [species] [options]
 
 #### Remote Targets
 
-- **`local`** -- Starts the local assistant and local gateway. Gateway source resolution order is: `VELLUM_GATEWAY_DIR` override, repo source tree, then installed `@vellumai/vellum-gateway` package.
+- **`local`** -- Starts the local assistant and local gateway. Gateway source resolution order is: repo source tree, then installed `@vellumai/vellum-gateway` package.
 - **`gcp`** -- Creates a GCP Compute Engine VM (`e2-standard-4`: 4 vCPUs, 16 GB) with a startup script that bootstraps the assistant. Requires `gcloud` authentication and `GCP_PROJECT` / `GCP_DEFAULT_ZONE` environment variables.
 - **`aws`** -- Provisions an AWS instance.
 - **`custom`** -- Provisions on an arbitrary SSH host. Set `VELLUM_CUSTOM_HOST` (e.g. `user@hostname`) to specify the target.
 
 #### Environment Variables
 
-| Variable                  | Required For | Description                                                                                        |
-| ------------------------- | ------------ | -------------------------------------------------------------------------------------------------- |
-| `ANTHROPIC_API_KEY`       | All          | Anthropic API key passed to the assistant runtime.                                                 |
-| `GCP_PROJECT`             | `gcp`        | GCP project ID. Falls back to the active `gcloud` project.                                         |
-| `GCP_DEFAULT_ZONE`        | `gcp`        | GCP zone for the compute instance.                                                                 |
-| `VELLUM_CUSTOM_HOST`      | `custom`     | SSH host in `user@hostname` format.                                                                |
-| `VELLUM_GATEWAY_DIR`      | `local`      | Optional absolute path to a local gateway source directory to run instead of the packaged gateway. |
-| `INGRESS_PUBLIC_BASE_URL` | `local`      | Optional fallback public ingress URL when `ingress.publicBaseUrl` is not set in workspace config.  |
+| Variable             | Required For | Description                                                |
+| -------------------- | ------------ | ---------------------------------------------------------- |
+| `ANTHROPIC_API_KEY`  | All          | Anthropic API key passed to the assistant runtime.         |
+| `GCP_PROJECT`        | `gcp`        | GCP project ID. Falls back to the active `gcloud` project. |
+| `GCP_DEFAULT_ZONE`   | `gcp`        | GCP zone for the compute instance.                         |
+| `VELLUM_CUSTOM_HOST` | `custom`     | SSH host in `user@hostname` format.                        |
 
 #### Examples
 

package/package.json

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

package/src/adapters/install.sh

@@ -229,14 +229,14 @@ symlink_vellum() {
     symlink_cli "assistant"
 }
 
-# Write a small sourceable env file to ~/.config/vellum/env so callers can
-# pick up PATH changes without restarting their shell:
+# Append PATH setup to ~/.config/vellum/env so callers can pick up PATH
+# changes without restarting their shell:
 #   curl -fsSL https://assistant.vellum.ai/install.sh | bash && . ~/.config/vellum/env
 write_env_file() {
     local env_dir="${XDG_CONFIG_HOME:-$HOME/.config}/vellum"
     local env_file="$env_dir/env"
     mkdir -p "$env_dir"
-    cat > "$env_file" <<'ENVEOF'
+    cat >> "$env_file" <<'ENVEOF'
 export BUN_INSTALL="$HOME/.bun"
 case ":$PATH:" in
   *":$BUN_INSTALL/bin:"*) ;;
@@ -278,8 +278,8 @@ main() {
         info "Note: 'assistant' command may require opening a new terminal session"
     fi
 
-    # Write a sourceable env file so the quickstart one-liner can pick up
-    # PATH changes in the caller's shell:
+    # Append PATH config to the env file so the quickstart one-liner can
+    # pick up PATH changes in the caller's shell:
     #   curl ... | bash && . ~/.config/vellum/env
     write_env_file
 
@@ -292,7 +292,7 @@ main() {
     info "Running vellum hatch..."
     printf "\n"
     if [ -n "${VELLUM_SSH_USER:-}" ] && [ "$(id -u)" = "0" ]; then
-        su - "$VELLUM_SSH_USER" -c "set -a; [ -f \"\$HOME/.vellum/.env\" ] && . \"\$HOME/.vellum/.env\"; set +a; export PATH=\"$HOME/.bun/bin:\$PATH\"; vellum hatch"
+        su - "$VELLUM_SSH_USER" -c "set -a; [ -f \"\$HOME/.config/vellum/env\" ] && . \"\$HOME/.config/vellum/env\"; set +a; export PATH=\"$HOME/.bun/bin:\$PATH\"; vellum hatch"
     else
         vellum hatch
     fi

package/src/commands/clean.ts

@@ -6,7 +6,9 @@ export async function clean(): Promise<void> {
   if (args.includes("--help") || args.includes("-h")) {
     console.log("Usage: vellum clean");
     console.log("");
-    console.log("Kill all orphaned vellum processes that are not tracked by any assistant.");
+    console.log(
+      "Kill all orphaned vellum processes that are not tracked by any assistant.",
+    );
     process.exit(0);
   }
 
@@ -17,18 +19,21 @@ export async function clean(): Promise<void> {
     return;
   }
 
-  console.log(`Found ${orphans.length} orphaned process${orphans.length === 1 ? "" : "es"}.\n`);
+  console.log(
+    `Found ${orphans.length} orphaned process${orphans.length === 1 ? "" : "es"}.\n`,
+  );
 
   let killed = 0;
   for (const orphan of orphans) {
     const pid = parseInt(orphan.pid, 10);
-    const stopped = await stopProcess(pid, `${orphan.name} (PID ${orphan.pid})`);
+    const stopped = await stopProcess(
+      pid,
+      `${orphan.name} (PID ${orphan.pid})`,
+    );
     if (stopped) {
       killed++;
     }
   }
 
-  console.log(
-    `\nCleaned up ${killed} process${killed === 1 ? "" : "es"}.`,
-  );
+  console.log(`\nCleaned up ${killed} process${killed === 1 ? "" : "es"}.`);
 }

package/src/commands/client.ts

@@ -60,9 +60,7 @@ function parseArgs(): ParsedArgs {
     }
   } else {
     const hasExplicitUrl =
-      process.env.RUNTIME_URL ||
-      flagArgs.includes("--url") ||
-      flagArgs.includes("-u");
+      flagArgs.includes("--url") || flagArgs.includes("-u");
     const active = getActiveAssistant();
     if (active) {
       entry = findAssistantByName(active);
@@ -84,15 +82,9 @@ function parseArgs(): ParsedArgs {
     }
   }
 
-  let runtimeUrl =
-    process.env.RUNTIME_URL ||
-    entry?.localUrl ||
-    entry?.runtimeUrl ||
-    FALLBACK_RUNTIME_URL;
-  let assistantId =
-    process.env.ASSISTANT_ID || entry?.assistantId || FALLBACK_ASSISTANT_ID;
-  const bearerToken =
-    process.env.RUNTIME_PROXY_BEARER_TOKEN || entry?.bearerToken || undefined;
+  let runtimeUrl = entry?.localUrl || entry?.runtimeUrl || FALLBACK_RUNTIME_URL;
+  let assistantId = entry?.assistantId || FALLBACK_ASSISTANT_ID;
+  const bearerToken = entry?.bearerToken || undefined;
   const species: Species = (entry?.species as Species) ?? "vellum";
 
   for (let i = 0; i < flagArgs.length; i++) {
@@ -177,7 +169,7 @@ ${ANSI.bold}OPTIONS:${ANSI.reset}
 
 ${ANSI.bold}DEFAULTS:${ANSI.reset}
     Reads from ~/.vellum.lock.json (created by vellum hatch).
-    Override with flags above or env vars RUNTIME_URL / ASSISTANT_ID.
+    Override with flags above.
 
 ${ANSI.bold}EXAMPLES:${ANSI.reset}
     vellum client

package/src/commands/hatch.ts

@@ -103,7 +103,7 @@ export async function buildStartupScript(
   cloud: RemoteHost,
 ): Promise<string> {
   const platformUrl =
-    process.env.VELLUM_ASSISTANT_PLATFORM_URL ?? "https://assistant.vellum.ai";
+    process.env.VELLUM_PLATFORM_URL ?? "https://assistant.vellum.ai";
   const logPath =
     cloud === "custom"
       ? "/tmp/vellum-startup.log"
@@ -133,28 +133,13 @@ ${timestampRedirect}
 trap 'EXIT_CODE=\$?; if [ \$EXIT_CODE -ne 0 ]; then echo "Startup script failed with exit code \$EXIT_CODE at line \$LINENO" > ${errorPath}; echo "Last 20 log lines:" >> ${errorPath}; tail -20 ${logPath} >> ${errorPath} 2>/dev/null || true; fi' EXIT
 ${userSetup}
 ANTHROPIC_API_KEY=${anthropicApiKey}
-GATEWAY_RUNTIME_PROXY_ENABLED=true
-RUNTIME_PROXY_BEARER_TOKEN=${bearerToken}
 VELLUM_ASSISTANT_NAME=${instanceName}
-VELLUM_CLOUD=${cloud}
-mkdir -p "\$HOME/.vellum"
-cat > "\$HOME/.vellum/.env" << DOTENV_EOF
+mkdir -p "\$HOME/.config/vellum"
+cat > "\$HOME/.config/vellum/env" << DOTENV_EOF
 ANTHROPIC_API_KEY=\$ANTHROPIC_API_KEY
-GATEWAY_RUNTIME_PROXY_ENABLED=\$GATEWAY_RUNTIME_PROXY_ENABLED
-RUNTIME_PROXY_BEARER_TOKEN=\$RUNTIME_PROXY_BEARER_TOKEN
 RUNTIME_HTTP_PORT=7821
-VELLUM_CLOUD=\$VELLUM_CLOUD
 DOTENV_EOF
 
-mkdir -p "\$HOME/.vellum/workspace"
-cat > "\$HOME/.vellum/workspace/config.json" << CONFIG_EOF
-{
-  "logFile": {
-    "dir": "\$HOME/.vellum/workspace/data/logs"
-  }
-}
-CONFIG_EOF
-
 ${ownershipFixup}
 
 export VELLUM_SSH_USER="\$SSH_USER"
@@ -743,7 +728,10 @@ async function hatchLocal(
         `🧹 Found ${orphans.length} orphaned process${orphans.length === 1 ? "" : "es"} — cleaning up...`,
       );
       for (const orphan of orphans) {
-        await stopProcess(parseInt(orphan.pid, 10), `${orphan.name} (PID ${orphan.pid})`);
+        await stopProcess(
+          parseInt(orphan.pid, 10),
+          `${orphan.name} (PID ${orphan.pid})`,
+        );
       }
     }
   }
@@ -776,7 +764,7 @@ async function hatchLocal(
 
   let runtimeUrl: string;
   try {
-    runtimeUrl = await startGateway(instanceName, watch, resources);
+    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.

package/src/commands/ps.ts

@@ -6,7 +6,7 @@ import {
   loadAllAssistants,
   type AssistantEntry,
 } from "../lib/assistant-config";
-import { checkHealth } from "../lib/health-check";
+import { checkHealth, checkManagedHealth } from "../lib/health-check";
 import {
   classifyProcess,
   detectOrphanedProcesses,
@@ -150,7 +150,13 @@ async function detectProcess(spec: ProcessSpec): Promise<DetectedProcess> {
   const pids = await pgrepExact(spec.pgrepName);
   if (pids.length > 0) {
     const watch = await isWatchMode(pids[0]);
-    return { name: spec.name, pid: pids[0], port: spec.port, running: true, watch };
+    return {
+      name: spec.name,
+      pid: pids[0],
+      port: spec.port,
+      running: true,
+      watch,
+    };
   }
 
   // Tier 2: TCP port probe (skip for processes without a port)
@@ -171,10 +177,22 @@ async function detectProcess(spec: ProcessSpec): Promise<DetectedProcess> {
   const filePid = readPidFile(spec.pidFile);
   if (filePid && isProcessAlive(filePid)) {
     const watch = await isWatchMode(filePid);
-    return { name: spec.name, pid: filePid, port: spec.port, running: true, watch };
+    return {
+      name: spec.name,
+      pid: filePid,
+      port: spec.port,
+      running: true,
+      watch,
+    };
   }
 
-  return { name: spec.name, pid: null, port: spec.port, running: false, watch: false };
+  return {
+    name: spec.name,
+    pid: null,
+    port: spec.port,
+    running: false,
+    watch: false,
+  };
 }
 
 function formatDetectionInfo(proc: DetectedProcess): string {
@@ -341,6 +359,8 @@ async function listAllAssistants(): Promise<void> {
         } else {
           health = await checkHealth(a.localUrl ?? a.runtimeUrl, a.bearerToken);
         }
+      } else if (a.cloud === "vellum") {
+        health = await checkManagedHealth(a.runtimeUrl, a.assistantId);
       } else {
         health = await checkHealth(a.localUrl ?? a.runtimeUrl, a.bearerToken);
       }

package/src/commands/recover.ts

@@ -69,7 +69,7 @@ export async function recover(): Promise<void> {
   // 7. Start daemon + gateway (same as wake)
   await startLocalDaemon(false, entry.resources);
   if (!process.env.VELLUM_DESKTOP_APP) {
-    await startGateway(undefined, false, entry.resources);
+    await startGateway(false, entry.resources);
   }
 
   console.log(`✅ Recovered assistant '${name}'.`);

package/src/commands/retire.ts

@@ -9,10 +9,7 @@ import {
   removeAssistantEntry,
 } from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
-import {
-  getPlatformUrl,
-  readPlatformToken,
-} from "../lib/platform-client";
+import { getPlatformUrl, readPlatformToken } from "../lib/platform-client";
 import { retireInstance as retireAwsInstance } from "../lib/aws";
 import { retireDocker } from "../lib/docker";
 import { retireInstance as retireGcpInstance } from "../lib/gcp";
@@ -83,7 +80,7 @@ async function retireLocal(name: string, entry: AssistantEntry): Promise<void> {
   const daemonStopped = await stopProcessByPidFile(daemonPidFile, "daemon");
 
   // Stop gateway via PID file — use a longer timeout because the gateway has a
-  // configurable drain window (GATEWAY_SHUTDOWN_DRAIN_MS, default 5s) before it exits.
+  // drain window (5s) before it exits.
   const gatewayPidFile = join(vellumDir, "gateway.pid");
   await stopProcessByPidFile(gatewayPidFile, "gateway", undefined, 7000);
 

package/src/commands/setup.ts

@@ -0,0 +1,172 @@
+import { createInterface } from "readline";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+function getVellumDir(): string {
+  const base = process.env.BASE_DATA_DIR?.trim() || homedir();
+  return join(base, ".vellum");
+}
+
+function getEnvFilePath(): string {
+  return join(getVellumDir(), ".env");
+}
+
+function readEnvFile(): Record<string, string> {
+  const envPath = getEnvFilePath();
+  const vars: Record<string, string> = {};
+  if (!existsSync(envPath)) return vars;
+
+  const content = readFileSync(envPath, "utf-8");
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eqIdx = trimmed.indexOf("=");
+    if (eqIdx === -1) continue;
+    const key = trimmed.slice(0, eqIdx).trim();
+    const value = trimmed.slice(eqIdx + 1).trim();
+    vars[key] = value;
+  }
+  return vars;
+}
+
+function writeEnvFile(vars: Record<string, string>): void {
+  const envPath = getEnvFilePath();
+  const dir = dirname(envPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const lines = Object.entries(vars).map(([k, v]) => `${k}=${v}`);
+  writeFileSync(envPath, lines.join("\n") + "\n", { mode: 0o600 });
+}
+
+async function promptMasked(prompt: string): Promise<string> {
+  return new Promise((resolve) => {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    // Disable echoing by writing the prompt manually and intercepting keystrokes
+    process.stdout.write(prompt);
+
+    const stdin = process.stdin;
+    const wasRaw = stdin.isRaw;
+    if (stdin.isTTY) {
+      stdin.setRawMode(true);
+    }
+
+    let input = "";
+    const onData = (key: Buffer): void => {
+      const char = key.toString("utf-8");
+
+      if (char === "\r" || char === "\n") {
+        // Enter pressed
+        stdin.removeListener("data", onData);
+        if (stdin.isTTY) {
+          stdin.setRawMode(wasRaw ?? false);
+        }
+        process.stdout.write("\n");
+        rl.close();
+        resolve(input);
+      } else if (char === "\u0003") {
+        // Ctrl+C
+        process.stdout.write("\n");
+        process.exit(1);
+      } else if (char === "\u007F" || char === "\b") {
+        // Backspace
+        if (input.length > 0) {
+          input = input.slice(0, -1);
+          process.stdout.write("\b \b");
+        }
+      } else if (char.length === 1 && char >= " ") {
+        input += char;
+        process.stdout.write("*");
+      }
+    };
+
+    stdin.on("data", onData);
+  });
+}
+
+async function validateAnthropicKey(apiKey: string): Promise<boolean> {
+  try {
+    const resp = await fetch("https://api.anthropic.com/v1/models", {
+      headers: {
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+      },
+      signal: AbortSignal.timeout(10_000),
+    });
+    return resp.ok;
+  } catch {
+    return false;
+  }
+}
+
+export async function setup(): Promise<void> {
+  const args = process.argv.slice(3);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum setup");
+    console.log("");
+    console.log("Interactive wizard to configure API keys.");
+    console.log(
+      "Keys are validated against their APIs and saved to <BASE_DATA_DIR>/.vellum/.env.",
+    );
+    process.exit(0);
+  }
+
+  console.log("Vellum Setup");
+  console.log("============\n");
+
+  const existingVars = readEnvFile();
+  const hasExistingKey = !!existingVars.ANTHROPIC_API_KEY;
+
+  if (hasExistingKey) {
+    const masked =
+      existingVars.ANTHROPIC_API_KEY.slice(0, 7) +
+      "..." +
+      existingVars.ANTHROPIC_API_KEY.slice(-4);
+    console.log(`Anthropic API key is already configured (${masked}).`);
+
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    const answer = await new Promise<string>((resolve) => {
+      rl.question("Overwrite? [y/N] ", resolve);
+    });
+    rl.close();
+
+    if (answer.trim().toLowerCase() !== "y") {
+      console.log("\nSetup complete. No changes made.");
+      return;
+    }
+    console.log("");
+  }
+
+  const apiKey = await promptMasked(
+    "Enter your Anthropic API key (sk-ant-...): ",
+  );
+
+  if (!apiKey.trim()) {
+    console.error("Error: API key cannot be empty.");
+    process.exit(1);
+  }
+
+  console.log("Validating key...");
+  const valid = await validateAnthropicKey(apiKey.trim());
+
+  if (!valid) {
+    console.error(
+      "Error: Invalid API key. Could not authenticate with the Anthropic API.",
+    );
+    process.exit(1);
+  }
+
+  existingVars.ANTHROPIC_API_KEY = apiKey.trim();
+  writeEnvFile(existingVars);
+
+  console.log(`\nAPI key saved to ${getEnvFilePath()}`);
+  console.log("Setup complete.");
+}

package/src/commands/sleep.ts

@@ -120,7 +120,7 @@ export async function sleep(): Promise<void> {
   }
 
   // Stop gateway — use a longer timeout because the gateway has a configurable
-  // drain window (GATEWAY_SHUTDOWN_DRAIN_MS, default 5s) before it exits.
+  // drain window (5s) before it exits.
   const gatewayStopped = await stopProcessByPidFile(
     gatewayPidFile,
     "gateway",

package/src/commands/wake.ts

@@ -87,12 +87,12 @@ export async function wake(): Promise<void> {
           `Gateway running (pid ${pid}) — restarting in watch mode...`,
         );
         await stopProcessByPidFile(gatewayPidFile, "gateway");
-        await startGateway(undefined, watch, resources);
+        await startGateway(watch, resources);
       } else {
         console.log(`Gateway already running (pid ${pid}).`);
       }
     } else {
-      await startGateway(undefined, watch, resources);
+      await startGateway(watch, resources);
     }
   }