@vellumai/cli 0.4.0 → 0.4.2

package/package.json

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

package/src/adapters/install.sh

@@ -79,6 +79,82 @@ ensure_bun() {
     success "bun installed ($(bun --version))"
 }
 
+# Ensure ~/.bun/bin is in the user's shell profile so bun and vellum are
+# available in new terminal sessions. The bun installer sometimes skips
+# this (e.g. when stdin is piped via curl | bash).
+configure_shell_profile() {
+    local bun_line='export BUN_INSTALL="$HOME/.bun"'
+    local path_line='export PATH="$BUN_INSTALL/bin:$PATH"'
+    local snippet
+    snippet=$(printf '\n# bun\n%s\n%s\n' "$bun_line" "$path_line")
+
+    local profiles=()
+    local shell_name="${SHELL:-}"
+
+    if [[ "$shell_name" == */zsh ]]; then
+        profiles+=("$HOME/.zshrc")
+    elif [[ "$shell_name" == */bash ]]; then
+        # Write to both .bashrc (non-login shells, e.g. new terminal on Linux)
+        # and .bash_profile (login shells, e.g. macOS Terminal.app)
+        profiles+=("$HOME/.bashrc")
+        [ -f "$HOME/.bash_profile" ] && profiles+=("$HOME/.bash_profile")
+    else
+        # Unknown shell — try both
+        profiles+=("$HOME/.bashrc")
+        [ -f "$HOME/.zshrc" ] && profiles+=("$HOME/.zshrc")
+    fi
+
+    for profile in "${profiles[@]}"; do
+        if [ -f "$profile" ] && grep -q 'BUN_INSTALL' "$profile" 2>/dev/null; then
+            continue
+        fi
+        printf '%s\n' "$snippet" >> "$profile"
+        success "Added bun to PATH in $profile"
+    done
+}
+
+# Create a symlink so `vellum` is available without ~/.bun/bin in PATH.
+# Tries /usr/local/bin first (works on most systems), falls back to
+# ~/.local/bin (user-writable, no sudo needed).
+# This is best-effort — failure must not abort the install script.
+symlink_vellum() {
+    local vellum_bin="$HOME/.bun/bin/vellum"
+    if [ ! -f "$vellum_bin" ]; then
+        return 0
+    fi
+
+    # Skip if vellum is already resolvable outside of ~/.bun/bin
+    local resolved
+    resolved=$(command -v vellum 2>/dev/null || true)
+    if [ -n "$resolved" ] && [ "$resolved" != "$vellum_bin" ]; then
+        return 0
+    fi
+
+    # Try /usr/local/bin (may need sudo on some systems)
+    if [ -d "/usr/local/bin" ] && [ -w "/usr/local/bin" ]; then
+        if ln -sf "$vellum_bin" /usr/local/bin/vellum 2>/dev/null; then
+            success "Symlinked /usr/local/bin/vellum → $vellum_bin"
+            return 0
+        fi
+    fi
+
+    # Fallback: ~/.local/bin
+    local local_bin="$HOME/.local/bin"
+    mkdir -p "$local_bin" 2>/dev/null || true
+    if ln -sf "$vellum_bin" "$local_bin/vellum" 2>/dev/null; then
+        success "Symlinked $local_bin/vellum → $vellum_bin"
+        # Ensure ~/.local/bin is in PATH in shell profile
+        for profile in "$HOME/.zshrc" "$HOME/.bashrc" "$HOME/.bash_profile"; do
+            if [ -f "$profile" ] && ! grep -q "$local_bin" "$profile" 2>/dev/null; then
+                printf '\nexport PATH="%s:$PATH"\n' "$local_bin" >> "$profile"
+            fi
+        done
+        return 0
+    fi
+
+    return 0
+}
+
 install_vellum() {
     if command -v vellum >/dev/null 2>&1; then
         info "Updating vellum to latest..."
@@ -103,7 +179,15 @@ main() {
 
     ensure_git
     ensure_bun
+    configure_shell_profile
     install_vellum
+    symlink_vellum
+
+    # Source the shell profile so vellum hatch runs with the correct PATH
+    # in this session (the profile changes only take effect in new shells
+    # otherwise).
+    export BUN_INSTALL="$HOME/.bun"
+    export PATH="$BUN_INSTALL/bin:$PATH"
 
     info "Running vellum hatch..."
     printf "\n"

package/src/commands/hatch.ts

@@ -13,6 +13,7 @@ import { loadAllAssistants, saveAssistantEntry, syncConfigToLockfile } from "../
 import type { AssistantEntry } from "../lib/assistant-config";
 import { hatchAws } from "../lib/aws";
 import {
+  GATEWAY_PORT,
   SPECIES_CONFIG,
   VALID_REMOTE_HOSTS,
   VALID_SPECIES,
@@ -21,6 +22,7 @@ import type { RemoteHost, Species } from "../lib/constants";
 import { hatchGcp } from "../lib/gcp";
 import type { PollResult, WatchHatchingResult } from "../lib/gcp";
 import { startLocalDaemon, startGateway, stopLocalProcesses } from "../lib/local";
+import { probePort } from "../lib/port-probe";
 import { isProcessAlive } from "../lib/process";
 import { generateRandomSuffix } from "../lib/random-name";
 import { validateAssistantName } from "../lib/retire-archive";
@@ -155,7 +157,22 @@ function parseArgs(): HatchArgs {
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
-    if (arg === "-d") {
+    if (arg === "--help" || arg === "-h") {
+      console.log("Usage: vellum hatch [species] [options]");
+      console.log("");
+      console.log("Create a new assistant instance.");
+      console.log("");
+      console.log("Species:");
+      console.log("  vellum       Default assistant (default)");
+      console.log("  openclaw     OpenClaw adapter");
+      console.log("");
+      console.log("Options:");
+      console.log("  -d                        Run in detached mode");
+      console.log("  --name <name>             Custom instance name");
+      console.log("  --remote <host>           Remote host (local, gcp, aws, custom)");
+      console.log("  --daemon-only             Start daemon only, skip gateway");
+      process.exit(0);
+    } else if (arg === "-d") {
       detached = true;
     } else if (arg === "--daemon-only") {
       daemonOnly = true;
@@ -496,6 +513,8 @@ async function displayPairingQRCode(runtimeUrl: string, bearerToken: string | un
     });
 
     if (!registerRes.ok) {
+      const body = await registerRes.text().catch(() => "");
+      console.warn(`⚠ Could not register pairing request: ${registerRes.status} ${registerRes.statusText}${body ? ` — ${body}` : ""}. Run \`vellum pair\` to try again.\n`);
       return;
     }
 
@@ -519,8 +538,10 @@ async function displayPairingQRCode(runtimeUrl: string, bearerToken: string | un
     console.log(qrString);
     console.log("This pairing request expires in 5 minutes.");
     console.log("Run `vellum pair` to generate a new one.\n");
-  } catch {
+  } catch (err) {
     // Non-fatal — pairing is optional
+    const reason = err instanceof Error ? err.message : String(err);
+    console.warn(`⚠ Could not generate pairing QR code: ${reason}. Run \`vellum pair\` to try again.\n`);
   }
 }
 
@@ -540,6 +561,32 @@ async function hatchLocal(species: Species, name: string | null, daemonOnly: boo
       console.log("🧹 Cleaning up stale local processes (no lock file entry)...\n");
       await stopLocalProcesses();
     }
+
+    // Verify required ports are available before starting any services.
+    // Only check when no local assistants exist — if there are existing local
+    // assistants, their daemon/gateway/qdrant legitimately own these ports.
+    const RUNTIME_HTTP_PORT = Number(process.env.RUNTIME_HTTP_PORT) || 7821;
+    const QDRANT_PORT = 6333;
+    const requiredPorts = [
+      { name: "daemon", port: RUNTIME_HTTP_PORT },
+      { name: "gateway", port: GATEWAY_PORT },
+      { name: "qdrant", port: QDRANT_PORT },
+    ];
+    const conflicts: string[] = [];
+    await Promise.all(
+      requiredPorts.map(async ({ name, port }) => {
+        if (await probePort(port)) {
+          conflicts.push(`  - Port ${port} (${name}) is already in use`);
+        }
+      }),
+    );
+    if (conflicts.length > 0) {
+      throw new Error(
+        `Cannot hatch — required ports are already in use:\n${conflicts.join("\n")}\n\n` +
+          "Stop the conflicting processes or use environment variables to configure alternative ports " +
+          "(RUNTIME_HTTP_PORT, GATEWAY_PORT).",
+      );
+    }
   }
 
   const baseDataDir = join(process.env.BASE_DATA_DIR?.trim() || (process.env.HOME ?? userInfo().homedir), ".vellum");

package/src/commands/login.ts

@@ -7,6 +7,17 @@ import {
 
 export async function login(): Promise<void> {
   const args = process.argv.slice(3);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum login --token <session-token>");
+    console.log("");
+    console.log("Log in to the Vellum platform.");
+    console.log("");
+    console.log("Options:");
+    console.log("  --token <token>    Session token from the Vellum platform");
+    process.exit(0);
+  }
+
   let token: string | null = null;
 
   for (let i = 0; i < args.length; i++) {
@@ -43,11 +54,27 @@ export async function login(): Promise<void> {
 }
 
 export async function logout(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum logout");
+    console.log("");
+    console.log("Log out of the Vellum platform and remove the stored session token.");
+    process.exit(0);
+  }
+
   clearPlatformToken();
   console.log("Logged out. Platform token removed.");
 }
 
 export async function whoami(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum whoami");
+    console.log("");
+    console.log("Show the currently logged-in Vellum platform user.");
+    process.exit(0);
+  }
+
   const token = readPlatformToken();
   if (!token) {
     console.error("Not logged in. Run `vellum login --token <token>` first.");

package/src/commands/pair.ts

@@ -72,6 +72,14 @@ async function pollForApproval(
 
 export async function pair(): Promise<void> {
   const args = process.argv.slice(3);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum pair <path-to-qrcode.png>");
+    console.log("");
+    console.log("Pair with a remote assistant by scanning the QR code PNG generated during setup.");
+    process.exit(0);
+  }
+
   const qrCodePath = args[0] || process.env.VELLUM_CUSTOM_QR_CODE_PATH;
 
   if (!qrCodePath) {

package/src/commands/ps.ts

@@ -409,6 +409,17 @@ async function listAllAssistants(): Promise<void> {
 // ── Entry point ─────────────────────────────────────────────────
 
 export async function ps(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum ps [<name>]");
+    console.log("");
+    console.log("List all assistants, or show processes for a specific assistant.");
+    console.log("");
+    console.log("Arguments:");
+    console.log("  <name>    Show processes for the named assistant");
+    process.exit(0);
+  }
+
   const assistantId = process.argv[3];
 
   if (!assistantId) {

package/src/commands/recover.ts

@@ -9,6 +9,17 @@ import { getArchivePath, getMetadataPath } from "../lib/retire-archive";
 import { exec } from "../lib/step-runner";
 
 export async function recover(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum recover <name>");
+    console.log("");
+    console.log("Restore a previously retired local assistant from its archive.");
+    console.log("");
+    console.log("Arguments:");
+    console.log("  <name>    Name of the retired assistant to recover");
+    process.exit(0);
+  }
+
   const name = process.argv[3];
   if (!name) {
     console.error("Usage: vellum recover <name>");

package/src/commands/retire.ts

@@ -121,6 +121,20 @@ function parseSource(): string | undefined {
 }
 
 export async function retire(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum retire <name> [--source <source>]");
+    console.log("");
+    console.log("Delete an assistant instance and archive its data.");
+    console.log("");
+    console.log("Arguments:");
+    console.log("  <name>               Name of the assistant to retire");
+    console.log("");
+    console.log("Options:");
+    console.log("  --source <source>    Source identifier for the retirement");
+    process.exit(0);
+  }
+
   const name = process.argv[3];
 
   if (!name) {

package/src/commands/sleep.ts

@@ -5,6 +5,14 @@ import { loadAllAssistants } from "../lib/assistant-config";
 import { stopProcessByPidFile } from "../lib/process";
 
 export async function sleep(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum sleep");
+    console.log("");
+    console.log("Stop the daemon and gateway processes.");
+    process.exit(0);
+  }
+
   const assistants = loadAllAssistants();
   const hasLocal = assistants.some((a) => a.cloud === "local");
   if (!hasLocal) {

package/src/commands/ssh.ts

@@ -33,6 +33,17 @@ function extractHostFromUrl(url: string): string {
 }
 
 export async function ssh(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum ssh [<name>]");
+    console.log("");
+    console.log("SSH into a remote assistant instance.");
+    console.log("");
+    console.log("Arguments:");
+    console.log("  <name>    Name of the assistant to connect to (defaults to latest)");
+    process.exit(0);
+  }
+
   const name = process.argv[3];
   const entry = name ? findAssistantByName(name) : loadLatestAssistant();
 

package/src/commands/wake.ts

@@ -7,6 +7,14 @@ import { isProcessAlive } from "../lib/process";
 import { startLocalDaemon, startGateway } from "../lib/local";
 
 export async function wake(): Promise<void> {
+  const args = process.argv.slice(3);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum wake");
+    console.log("");
+    console.log("Start the daemon and gateway processes.");
+    process.exit(0);
+  }
+
   const assistants = loadAllAssistants();
   const hasLocal = assistants.some((a) => a.cloud === "local");
   if (!hasLocal) {

package/src/index.ts

@@ -31,8 +31,8 @@ const commands = {
   email,
   hatch,
   login,
-  pair,
   logout,
+  pair,
   ps,
   recover,
   retire,
@@ -90,9 +90,9 @@ async function main() {
     console.log("  contacts Manage the contact graph");
     console.log("  email    Email operations (status, create inbox)");
     console.log("  hatch    Create a new assistant instance");
-    console.log("  pair     Pair with a remote assistant via QR code");
     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");