@vellumai/cli 0.4.48 → 0.4.50

package/src/components/TextInput.tsx

@@ -6,6 +6,9 @@ interface TextInputProps {
   value: string;
   onChange: (value: string) => void;
   onSubmit?: (value: string) => void;
+  onHistoryUp?: () => void;
+  onHistoryDown?: () => void;
+  completionCommands?: string[];
   focus?: boolean;
   placeholder?: string;
 }
@@ -14,12 +17,19 @@ function TextInput({
   value,
   onChange,
   onSubmit,
+  onHistoryUp,
+  onHistoryDown,
+  completionCommands,
   focus = true,
   placeholder = "",
 }: TextInputProps): ReactElement {
   const cursorOffsetRef = useRef(value.length);
   const valueRef = useRef(value);
 
+  // Tab completion state
+  const [completionIndex, setCompletionIndex] = useState(-1);
+  const [completionMatches, setCompletionMatches] = useState<string[]>([]);
+
   valueRef.current = value;
 
   if (cursorOffsetRef.current > value.length) {
@@ -28,40 +38,162 @@ function TextInput({
 
   const [, setRenderTick] = useState(0);
 
+  const clearCompletion = () => {
+    setCompletionIndex(-1);
+    setCompletionMatches([]);
+  };
+
+  const getMatches = (text: string): string[] => {
+    if (!completionCommands || !text.startsWith("/") || text.includes(" ")) {
+      return [];
+    }
+    const prefix = text.toLowerCase();
+    return completionCommands.filter((cmd) =>
+      cmd.toLowerCase().startsWith(prefix),
+    );
+  };
+
   useInput(
     (input, key) => {
-      if (
-        key.upArrow ||
-        key.downArrow ||
-        (key.ctrl && input === "c") ||
-        key.tab ||
-        (key.shift && key.tab)
-      ) {
+      if (key.upArrow && !key.shift && !key.meta) {
+        clearCompletion();
+        onHistoryUp?.();
+        cursorOffsetRef.current = Infinity;
+        setRenderTick((t) => t + 1);
+        return;
+      }
+      if (key.downArrow && !key.shift && !key.meta) {
+        clearCompletion();
+        onHistoryDown?.();
+        cursorOffsetRef.current = Infinity;
+        setRenderTick((t) => t + 1);
+        return;
+      }
+      if (key.ctrl && input === "c") {
+        return;
+      }
+
+      // Tab completion handling
+      if (key.tab) {
+        const currentValue = valueRef.current;
+
+        if (completionMatches.length > 0) {
+          // Already in completion mode — cycle through matches
+          const direction = key.shift ? -1 : 1;
+          const nextIndex =
+            (completionIndex + direction + completionMatches.length) %
+            completionMatches.length;
+          setCompletionIndex(nextIndex);
+
+          const completed = completionMatches[nextIndex]!;
+          valueRef.current = completed;
+          cursorOffsetRef.current = completed.length;
+          onChange(completed);
+          setRenderTick((t) => t + 1);
+          return;
+        }
+
+        // Start completion mode
+        const matches = getMatches(currentValue);
+        if (matches.length === 1) {
+          // Single match — accept immediately with trailing space
+          const completed = matches[0]! + " ";
+          valueRef.current = completed;
+          cursorOffsetRef.current = completed.length;
+          onChange(completed);
+          setRenderTick((t) => t + 1);
+        } else if (matches.length > 1) {
+          setCompletionMatches(matches);
+          const idx = key.shift ? matches.length - 1 : 0;
+          setCompletionIndex(idx);
+
+          const completed = matches[idx]!;
+          valueRef.current = completed;
+          cursorOffsetRef.current = completed.length;
+          onChange(completed);
+          setRenderTick((t) => t + 1);
+        }
         return;
       }
 
+      // Escape cancels completion mode
+      if (key.escape) {
+        if (completionMatches.length > 0) {
+          clearCompletion();
+          setRenderTick((t) => t + 1);
+          return;
+        }
+      }
+
+      // Enter accepts completion and submits
       if (key.return) {
-        onSubmit?.(valueRef.current);
+        if (completionMatches.length > 0) {
+          // Append trailing space so the command is recognized by handleInput
+          const completed = valueRef.current + " ";
+          valueRef.current = completed;
+          cursorOffsetRef.current = completed.length;
+          onChange(completed);
+          clearCompletion();
+          onSubmit?.(completed);
+        } else {
+          clearCompletion();
+          onSubmit?.(valueRef.current);
+        }
         return;
       }
 
+      // Space accepts completion, then continues editing
+      if (input === " " && completionMatches.length > 0) {
+        clearCompletion();
+        // Let the space be inserted normally below
+      } else if (completionMatches.length > 0) {
+        // Any other key exits completion mode
+        clearCompletion();
+      }
+
       const currentValue = valueRef.current;
       const currentOffset = cursorOffsetRef.current;
       let nextValue = currentValue;
       let nextOffset = currentOffset;
 
-      if (key.leftArrow) {
+      if (key.ctrl && input === "a") {
+        // Ctrl+A — move cursor to start
+        nextOffset = 0;
+      } else if (key.ctrl && input === "e") {
+        // Ctrl+E — move cursor to end
+        nextOffset = currentValue.length;
+      } else if (key.ctrl && input === "u") {
+        // Ctrl+U — clear line before cursor
+        nextValue = currentValue.slice(currentOffset);
+        nextOffset = 0;
+      } else if (key.ctrl && input === "k") {
+        // Ctrl+K — kill from cursor to end
+        nextValue = currentValue.slice(0, currentOffset);
+      } else if (key.ctrl && input === "w") {
+        // Ctrl+W — delete word backwards (handles tabs and other whitespace)
+        const before = currentValue.slice(0, currentOffset);
+        // Skip trailing whitespace, then find previous whitespace boundary
+        const match = before.match(/^(.*\s)?\S+\s*$/);
+        const wordStart = match?.[1]?.length ?? 0;
+        nextValue =
+          currentValue.slice(0, wordStart) + currentValue.slice(currentOffset);
+        nextOffset = wordStart;
+      } else if (key.leftArrow) {
         nextOffset = Math.max(0, currentOffset - 1);
       } else if (key.rightArrow) {
         nextOffset = Math.min(currentValue.length, currentOffset + 1);
       } else if (key.backspace || key.delete) {
         if (currentOffset > 0) {
-          nextValue = currentValue.slice(0, currentOffset - 1) + currentValue.slice(currentOffset);
+          nextValue =
+            currentValue.slice(0, currentOffset - 1) +
+            currentValue.slice(currentOffset);
           nextOffset = currentOffset - 1;
         }
       } else {
         nextValue =
-          currentValue.slice(0, currentOffset) + input + currentValue.slice(currentOffset);
+          currentValue.slice(0, currentOffset) +
+          input +
+          currentValue.slice(currentOffset);
         nextOffset = currentOffset + input.length;
       }
 
@@ -78,6 +210,14 @@ function TextInput({
   );
 
   const cursorOffset = cursorOffsetRef.current;
+  const isCompleting = completionMatches.length > 0;
+
+  // Build completion hint text
+  let completionHint = "";
+  if (isCompleting && completionMatches.length > 1) {
+    completionHint = ` [${completionIndex + 1}/${completionMatches.length}]`;
+  }
+
   let renderedValue: string;
   let renderedPlaceholder: string | undefined;
 
@@ -97,6 +237,9 @@ function TextInput({
       if (cursorOffset === value.length) {
         renderedValue += chalk.inverse(" ");
       }
+      if (completionHint) {
+        renderedValue += chalk.grey(completionHint);
+      }
     } else {
       renderedValue = chalk.inverse(" ");
     }
@@ -107,7 +250,11 @@ function TextInput({
 
   return (
     <Text>
-      {placeholder ? (value.length > 0 ? renderedValue : renderedPlaceholder) : renderedValue}
+      {placeholder
+        ? value.length > 0
+          ? renderedValue
+          : renderedPlaceholder
+        : renderedValue}
     </Text>
   );
 }

package/src/index.ts

@@ -9,11 +9,19 @@ import { pair } from "./commands/pair";
 import { ps } from "./commands/ps";
 import { recover } from "./commands/recover";
 import { retire } from "./commands/retire";
+import { setup } from "./commands/setup";
 import { sleep } from "./commands/sleep";
 import { ssh } from "./commands/ssh";
 import { tunnel } from "./commands/tunnel";
 import { use } from "./commands/use";
 import { wake } from "./commands/wake";
+import {
+  getActiveAssistant,
+  findAssistantByName,
+  loadLatestAssistant,
+  setActiveAssistant,
+} from "./lib/assistant-config";
+import { checkHealth } from "./lib/health-check";
 
 const commands = {
   clean,
@@ -25,6 +33,7 @@ const commands = {
   ps,
   recover,
   retire,
+  setup,
   sleep,
   ssh,
   tunnel,
@@ -35,36 +44,106 @@ const commands = {
 
 type CommandName = keyof typeof commands;
 
+function printHelp(): void {
+  console.log("Usage: vellum <command> [options]");
+  console.log("");
+  console.log("Commands:");
+  console.log("  clean    Kill orphaned vellum processes");
+  console.log("  client   Connect to a hatched assistant");
+  console.log("  hatch    Create a new assistant instance");
+  console.log("  login    Log in to the Vellum platform");
+  console.log("  logout   Log out of the Vellum platform");
+  console.log("  pair     Pair with a remote assistant via QR code");
+  console.log(
+    "  ps       List assistants (or processes for a specific assistant)",
+  );
+  console.log("  recover  Restore a previously retired local assistant");
+  console.log("  retire   Delete an assistant instance");
+  console.log("  setup    Configure API keys interactively");
+  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("  use      Set the active assistant for commands");
+  console.log("  wake     Start the assistant and gateway");
+  console.log("  whoami   Show current logged-in user");
+  console.log("");
+  console.log("Options:");
+  console.log(
+    "  --no-color, --plain   Disable colored output (honors NO_COLOR env)",
+  );
+  console.log("  --version, -v         Show version");
+  console.log("  --help, -h            Show this help");
+}
+
+/**
+ * Check for --no-color / --plain flags and set NO_COLOR env var
+ * before any terminal capability detection runs.
+ *
+ * Per https://no-color.org/, setting NO_COLOR to any non-empty value
+ * signals that color output should be suppressed.
+ */
+function applyNoColorFlags(argv: string[]): void {
+  if (argv.includes("--no-color") || argv.includes("--plain")) {
+    process.env.NO_COLOR = "1";
+  }
+}
+
+/**
+ * If a running assistant is detected, launch the TUI client and return true.
+ * Otherwise return false so the caller can fall back to help text.
+ */
+async function tryLaunchClient(): Promise<boolean> {
+  const activeName = getActiveAssistant();
+  const entry = activeName
+    ? findAssistantByName(activeName)
+    : loadLatestAssistant();
+
+  if (!entry) return false;
+
+  const url = entry.localUrl || entry.runtimeUrl;
+  if (!url) return false;
+
+  const result = await checkHealth(url, entry.bearerToken);
+  if (result.status !== "healthy") return false;
+
+  // Ensure the resolved assistant is active so client() can find it
+  // (client() independently reads the active assistant from config).
+  setActiveAssistant(String(entry.assistantId));
+
+  await client();
+  return true;
+}
+
 async function main() {
   const args = process.argv.slice(2);
-  const commandName = args[0];
+
+  // Must run before any command or terminal-capabilities usage
+  applyNoColorFlags(args);
+
+  // Global flags that are not command names
+  const GLOBAL_FLAGS = new Set(["--no-color", "--plain"]);
+  const commandName = args.find((a) => !GLOBAL_FLAGS.has(a));
+
+  // Strip global flags from process.argv so subcommands that parse
+  // process.argv.slice(3) don't see them as positional arguments.
+  const filteredArgs = args.filter((a) => !GLOBAL_FLAGS.has(a));
+  process.argv = [...process.argv.slice(0, 2), ...filteredArgs];
 
   if (commandName === "--version" || commandName === "-v") {
     console.log(`@vellumai/cli v${cliPkg.version}`);
     process.exit(0);
   }
 
-  if (!commandName || commandName === "--help" || commandName === "-h") {
-    console.log("Usage: vellum <command> [options]");
-    console.log("");
-    console.log("Commands:");
-    console.log("  clean    Kill orphaned vellum processes");
-    console.log("  client   Connect to a hatched assistant");
-    console.log("  hatch    Create a new assistant instance");
-    console.log("  login    Log in to the Vellum platform");
-    console.log("  logout   Log out of the Vellum platform");
-    console.log("  pair     Pair with a remote assistant via QR code");
-    console.log(
-      "  ps       List assistants (or processes for a specific assistant)",
-    );
-    console.log("  recover  Restore a previously retired local assistant");
-    console.log("  retire   Delete an assistant instance");
-    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("  use      Set the active assistant for commands");
-    console.log("  wake     Start the assistant and gateway");
-    console.log("  whoami   Show current logged-in user");
+  if (commandName === "--help" || commandName === "-h") {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (!commandName) {
+    const launched = await tryLaunchClient();
+    if (!launched) {
+      printHelp();
+    }
     process.exit(0);
   }
 

package/src/lib/assistant-config.ts

@@ -190,11 +190,7 @@ export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
       mutated = true;
     }
     if (typeof res.pidFile !== "string") {
-      res.pidFile = join(
-        res.instanceDir as string,
-        ".vellum",
-        "vellum.pid",
-      );
+      res.pidFile = join(res.instanceDir as string, ".vellum", "vellum.pid");
       mutated = true;
     }
   }
@@ -363,7 +359,6 @@ export async function allocateLocalResources(
   if (existingLocals.length === 0) {
     const home = homedir();
     const vellumDir = join(home, ".vellum");
-    mkdirSync(vellumDir, { recursive: true });
     return {
       instanceDir: home,
       daemonPort: DEFAULT_DAEMON_PORT,

package/src/lib/constants.ts

@@ -8,7 +8,13 @@ export const DEFAULT_DAEMON_PORT = 7821;
 export const DEFAULT_GATEWAY_PORT = 7830;
 export const DEFAULT_QDRANT_PORT = 6333;
 
-export const VALID_REMOTE_HOSTS = ["local", "gcp", "aws", "docker", "custom"] as const;
+export const VALID_REMOTE_HOSTS = [
+  "local",
+  "gcp",
+  "aws",
+  "docker",
+  "custom",
+] as const;
 export type RemoteHost = (typeof VALID_REMOTE_HOSTS)[number];
 export const VALID_SPECIES = ["openclaw", "vellum"] as const;
 export type Species = (typeof VALID_SPECIES)[number];

package/src/lib/docker.ts

@@ -7,7 +7,6 @@ import { saveAssistantEntry, setActiveAssistant } from "./assistant-config";
 import type { AssistantEntry } from "./assistant-config";
 import { DEFAULT_GATEWAY_PORT } from "./constants";
 import type { Species } from "./constants";
-import { discoverPublicUrl } from "./local";
 import { generateRandomSuffix } from "./random-name";
 import { exec, execOutput } from "./step-runner";
 import {
@@ -19,6 +18,102 @@ import {
 
 const _require = createRequire(import.meta.url);
 
+/**
+ * Checks whether the `docker` CLI and daemon are available on the system.
+ * Installs Colima and Docker via Homebrew if the CLI is missing, and starts
+ * Colima if the Docker daemon is not reachable.
+ */
+async function ensureDockerInstalled(): Promise<void> {
+  let installed = false;
+  try {
+    await execOutput("docker", ["--version"]);
+    installed = true;
+  } catch {
+    // docker CLI not found — install it
+  }
+
+  if (!installed) {
+    // Check whether Homebrew is available before attempting to use it.
+    let hasBrew = false;
+    try {
+      await execOutput("brew", ["--version"]);
+      hasBrew = true;
+    } catch {
+      // brew not found
+    }
+
+    if (!hasBrew) {
+      console.log("🍺 Homebrew not found. Installing Homebrew...");
+      try {
+        await exec("bash", [
+          "-c",
+          'NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"',
+        ]);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(
+          `Failed to install Homebrew. Please install Docker manually from https://www.docker.com/products/docker-desktop/\n${message}`,
+        );
+      }
+
+      // Homebrew on Apple Silicon installs to /opt/homebrew; add it to PATH
+      // so subsequent brew/colima/docker invocations work in this session.
+      if (!process.env.PATH?.includes("/opt/homebrew")) {
+        process.env.PATH = `/opt/homebrew/bin:/opt/homebrew/sbin:${process.env.PATH}`;
+      }
+    }
+
+    console.log("🐳 Docker not found. Installing via Homebrew...");
+    try {
+      await exec("brew", ["install", "colima", "docker"]);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `Failed to install Docker via Homebrew. Please install Docker manually.\n${message}`,
+      );
+    }
+
+    try {
+      await execOutput("docker", ["--version"]);
+    } catch {
+      throw new Error(
+        "Docker was installed but is still not available on PATH. " +
+          "You may need to restart your terminal.",
+      );
+    }
+  }
+
+  // Verify the Docker daemon is reachable; start Colima if it isn't
+  try {
+    await exec("docker", ["info"]);
+  } catch {
+    let hasColima = false;
+    try {
+      await execOutput("colima", ["version"]);
+      hasColima = true;
+    } catch {
+      // colima not found
+    }
+
+    if (!hasColima) {
+      throw new Error(
+        "Docker daemon is not running and Colima is not installed.\n" +
+          "Please start Docker Desktop, or install Colima with 'brew install colima' and run 'colima start'.",
+      );
+    }
+
+    console.log("🚀 Docker daemon not running. Starting Colima...");
+    try {
+      await exec("colima", ["start"]);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `Failed to start Colima. Please run 'colima start' manually.\n${message}`,
+      );
+    }
+  }
+}
+
 interface DockerRoot {
   /** Directory to use as the Docker build context */
   root: string;
@@ -180,6 +275,8 @@ export async function hatchDocker(
 ): Promise<void> {
   resetLogFile("hatch.log");
 
+  await ensureDockerInstalled();
+
   let repoRoot: string;
   let dockerfileDir: string;
   try {
@@ -251,12 +348,7 @@ export async function hatchDocker(
   ];
 
   // Pass through environment variables the assistant needs
-  for (const envVar of [
-    "ANTHROPIC_API_KEY",
-    "GATEWAY_RUNTIME_PROXY_ENABLED",
-    "RUNTIME_PROXY_BEARER_TOKEN",
-    "VELLUM_ASSISTANT_PLATFORM_URL",
-  ]) {
+  for (const envVar of ["ANTHROPIC_API_KEY", "VELLUM_PLATFORM_URL"]) {
     if (process.env[envVar]) {
       runArgs.push("-e", `${envVar}=${process.env[envVar]}`);
     }
@@ -278,8 +370,10 @@ export async function hatchDocker(
     );
   }
 
-  const publicUrl = await discoverPublicUrl(gatewayPort);
-  const runtimeUrl = publicUrl || `http://localhost:${gatewayPort}`;
+  // Docker containers bind to 0.0.0.0 so localhost always works. Skip
+  // mDNS/LAN discovery — the .local hostname often fails to resolve on the
+  // host machine itself (mDNS is designed for cross-device discovery).
+  const runtimeUrl = `http://localhost:${gatewayPort}`;
   const dockerEntry: AssistantEntry = {
     assistantId: instanceName,
     runtimeUrl,

package/src/lib/doctor-client.ts

@@ -1,4 +1,4 @@
-const DOCTOR_URL = process.env.DOCTOR_URL || "https://doctor.vellum.ai";
+const DOCTOR_URL = "https://doctor.vellum.ai";
 
 export type ProgressPhase =
   | "invoking_prompt"

package/src/lib/gcp.ts

@@ -637,7 +637,7 @@ export async function hatchGcp(
           species === "vellum" &&
           (await checkCurlFailure(instanceName, project, zone, account))
         ) {
-          const installScriptUrl = `${process.env.VELLUM_ASSISTANT_PLATFORM_URL ?? "https://assistant.vellum.ai"}/install.sh`;
+          const installScriptUrl = `${process.env.VELLUM_PLATFORM_URL ?? "https://assistant.vellum.ai"}/install.sh`;
           console.log(
             `\ud83d\udd04 Detected install script curl failure for ${installScriptUrl}, attempting recovery...`,
           );

package/src/lib/health-check.ts

@@ -10,6 +10,93 @@ export interface HealthCheckResult {
   detail: string | null;
 }
 
+interface OrgListResponse {
+  results: { id: string }[];
+}
+
+async function fetchOrganizationId(
+  platformUrl: string,
+  token: string,
+): Promise<{ orgId: string } | { error: string }> {
+  try {
+    const response = await fetch(`${platformUrl}/v1/organizations/`, {
+      headers: { "X-Session-Token": token },
+    });
+    if (!response.ok) {
+      return { error: `org lookup failed (${response.status})` };
+    }
+    const body = (await response.json()) as OrgListResponse;
+    const orgId = body.results?.[0]?.id;
+    if (!orgId) {
+      return { error: "no organization found" };
+    }
+    return { orgId };
+  } catch {
+    return { error: "org lookup unreachable" };
+  }
+}
+
+export async function checkManagedHealth(
+  runtimeUrl: string,
+  assistantId: string,
+): Promise<HealthCheckResult> {
+  const { readPlatformToken } = await import("./platform-client.js");
+  const token = readPlatformToken();
+  if (!token) {
+    return {
+      status: "error (auth)",
+      detail: "not logged in — run `vellum login`",
+    };
+  }
+
+  const orgResult = await fetchOrganizationId(runtimeUrl, token);
+  if ("error" in orgResult) {
+    return {
+      status: "error (auth)",
+      detail: orgResult.error,
+    };
+  }
+  const { orgId } = orgResult;
+
+  try {
+    const url = `${runtimeUrl}/v1/assistants/${encodeURIComponent(assistantId)}/healthz/`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(
+      () => controller.abort(),
+      HEALTH_CHECK_TIMEOUT_MS,
+    );
+
+    const headers: Record<string, string> = {
+      "X-Session-Token": token,
+      "Vellum-Organization-Id": orgId,
+    };
+
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      return { status: `error (${response.status})`, detail: null };
+    }
+
+    const data = (await response.json()) as HealthResponse;
+    const status = data.status || "unknown";
+    return {
+      status,
+      detail: status !== "healthy" ? (data.message ?? null) : null,
+    };
+  } catch (error) {
+    const status =
+      error instanceof Error && error.name === "AbortError"
+        ? "timeout"
+        : "unreachable";
+    return { status, detail: null };
+  }
+}
+
 export async function checkHealth(
   runtimeUrl: string,
   bearerToken?: string,