@vellumai/cli 0.4.35 → 0.4.37

package/AGENTS.md

@@ -0,0 +1,47 @@
+# CLI Package — Agent Instructions
+
+## Purpose
+
+The `cli/` package (`@vellumai/cli`) manages the **lifecycle of Vellum assistant instances** — creating, starting, stopping, connecting to, and deleting them. Commands here operate on or across instances and typically require specifying which assistant to target.
+
+This contrasts with `assistant/src/cli/`, where commands are scoped to a **single running assistant** and operate on its local state (config, memory, contacts, etc.).
+
+## When a command belongs here vs `assistant/src/cli/`
+
+| `cli/` (this package)                           | `assistant/src/cli/`                                |
+| ----------------------------------------------- | --------------------------------------------------- |
+| Operates on or across assistant instances       | Operates within a single assistant's workspace      |
+| Manages lifecycle (create, start, stop, delete) | Manages instance-local state (config, memory, etc.) |
+| Requires specifying which assistant to target   | Implicitly scoped to the running assistant          |
+| Works without an assistant process running      | May require or start the daemon                     |
+
+Examples: `hatch`, `wake`, `sleep`, `retire`, `ps`, `ssh` belong here. `config`, `contacts`, `memory` belong in `assistant/src/cli/`.
+
+## Assistant targeting convention
+
+Commands that act on a specific assistant should accept an assistant name or ID as an argument. When none is specified, default to the most recently created local assistant. Use `loadAllAssistants()` and `findAssistantByName()` from `lib/assistant-config` for resolution.
+
+## Conventions
+
+- Commands are standalone exported functions in `src/commands/`.
+- Each command manually parses `process.argv.slice(3)` (no framework — keep it lightweight).
+- Register new commands in the `commands` object in `src/index.ts` and add a help line.
+- User-facing output uses `console.log`/`console.error` directly (no shared logger).
+
+## Help Text Standards
+
+Every command must have high-quality `--help` output optimized for AI/LLM
+consumption. Help text is a primary interface — both humans and AI agents read
+it to understand what a command does and how to use it.
+
+### Requirements
+
+1. **Each command**: Include a concise one-liner description in the help output,
+   followed by an explanation of arguments/options with their formats and
+   constraints.
+
+2. **Include examples**: Show 2-3 concrete invocations with realistic values.
+
+3. **Write for machines**: Be precise about formats, constraints, and side effects.
+   AI agents parse help text to decide which command to run and how. Avoid vague
+   language — say exactly what the command does and where state is stored.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.4.35",
+  "version": "0.4.37",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {
@@ -11,7 +11,7 @@
     "./src/commands/*": "./src/commands/*.ts"
   },
   "bin": {
-    "vellum": "./src/index.ts"
+    "assistant": "./src/index.ts"
   },
   "scripts": {
     "format": "prettier --write .",

package/src/__tests__/skills-uninstall.test.ts

@@ -0,0 +1,201 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { skills } from "../commands/skills.js";
+
+let tempDir: string;
+let originalArgv: string[];
+let originalBaseDataDir: string | undefined;
+let originalExitCode: number | string | null | undefined;
+
+function getSkillsDir(): string {
+  return join(tempDir, ".vellum", "workspace", "skills");
+}
+
+function getSkillsIndexPath(): string {
+  return join(getSkillsDir(), "SKILLS.md");
+}
+
+function installFakeSkill(skillId: string): void {
+  const skillDir = join(getSkillsDir(), skillId);
+  mkdirSync(skillDir, { recursive: true });
+  writeFileSync(join(skillDir, "SKILL.md"), `# ${skillId}\nA test skill.\n`);
+}
+
+function writeSkillsIndex(content: string): void {
+  mkdirSync(getSkillsDir(), { recursive: true });
+  writeFileSync(getSkillsIndexPath(), content);
+}
+
+beforeEach(() => {
+  tempDir = join(tmpdir(), `skills-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(join(tempDir, ".vellum", "workspace", "skills"), {
+    recursive: true,
+  });
+  originalArgv = process.argv;
+  originalBaseDataDir = process.env.BASE_DATA_DIR;
+  originalExitCode = process.exitCode;
+  process.env.BASE_DATA_DIR = tempDir;
+});
+
+afterEach(() => {
+  process.argv = originalArgv;
+  process.env.BASE_DATA_DIR = originalBaseDataDir;
+  process.exitCode = originalExitCode;
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("vellum skills uninstall", () => {
+  test("removes skill directory and SKILLS.md entry", async () => {
+    /**
+     * Tests the happy path for uninstalling a skill.
+     */
+
+    // GIVEN a skill is installed locally
+    installFakeSkill("weather");
+    writeSkillsIndex("- weather\n- google-oauth-setup\n");
+
+    // WHEN we run `vellum skills uninstall weather`
+    process.argv = ["bun", "run", "skills", "uninstall", "weather"];
+    await skills();
+
+    // THEN the skill directory should be removed
+    expect(existsSync(join(getSkillsDir(), "weather"))).toBe(false);
+
+    // AND the SKILLS.md entry should be removed
+    const index = readFileSync(getSkillsIndexPath(), "utf-8");
+    expect(index).not.toContain("weather");
+
+    // AND other skills should remain in the index
+    expect(index).toContain("google-oauth-setup");
+  });
+
+  test("outputs JSON on success when --json flag is passed", async () => {
+    /**
+     * Tests that --json flag produces machine-readable output.
+     */
+
+    // GIVEN a skill is installed locally
+    installFakeSkill("weather");
+    writeSkillsIndex("- weather\n");
+
+    // WHEN we run `vellum skills uninstall weather --json`
+    process.argv = ["bun", "run", "skills", "uninstall", "weather", "--json"];
+    const logs: string[] = [];
+    const origLog = console.log;
+    console.log = (...args: unknown[]) => logs.push(args.join(" "));
+    try {
+      await skills();
+    } finally {
+      console.log = origLog;
+    }
+
+    // THEN JSON output should indicate success
+    const output = JSON.parse(logs[0]);
+    expect(output).toEqual({ ok: true, skillId: "weather" });
+  });
+
+  test("errors when skill is not installed", async () => {
+    /**
+     * Tests that uninstalling a non-existent skill produces an error.
+     */
+
+    // GIVEN no skills are installed
+    // WHEN we run `vellum skills uninstall nonexistent`
+    process.argv = ["bun", "run", "skills", "uninstall", "nonexistent"];
+    const errors: string[] = [];
+    const origError = console.error;
+    console.error = (...args: unknown[]) => errors.push(args.join(" "));
+    try {
+      await skills();
+    } finally {
+      console.error = origError;
+    }
+
+    // THEN an error message should be displayed
+    expect(errors[0]).toContain('Skill "nonexistent" is not installed.');
+    expect(process.exitCode).toBe(1);
+  });
+
+  test("errors with JSON output when skill is not installed and --json is passed", async () => {
+    /**
+     * Tests that --json flag produces machine-readable error output.
+     */
+
+    // GIVEN no skills are installed
+    // WHEN we run `vellum skills uninstall nonexistent --json`
+    process.argv = [
+      "bun",
+      "run",
+      "skills",
+      "uninstall",
+      "nonexistent",
+      "--json",
+    ];
+    const logs: string[] = [];
+    const origLog = console.log;
+    console.log = (...args: unknown[]) => logs.push(args.join(" "));
+    try {
+      await skills();
+    } finally {
+      console.log = origLog;
+    }
+
+    // THEN JSON output should indicate failure
+    const output = JSON.parse(logs[0]);
+    expect(output.ok).toBe(false);
+    expect(output.error).toContain('Skill "nonexistent" is not installed.');
+  });
+
+  test("works when SKILLS.md does not exist", async () => {
+    /**
+     * Tests that uninstall works even if the SKILLS.md index file is missing.
+     */
+
+    // GIVEN a skill directory exists but no SKILLS.md
+    installFakeSkill("weather");
+
+    // WHEN we run `vellum skills uninstall weather`
+    process.argv = ["bun", "run", "skills", "uninstall", "weather"];
+    await skills();
+
+    // THEN the skill directory should be removed
+    expect(existsSync(join(getSkillsDir(), "weather"))).toBe(false);
+
+    // AND no SKILLS.md should have been created
+    expect(existsSync(getSkillsIndexPath())).toBe(false);
+  });
+
+  test("removes skill with nested files", async () => {
+    /**
+     * Tests that uninstall recursively removes skills with nested directories.
+     */
+
+    // GIVEN a skill with nested files is installed
+    const skillDir = join(getSkillsDir(), "weather");
+    mkdirSync(join(skillDir, "scripts", "lib"), { recursive: true });
+    writeFileSync(join(skillDir, "SKILL.md"), "# weather\n");
+    writeFileSync(join(skillDir, "scripts", "fetch.sh"), "#!/bin/bash\n");
+    writeFileSync(join(skillDir, "scripts", "lib", "utils.sh"), "# utils\n");
+    writeSkillsIndex("- weather\n");
+
+    // WHEN we run `vellum skills uninstall weather`
+    process.argv = ["bun", "run", "skills", "uninstall", "weather"];
+    await skills();
+
+    // THEN the entire skill directory tree should be removed
+    expect(existsSync(skillDir)).toBe(false);
+
+    // AND the SKILLS.md entry should be removed
+    const index = readFileSync(getSkillsIndexPath(), "utf-8");
+    expect(index).not.toContain("weather");
+  });
+});

package/src/commands/skills.ts

@@ -1,10 +1,12 @@
 import { execSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import {
+  cpSync,
   existsSync,
   mkdirSync,
   readFileSync,
   renameSync,
+  rmSync,
   writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
@@ -27,6 +29,38 @@ function getSkillsIndexPath(): string {
   return join(getSkillsDir(), "SKILLS.md");
 }
 
+/**
+ * Resolve the repo-level skills/ directory when running in dev mode.
+ * Returns the path if VELLUM_DEV is set and the directory exists, or undefined.
+ */
+function getRepoSkillsDir(): string | undefined {
+  if (!process.env.VELLUM_DEV) return undefined;
+
+  // cli/src/commands/skills.ts -> ../../../skills/
+  const candidate = join(import.meta.dir, "..", "..", "..", "skills");
+  if (existsSync(join(candidate, "catalog.json"))) {
+    return candidate;
+  }
+  return undefined;
+}
+
+/**
+ * Read skills from the repo-local catalog.json.
+ */
+function readLocalCatalog(repoSkillsDir: string): CatalogSkill[] {
+  try {
+    const raw = readFileSync(
+      join(repoSkillsDir, "catalog.json"),
+      "utf-8",
+    );
+    const manifest = JSON.parse(raw) as CatalogManifest;
+    if (!Array.isArray(manifest.skills)) return [];
+    return manifest.skills;
+  } catch {
+    return [];
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Platform API client
 // ---------------------------------------------------------------------------
@@ -221,6 +255,33 @@ function upsertSkillsIndex(id: string): void {
   atomicWriteFile(indexPath, content.endsWith("\n") ? content : content + "\n");
 }
 
+function removeSkillsIndexEntry(id: string): void {
+  const indexPath = getSkillsIndexPath();
+  if (!existsSync(indexPath)) return;
+
+  const lines = readFileSync(indexPath, "utf-8").split("\n");
+  const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(`^[-*]\\s+(?:\`)?${escaped}(?:\`)?\\s*$`);
+  const filtered = lines.filter((line) => !pattern.test(line));
+
+  // If nothing changed, skip the write
+  if (filtered.length === lines.length) return;
+
+  const content = filtered.join("\n");
+  atomicWriteFile(indexPath, content.endsWith("\n") ? content : content + "\n");
+}
+
+function uninstallSkillLocally(skillId: string): void {
+  const skillDir = join(getSkillsDir(), skillId);
+
+  if (!existsSync(skillDir)) {
+    throw new Error(`Skill "${skillId}" is not installed.`);
+  }
+
+  rmSync(skillDir, { recursive: true, force: true });
+  removeSkillsIndexEntry(skillId);
+}
+
 async function installSkillLocally(
   skillId: string,
   catalogEntry: CatalogSkill,
@@ -237,8 +298,17 @@ async function installSkillLocally(
 
   mkdirSync(skillDir, { recursive: true });
 
-  // Extract all files from the archive into the skill directory
-  await fetchAndExtractSkill(skillId, skillDir);
+  // In dev mode, install from the local repo skills directory if available
+  const repoSkillsDir = getRepoSkillsDir();
+  const repoSkillSource = repoSkillsDir
+    ? join(repoSkillsDir, skillId)
+    : undefined;
+
+  if (repoSkillSource && existsSync(join(repoSkillSource, "SKILL.md"))) {
+    cpSync(repoSkillSource, skillDir, { recursive: true });
+  } else {
+    await fetchAndExtractSkill(skillId, skillDir);
+  }
 
   // Write version metadata
   if (catalogEntry.version) {
@@ -288,6 +358,9 @@ function printUsage(): void {
   console.log(
     "  install <skill-id> [--overwrite]  Install a skill from the catalog",
   );
+  console.log(
+    "  uninstall <skill-id>              Uninstall a previously installed skill",
+  );
   console.log("");
   console.log("Options:");
   console.log("  --json    Machine-readable JSON output");
@@ -312,6 +385,18 @@ export async function skills(): Promise<void> {
       try {
         const catalog = await fetchCatalog();
 
+        // In dev mode, merge in skills from the repo-local skills/ directory
+        const repoSkillsDir = getRepoSkillsDir();
+        if (repoSkillsDir) {
+          const localSkills = readLocalCatalog(repoSkillsDir);
+          const remoteIds = new Set(catalog.map((s) => s.id));
+          for (const local of localSkills) {
+            if (!remoteIds.has(local.id)) {
+              catalog.push(local);
+            }
+          }
+        }
+
         if (json) {
           console.log(JSON.stringify({ ok: true, skills: catalog }));
           return;
@@ -353,9 +438,20 @@ export async function skills(): Promise<void> {
       const overwrite = hasFlag(args, "--overwrite");
 
       try {
-        // Verify skill exists in catalog
-        const catalog = await fetchCatalog();
-        const entry = catalog.find((s) => s.id === skillId);
+        // In dev mode, also check the repo-local skills/ directory
+        const repoSkillsDir = getRepoSkillsDir();
+        let localSkills: CatalogSkill[] = [];
+        if (repoSkillsDir) {
+          localSkills = readLocalCatalog(repoSkillsDir);
+        }
+
+        // Check local catalog first, then fall back to remote
+        let entry = localSkills.find((s) => s.id === skillId);
+        if (!entry) {
+          const catalog = await fetchCatalog();
+          entry = catalog.find((s) => s.id === skillId);
+        }
+
         if (!entry) {
           throw new Error(`Skill "${skillId}" not found in the Vellum catalog`);
         }
@@ -380,6 +476,35 @@ export async function skills(): Promise<void> {
       break;
     }
 
+    case "uninstall": {
+      const skillId = args.find(
+        (a) => !a.startsWith("--") && a !== "uninstall",
+      );
+      if (!skillId) {
+        console.error("Usage: vellum skills uninstall <skill-id>");
+        process.exit(1);
+      }
+
+      try {
+        uninstallSkillLocally(skillId);
+
+        if (json) {
+          console.log(JSON.stringify({ ok: true, skillId }));
+        } else {
+          console.log(`Uninstalled skill "${skillId}".`);
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (json) {
+          console.log(JSON.stringify({ ok: false, error: msg }));
+        } else {
+          console.error(`Error: ${msg}`);
+        }
+        process.exitCode = 1;
+      }
+      break;
+    }
+
     default: {
       console.error(`Unknown skills subcommand: ${subcommand}`);
       printUsage();

package/src/index.ts

@@ -7,11 +7,7 @@ import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
 import cliPkg from "../package.json";
-import { autonomy } from "./commands/autonomy";
 import { client } from "./commands/client";
-import { config } from "./commands/config";
-import { contacts } from "./commands/contacts";
-import { email } from "./commands/email";
 import { hatch } from "./commands/hatch";
 import { login, logout, whoami } from "./commands/login";
 import { pair } from "./commands/pair";
@@ -25,11 +21,7 @@ import { tunnel } from "./commands/tunnel";
 import { wake } from "./commands/wake";
 
 const commands = {
-  autonomy,
   client,
-  config,
-  contacts,
-  email,
   hatch,
   login,
   logout,
@@ -88,8 +80,8 @@ async function main() {
     console.log("  autonomy View and configure autonomy tiers");
     console.log("  client   Connect to a hatched assistant");
     console.log("  config   Manage configuration");
-    console.log("  contacts Manage the contact graph");
-    console.log("  email    Email operations (status, create inbox)");
+    console.log("  contacts Manage assistant contacts");
+    console.log("  email    Email operations (provider-agnostic)");
     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");

package/src/lib/local.ts

@@ -342,6 +342,7 @@ async function startDaemonWatchFromSource(
   const env: Record<string, string | undefined> = {
     ...process.env,
     RUNTIME_HTTP_PORT: process.env.RUNTIME_HTTP_PORT || "7821",
+    VELLUM_DEV: "1",
   };
 
   const daemonLogFd = openLogFile("hatch.log");
@@ -701,6 +702,7 @@ export async function startLocalDaemon(watch: boolean = false): Promise<void> {
         "VELLUM_DAEMON_TCP_PORT",
         "VELLUM_DAEMON_TCP_HOST",
         "VELLUM_DAEMON_SOCKET",
+        "VELLUM_KEYCHAIN_BROKER_SOCKET",
         "VELLUM_DEBUG",
         "SENTRY_DSN",
         "TMPDIR",
@@ -839,6 +841,7 @@ export async function startGateway(
     // `vellum sleep` to SIGKILL the gateway when the CLI timeout is shorter
     // than the drain window.  Respect an explicit env override.
     GATEWAY_SHUTDOWN_DRAIN_MS: process.env.GATEWAY_SHUTDOWN_DRAIN_MS || "0",
+    ...(watch ? { VELLUM_DEV: "1" } : {}),
   };
 
   if (process.env.GATEWAY_UNMAPPED_POLICY) {

package/src/lib/ngrok.ts

@@ -1,8 +1,31 @@
 import { execFileSync, spawn, type ChildProcess } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 
-import { loadRawConfig, saveRawConfig } from "./config";
 import { GATEWAY_PORT } from "./constants";
 
+function getConfigPath(): string {
+  const root = join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum");
+  return join(root, "workspace", "config.json");
+}
+
+function loadRawConfig(): Record<string, unknown> {
+  const configPath = getConfigPath();
+  if (!existsSync(configPath)) return {};
+  return JSON.parse(readFileSync(configPath, "utf-8")) as Record<
+    string,
+    unknown
+  >;
+}
+
+function saveRawConfig(config: Record<string, unknown>): void {
+  const configPath = getConfigPath();
+  const dir = dirname(configPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
 const NGROK_API_URL = "http://127.0.0.1:4040/api/tunnels";
 const NGROK_POLL_INTERVAL_MS = 500;
 const NGROK_POLL_TIMEOUT_MS = 15_000;