@vellumai/cli 0.4.49 → 0.4.50

package/package.json

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

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,
@@ -359,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/components/DefaultMainScreen.tsx

@@ -500,6 +500,9 @@ async function handleScopeSelection(
 
 export const TYPING_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
+/** ASCII-safe spinner frames for the connection screen. */
+const CONNECTION_SPINNER_FRAMES = ["|", "/", "-", "\\"];
+
 export interface ToolCallInfo {
   name: string;
   input: Record<string, unknown>;
@@ -675,6 +678,75 @@ function SpinnerDisplay({ text }: { text: string }): ReactElement {
   );
 }
 
+type ConnectionState = "connecting" | "connected" | "error";
+
+function ConnectionScreen({
+  state,
+  errorMessage,
+  species,
+  terminalRows,
+  terminalColumns,
+  onRetry,
+  onExit,
+}: {
+  state: ConnectionState;
+  errorMessage?: string;
+  species: Species;
+  terminalRows: number;
+  terminalColumns: number;
+  onRetry: () => void;
+  onExit: () => void;
+}): ReactElement {
+  const [frameIndex, setFrameIndex] = useState(0);
+
+  useEffect(() => {
+    if (state !== "connecting") return;
+    const timer = setInterval(() => {
+      setFrameIndex((prev) => (prev + 1) % CONNECTION_SPINNER_FRAMES.length);
+    }, 150);
+    return () => clearInterval(timer);
+  }, [state]);
+
+  useInput((input, key) => {
+    if (key.ctrl && input === "c") {
+      onExit();
+    }
+    if (state === "error" && input === "r") {
+      onRetry();
+    }
+  });
+
+  const config = SPECIES_CONFIG[species];
+  const title = `Vellum ${config.hatchedEmoji} ${species}`;
+  const width = Math.min(terminalColumns, MAX_TOTAL_WIDTH);
+
+  return (
+    <Box
+      flexDirection="column"
+      height={terminalRows}
+      width={width}
+      justifyContent="center"
+      alignItems="center"
+    >
+      <Text dimColor bold>
+        {title}
+      </Text>
+      <Text> </Text>
+      {state === "connecting" ? (
+        <Text dimColor>
+          {CONNECTION_SPINNER_FRAMES[frameIndex]} Connecting to assistant...
+        </Text>
+      ) : (
+        <>
+          <Text color="red">Failed to connect: {errorMessage}</Text>
+          <Text> </Text>
+          <Text dimColor>Press r to retry or Ctrl+C to quit</Text>
+        </>
+      )}
+    </Box>
+  );
+}
+
 export function renderErrorMainScreen(error: unknown): number {
   const msg = error instanceof Error ? error.message : String(error);
   console.log(
@@ -1224,6 +1296,11 @@ function ChatApp({
   const [healthStatus, setHealthStatus] = useState<string | undefined>(
     undefined,
   );
+  const [connectionState, setConnectionState] =
+    useState<ConnectionState>("connecting");
+  const [connectionError, setConnectionError] = useState<string | undefined>(
+    undefined,
+  );
   const prevFeedLengthRef = useRef(0);
   const busyRef = useRef(false);
   const connectedRef = useRef(false);
@@ -1240,7 +1317,7 @@ function ChatApp({
   const headerHeight = calculateHeaderHeight(species, terminalColumns);
 
   const isCompact = terminalColumns < COMPACT_THRESHOLD;
-  const compactInputAreaHeight = 2; // separator + input row only
+  const compactInputAreaHeight = 1; // input row only, no separators
   const inputAreaHeight = isCompact
     ? compactInputAreaHeight
     : INPUT_AREA_HEIGHT;
@@ -1476,6 +1553,8 @@ function ChatApp({
       return false;
     }
     connectingRef.current = true;
+    setConnectionState("connecting");
+    setConnectionError(undefined);
     const h = handleRef_.current;
 
     h.showSpinner("Connecting...");
@@ -1538,12 +1617,15 @@ function ChatApp({
 
       connectedRef.current = true;
       connectingRef.current = false;
+      setConnectionState("connected");
       return true;
     } catch (err) {
       h.hideSpinner();
       connectingRef.current = false;
       h.updateHealthStatus("unreachable");
       const msg = err instanceof Error ? err.message : String(err);
+      setConnectionState("error");
+      setConnectionError(msg);
       h.addStatus(
         `${statusEmoji("unreachable")} Failed to connect: ${msg}`,
         "red",
@@ -2065,6 +2147,7 @@ function ChatApp({
                     role: "assistant",
                     content: msg.content,
                   });
+                  process.stdout.write("\x07");
                   h.setBusy(false);
                   h.hideSpinner();
                   return;
@@ -2174,6 +2257,13 @@ function ChatApp({
     updateHealthStatus,
   ]);
 
+  const retryConnection = useCallback(() => {
+    if (connectingRef.current) return; // already retrying
+    connectedRef.current = false;
+    setConnectionState("connecting");
+    ensureConnected();
+  }, [ensureConnected]);
+
   useEffect(() => {
     ensureConnected();
   }, [ensureConnected]);
@@ -2262,6 +2352,20 @@ function ChatApp({
     }
   }, [selection]);
 
+  if (connectionState !== "connected") {
+    return (
+      <ConnectionScreen
+        state={connectionState}
+        errorMessage={connectionError}
+        species={species}
+        terminalRows={terminalRows}
+        terminalColumns={terminalColumns}
+        onRetry={retryConnection}
+        onExit={onExit}
+      />
+    );
+  }
+
   return (
     <Box flexDirection="column" height={terminalRows}>
       <DefaultMainScreen
@@ -2274,8 +2378,9 @@ function ChatApp({
       <Box flexDirection="column" flexGrow={1} overflow="hidden">
         {visibleWindow.hiddenAbove > 0 ? (
           <Text dimColor>
-            {"\u2191"} {visibleWindow.hiddenAbove} more above
-            (Shift+\u2191/Cmd+\u2191)
+            {isCompact
+              ? `\u2191 ${visibleWindow.hiddenAbove} more above`
+              : `\u2191 ${visibleWindow.hiddenAbove} more above (Shift+\u2191/Cmd+\u2191)`}
           </Text>
         ) : null}
 
@@ -2341,12 +2446,14 @@ function ChatApp({
 
       {!selection && !secretInput ? (
         <Box flexDirection="column" flexShrink={0}>
-          <Text dimColor>
-            {unicodeOrFallback("\u2500", "-").repeat(terminalColumns)}
-          </Text>
-          <Box paddingLeft={1} height={1} flexShrink={0}>
+          {isCompact ? null : (
+            <Text dimColor>
+              {unicodeOrFallback("\u2500", "-").repeat(terminalColumns)}
+            </Text>
+          )}
+          <Box paddingLeft={isCompact ? 0 : 1} height={1} flexShrink={0}>
             <Text color="green" bold>
-              you{">"}
+              {isCompact ? ">" : "you>"}
               {" "}
             </Text>
             <TextInput

package/src/index.ts

@@ -15,6 +15,13 @@ 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,
@@ -37,37 +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("  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");
+  if (commandName === "--help" || commandName === "-h") {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (!commandName) {
+    const launched = await tryLaunchClient();
+    if (!launched) {
+      printHelp();
+    }
     process.exit(0);
   }
 

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 {
@@ -34,6 +33,36 @@ async function ensureDockerInstalled(): Promise<void> {
   }
 
   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"]);
@@ -58,6 +87,21 @@ async function ensureDockerInstalled(): Promise<void> {
   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"]);
@@ -326,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/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,

package/src/lib/terminal-capabilities.ts

@@ -107,6 +107,15 @@ export function getTerminalCapabilities(): TerminalCapabilities {
   return _cached;
 }
 
+/**
+ * Clear the cached capabilities so the next `getTerminalCapabilities()`
+ * call re-detects from the current environment. Useful after modifying
+ * `process.env.NO_COLOR` at startup or in tests.
+ */
+export function resetCapabilitiesCache(): void {
+  _cached = undefined;
+}
+
 // ── Convenience helpers ──────────────────────────────────────
 
 /** True when colors should be used (any level above "none"). */