@vellumai/cli 0.8.2 → 0.8.4

package/AGENTS.md

@@ -55,14 +55,26 @@ For example, the signing key used for JWT auth between the daemon and gateway is
 
 ## Docker Volume Management
 
-The CLI creates and manages Docker volumes for containerized instances. See the root `AGENTS.md` § Docker Volume Architecture for the full volume layout.
+The CLI creates and manages six per-instance Docker volumes with strict per-service access boundaries (least-privilege at the container level).
 
-**Volume creation** (`hatch`): Creates six volumes per instance — workspace, gateway-security, ces-security, socket, assistant-ipc, and gateway-ipc. The legacy data volume is no longer created.
+| Volume                                      | Mount path           | Access                              | Contents                                                                         |
+| ------------------------------------------- | -------------------- | ----------------------------------- | -------------------------------------------------------------------------------- |
+| **Workspace** (`<name>-workspace`)          | `/workspace`         | Assistant: rw, Gateway: rw, CES: ro | `config.json`, conversations, apps, skills, db, logs, `.backups/`, `.backup.key` |
+| **Gateway security** (`<name>-gateway-sec`) | `/gateway-security`  | Gateway only                        | `trust.json`, `actor-token-signing-key`, capability-token secrets                |
+| **CES security** (`<name>-ces-sec`)         | `/ces-security`      | CES only                            | `keys.enc`, `store.key`                                                          |
+| **Socket** (`<name>-socket`)                | `/run/ces-bootstrap` | Assistant + CES                     | CES bootstrap socket for initial handshake                                       |
+| **Gateway IPC** (`<name>-gateway-ipc`)      | `/run/gateway-ipc`   | Assistant + Gateway                 | `gateway.sock` (assistant → gateway)                                             |
+| **Assistant IPC** (`<name>-assistant-ipc`)  | `/run/assistant-ipc` | Assistant + Gateway                 | `assistant.sock` (gateway → assistant)                                           |
 
-**Volume migration** (`wake`/`hatch`): On startup, existing instances that still have a legacy data volume are migrated. `migrateGatewaySecurityFiles()` and `migrateCesSecurityFiles()` in `lib/docker.ts` copy security files from the data volume to their respective security volumes. Migrations are idempotent and non-fatal.
+The assistant container's root (`/`) holds per-container ephemeral and persistent state: package installs (`~/.bun`), `device.json`, embed-worker PID files.
 
-**Volume cleanup** (`retire`): All volumes (including the legacy data volume if it exists) are removed when an instance is retired.
+**Lifecycle**:
 
-**Volume mount rules**: Each service container receives only the volumes it needs. The assistant never mounts `gateway-security` or `ces-security`. The gateway never mounts `ces-security`. The CES mounts the workspace volume as read-only.
+- `hatch` creates the six volumes.
+- `retire` removes all of them.
 
-**Container security posture**: The assistant container runs as a non-root user (UID 1001) with no elevated capabilities. `--privileged`, `--cap-add`, and `--security-opt` overrides are NOT used. The host Docker socket is NOT bind-mounted. Do NOT re-add elevated capabilities without a concrete runtime requirement — the Docker Engine packages and inner `dockerd` supervisor were reverted (PR #26028) and the capabilities they required are no longer needed.
+**Mount rules**: each container receives only the volumes it needs. The assistant never mounts `gateway-security` or `ces-security`. The gateway never mounts `ces-security`. The CES mounts the workspace volume as read-only.
+
+**Container security posture**: the assistant container runs as a non-root user (UID 1001) with no elevated capabilities — `--privileged`, `--cap-add`, and `--security-opt` overrides are not used; the host Docker socket is not bind-mounted; default Docker seccomp and AppArmor profiles remain active. Do not add elevated capabilities without a concrete runtime requirement.
+
+**Backup paths in Docker mode**: backups land on the workspace volume (`VELLUM_BACKUP_DIR` defaults to `/workspace/.backups/`, key at `VELLUM_BACKUP_KEY_PATH` defaults to `/workspace/.backup.key`), so workspace-volume destruction loses both data and backups.

package/README.md

@@ -54,27 +54,25 @@ vellum hatch [species] [options]
 
 #### Options
 
-| Option              | Description                                                                                    |
-| ------------------- | ---------------------------------------------------------------------------------------------- |
-| `-d`                | Detached mode. Start the instance in the background without watching startup progress.         |
-| `--name <name>`     | Use a specific instance name instead of an auto-generated one.                                 |
-| `--remote <target>` | Where to provision the instance. One of: `local`, `gcp`, `aws`, `custom`. Defaults to `local`. |
+| Option              | Description                                                                                                        |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `-d`                | Detached mode. Start the instance in the background without watching startup progress.                             |
+| `--name <name>`     | Use a specific instance name instead of an auto-generated one.                                                     |
+| `--remote <target>` | Where to provision the instance. One of: `local`, `docker`, `vellum`, `gcp`, `aws`, `custom`. Defaults to `local`. |
 
 #### Remote Targets
 
 - **`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.
+- **`docker`** -- Starts the assistant, gateway, and credential service in Docker containers.
+- **`vellum`** -- Hatches an assistant on the Vellum platform.
+- **`gcp`** and **`aws`** -- Recognized but not supported as provisioning targets yet. The CLI exits before creating cloud resources. To self-host on AWS/GCP, SSH into the VM and run `vellum hatch` or `vellum hatch --remote docker` there.
+- **`custom`** -- Recognized but not yet implemented.
 
 #### 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.                        |
+| Variable            | Required For | Description                                                                |
+| ------------------- | ------------ | -------------------------------------------------------------------------- |
+| `ANTHROPIC_API_KEY` | Optional     | Used during setup when no Anthropic API key is already stored or prompted. |
 
 #### Examples
 
@@ -82,20 +80,14 @@ vellum hatch [species] [options]
 # Hatch a local assistant (default)
 vellum hatch
 
-# Hatch a vellum assistant on GCP
-vellum hatch vellum --remote gcp
-
-# Hatch an openclaw assistant on GCP in detached mode
-vellum hatch openclaw --remote gcp -d
+# Hatch a Docker assistant
+vellum hatch --remote docker
 
 # Hatch with a specific instance name
-vellum hatch --name my-assistant --remote gcp
-
-# Hatch on a custom SSH host
-VELLUM_CUSTOM_HOST=user@10.0.0.1 vellum hatch --remote custom
+vellum hatch --name my-assistant --remote docker
 ```
 
-When hatching on GCP in interactive mode (without `-d`), the CLI displays an animated progress TUI that polls the instance's startup script output in real time. Press `Ctrl+C` to detach -- the instance will continue running in the background.
+AWS and GCP hatch targets are recognized so users receive an explicit unsupported-target error instead of an unknown-option error. They currently exit without creating cloud resources; self-hosting on an AWS/GCP VM still works by running `vellum hatch` from inside that machine.
 
 ### `terminal`
 
@@ -111,18 +103,18 @@ Only available for managed assistants (those running in a Vellum Cloud container
 
 #### Subcommands
 
-| Subcommand         | Description                                                              |
-| ------------------ | ------------------------------------------------------------------------ |
-| _(none)_           | Open an interactive shell session inside the container.                  |
-| `attach <session>` | Attach to an existing `tmux` session by name inside the container.       |
-| `list`             | List the `tmux` sessions currently running inside the container.         |
+| Subcommand         | Description                                                        |
+| ------------------ | ------------------------------------------------------------------ |
+| _(none)_           | Open an interactive shell session inside the container.            |
+| `attach <session>` | Attach to an existing `tmux` session by name inside the container. |
+| `list`             | List the `tmux` sessions currently running inside the container.   |
 
 #### Options
 
-| Option               | Description                                                                                  |
-| -------------------- | -------------------------------------------------------------------------------------------- |
+| Option               | Description                                                                                         |
+| -------------------- | --------------------------------------------------------------------------------------------------- |
 | `[name]`             | Positional. Name of the assistant to target. Defaults to the active assistant set via `vellum use`. |
-| `--assistant <name>` | Explicit form of the assistant name. Equivalent to the positional argument.                  |
+| `--assistant <name>` | Explicit form of the assistant name. Equivalent to the positional argument.                         |
 
 If no assistant is named and no active assistant is set, the CLI uses the only managed assistant in the lockfile -- or errors out if there's more than one. Use `vellum ps` to see your assistants and `vellum use <name>` to set the active one.
 

package/package.json

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

package/src/__tests__/assistant-config.test.ts

@@ -10,6 +10,10 @@ process.env.VELLUM_LOCKFILE_DIR = testDir;
 import {
   loadLatestAssistant,
   findAssistantByName,
+  formatAssistantLookupError,
+  formatAssistantReference,
+  getAssistantDisplayName,
+  lookupAssistantByIdentifier,
   removeAssistantEntry,
   loadAllAssistants,
   saveAssistantEntry,
@@ -87,6 +91,110 @@ describe("assistant-config", () => {
     expect(result!.assistantId).toBe("beta");
   });
 
+  test("getAssistantDisplayName prefers platform and legacy display names", () => {
+    expect(
+      getAssistantDisplayName(
+        makeEntry("assistant-1", undefined, { name: "Alice" }),
+      ),
+    ).toBe("Alice");
+    expect(
+      getAssistantDisplayName(
+        makeEntry("assistant-2", undefined, { assistantName: "Legacy Alice" }),
+      ),
+    ).toBe("Legacy Alice");
+    expect(getAssistantDisplayName(makeEntry("assistant-3"))).toBe(
+      "assistant-3",
+    );
+  });
+
+  test("findAssistantByName only resolves assistant IDs", () => {
+    writeLockfile({
+      assistants: [
+        makeEntry("assistant-1", "http://localhost:7821", { name: "Alice" }),
+        makeEntry("assistant-2", "http://localhost:7822", { name: "Bob" }),
+      ],
+    });
+
+    expect(findAssistantByName("Alice")).toBeNull();
+    expect(findAssistantByName("assistant-1")?.assistantId).toBe("assistant-1");
+  });
+
+  test("lookupAssistantByIdentifier resolves a unique display name", () => {
+    writeLockfile({
+      assistants: [
+        makeEntry("assistant-1", "http://localhost:7821", { name: "Alice" }),
+        makeEntry("assistant-2", "http://localhost:7822", { name: "Bob" }),
+      ],
+    });
+
+    const result = lookupAssistantByIdentifier("Alice");
+    expect(result.status).toBe("found");
+    expect(result.status === "found" ? result.entry.assistantId : null).toBe(
+      "assistant-1",
+    );
+  });
+
+  test("lookupAssistantByIdentifier resolves a unique legacy assistantName", () => {
+    writeLockfile({
+      assistants: [
+        makeEntry("assistant-1", "http://localhost:7821", {
+          assistantName: "Legacy Alice",
+        }),
+      ],
+    });
+
+    const result = lookupAssistantByIdentifier("Legacy Alice");
+    expect(result.status).toBe("found");
+    expect(result.status === "found" ? result.entry.assistantId : null).toBe(
+      "assistant-1",
+    );
+  });
+
+  test("assistant ID lookup wins over a display name match", () => {
+    writeLockfile({
+      assistants: [
+        makeEntry("Alice", "http://localhost:7821", { name: "Primary" }),
+        makeEntry("assistant-2", "http://localhost:7822", { name: "Alice" }),
+      ],
+    });
+
+    const result = lookupAssistantByIdentifier("Alice");
+    expect(result.status).toBe("found");
+    expect(result.status === "found" ? result.entry.assistantId : null).toBe(
+      "Alice",
+    );
+  });
+
+  test("ambiguous display name lookup is explicit", () => {
+    writeLockfile({
+      assistants: [
+        makeEntry("assistant-1", "http://localhost:7821", { name: "Alice" }),
+        makeEntry("assistant-2", "http://localhost:7822", { name: "Alice" }),
+      ],
+    });
+
+    const result = lookupAssistantByIdentifier("Alice");
+    expect(result.status).toBe("ambiguous");
+    expect(findAssistantByName("Alice")).toBeNull();
+    expect(formatAssistantLookupError("Alice", result)).toContain(
+      "assistant-1",
+    );
+    expect(formatAssistantLookupError("Alice", result)).toContain(
+      "assistant-2",
+    );
+  });
+
+  test("formatAssistantReference includes distinct display name and id", () => {
+    expect(
+      formatAssistantReference(
+        makeEntry("assistant-1", undefined, { name: "Alice" }),
+      ),
+    ).toBe("Alice (assistant-1)");
+    expect(formatAssistantReference(makeEntry("assistant-2"))).toBe(
+      "assistant-2",
+    );
+  });
+
   test("findAssistantByName returns null for non-existent name", () => {
     writeLockfile({ assistants: [makeEntry("alpha")] });
     expect(findAssistantByName("missing")).toBeNull();

package/src/__tests__/assistant-target-args.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "bun:test";
+
+import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
+
+describe("parseAssistantTargetArg", () => {
+  test("joins unquoted display-name words into one assistant target", () => {
+    expect(parseAssistantTargetArg(["Example", "Assistant"])).toBe(
+      "Example Assistant",
+    );
+  });
+
+  test("skips boolean flags", () => {
+    expect(parseAssistantTargetArg(["Example", "Assistant", "--verbose"])).toBe(
+      "Example Assistant",
+    );
+  });
+
+  test("skips configured flags and their values", () => {
+    expect(
+      parseAssistantTargetArg(
+        ["--url", "http://localhost:7830", "Example", "Assistant"],
+        ["--url"],
+      ),
+    ).toBe("Example Assistant");
+  });
+
+  test("returns undefined when no target is present", () => {
+    expect(parseAssistantTargetArg(["--verbose"])).toBeUndefined();
+  });
+});

package/src/__tests__/config-utils.test.ts

@@ -1,7 +1,11 @@
 import { readFileSync, rmSync } from "fs";
 import { describe, expect, test } from "bun:test";
 
-import { buildNestedConfig, writeInitialConfig } from "../lib/config-utils.js";
+import {
+  buildHatchConfigValues,
+  buildNestedConfig,
+  writeInitialConfig,
+} from "../lib/config-utils.js";
 
 function readInitialConfig(
   configValues: Record<string, string>,
@@ -32,6 +36,32 @@ describe("config-utils", () => {
     });
   });
 
+  test("buildHatchConfigValues adds the default hatch provider when no config exists", () => {
+    expect(buildHatchConfigValues({}, "anthropic")).toEqual({
+      "llm.default.provider": "anthropic",
+    });
+  });
+
+  test("buildHatchConfigValues preserves explicit provider config", () => {
+    expect(
+      buildHatchConfigValues(
+        {
+          "llm.default.provider": "openai",
+          "llm.default.model": "gpt-5.4",
+        },
+        "anthropic",
+      ),
+    ).toEqual({
+      "llm.default.provider": "openai",
+      "llm.default.model": "gpt-5.4",
+    });
+  });
+
+  test("buildHatchConfigValues skips internal hatches without provider setup", () => {
+    expect(buildHatchConfigValues({}, undefined)).toEqual({});
+    expect(buildHatchConfigValues({}, null)).toEqual({});
+  });
+
   test("writeInitialConfig does not add a mainAgent callSite for Anthropic defaults", () => {
     expect(
       readInitialConfig({

package/src/__tests__/hatch-provider-secrets.test.ts

@@ -0,0 +1,284 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  configureHatchProviderApiKey,
+  resolveHatchProvider,
+  type ProviderSecretFetch,
+} from "../lib/provider-secrets.js";
+
+interface RecordedFetchCall {
+  url: string;
+  init?: RequestInit;
+  body: unknown;
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function makeFetch(responses: Response[]): {
+  calls: RecordedFetchCall[];
+  fetchImpl: ProviderSecretFetch;
+} {
+  const calls: RecordedFetchCall[] = [];
+  const fetchImpl: ProviderSecretFetch = async (input, init) => {
+    calls.push({
+      url: String(input),
+      init,
+      body: typeof init?.body === "string" ? JSON.parse(init.body) : init?.body,
+    });
+    const response = responses.shift();
+    if (!response) {
+      throw new Error("Unexpected fetch call.");
+    }
+    return response;
+  };
+
+  return { calls, fetchImpl };
+}
+
+describe("hatch provider secrets", () => {
+  test("defaults hatch provider setup to Anthropic", () => {
+    expect(resolveHatchProvider({})).toBe("anthropic");
+  });
+
+  test("uses llm.default.provider override for hatch provider setup", () => {
+    expect(resolveHatchProvider({ "llm.default.provider": "openai" })).toBe(
+      "openai",
+    );
+  });
+
+  test("uses active profile provider for hatch provider setup", () => {
+    expect(
+      resolveHatchProvider({
+        "llm.activeProfile": "work",
+        "llm.profiles.work.provider": "openai",
+      }),
+    ).toBe("openai");
+  });
+
+  test("infers active profile provider from model for hatch provider setup", () => {
+    expect(
+      resolveHatchProvider({
+        "llm.activeProfile": "work",
+        "llm.profiles.work.model": "gpt-5.4",
+      }),
+    ).toBe("openai");
+  });
+
+  test("active profile provider wins over main agent call-site provider", () => {
+    expect(
+      resolveHatchProvider({
+        "llm.activeProfile": "work",
+        "llm.profiles.work.provider": "openai",
+        "llm.callSites.mainAgent.provider": "gemini",
+      }),
+    ).toBe("openai");
+  });
+
+  test("uses default provider before static main agent call-site provider", () => {
+    expect(
+      resolveHatchProvider({
+        "llm.default.provider": "anthropic",
+        "llm.callSites.mainAgent.provider": "gemini",
+      }),
+    ).toBe("anthropic");
+  });
+
+  test("uses default provider before static main agent call-site profile", () => {
+    expect(
+      resolveHatchProvider({
+        "llm.default.provider": "anthropic",
+        "llm.callSites.mainAgent.profile": "work",
+        "llm.profiles.work.provider": "openai",
+      }),
+    ).toBe("anthropic");
+  });
+
+  test("uses main agent call-site provider when no hatch default exists", () => {
+    expect(
+      resolveHatchProvider({
+        "llm.callSites.mainAgent.provider": "gemini",
+      }),
+    ).toBe("gemini");
+  });
+
+  test("uses main agent call-site profile when no hatch default exists", () => {
+    expect(
+      resolveHatchProvider({
+        "llm.callSites.mainAgent.profile": "work",
+        "llm.profiles.work.provider": "openai",
+      }),
+    ).toBe("openai");
+  });
+
+  test("infers default provider from model before falling back to Anthropic", () => {
+    expect(
+      resolveHatchProvider({ "llm.default.model": "gemini-2.5-flash" }),
+    ).toBe("gemini");
+  });
+
+  test("skips hatch provider setup for ollama", () => {
+    expect(
+      resolveHatchProvider({ "llm.default.provider": "ollama" }),
+    ).toBeNull();
+  });
+
+  test("skips hatch provider setup for active Ollama profile", () => {
+    expect(
+      resolveHatchProvider({
+        "llm.activeProfile": "local",
+        "llm.profiles.local.model": "llama3.2",
+      }),
+    ).toBeNull();
+  });
+
+  test("rejects unsupported hatch providers before hatch starts", () => {
+    expect(() =>
+      resolveHatchProvider({ "llm.default.provider": "custom" }),
+    ).toThrow("supported API-key setup flow");
+  });
+
+  test("configures default Anthropic credentials from the environment", async () => {
+    const { calls, fetchImpl } = makeFetch([
+      jsonResponse({ found: false }),
+      jsonResponse({ success: true }),
+    ]);
+    const logs: string[] = [];
+
+    await configureHatchProviderApiKey({
+      gatewayUrl: "http://127.0.0.1:7830",
+      provider: resolveHatchProvider({}),
+      bearerToken: "guardian-token",
+      env: { ANTHROPIC_API_KEY: "test-anthropic-key" },
+      fetchImpl,
+      log: (message) => logs.push(message),
+    });
+
+    expect(calls).toHaveLength(2);
+    expect(calls[0].body).toEqual({
+      type: "api_key",
+      name: "anthropic",
+      reveal: false,
+    });
+    expect(calls[0].init?.headers).toMatchObject({
+      Authorization: "Bearer guardian-token",
+    });
+    expect(calls[1].body).toEqual({
+      type: "api_key",
+      name: "anthropic",
+      value: "test-anthropic-key",
+    });
+    expect(logs.join("\n")).toContain(
+      "Configured Anthropic credentials from ANTHROPIC_API_KEY.",
+    );
+    expect(logs.join("\n")).not.toContain("test-anthropic-key");
+  });
+
+  test("uses OpenAI override and skips prompt when credentials already exist", async () => {
+    const { calls, fetchImpl } = makeFetch([jsonResponse({ found: true })]);
+    const logs: string[] = [];
+    let prompted = false;
+
+    await configureHatchProviderApiKey({
+      gatewayUrl: "http://127.0.0.1:7830",
+      provider: resolveHatchProvider({ "llm.default.provider": "openai" }),
+      bearerToken: "guardian-token",
+      env: {},
+      fetchImpl,
+      prompt: async () => {
+        prompted = true;
+        return "unused";
+      },
+      log: (message) => logs.push(message),
+    });
+
+    expect(prompted).toBe(false);
+    expect(calls).toHaveLength(1);
+    expect(calls[0].body).toEqual({
+      type: "api_key",
+      name: "openai",
+      reveal: false,
+    });
+    expect(logs.join("\n")).toContain(
+      "Provider credentials already configured for OpenAI.",
+    );
+  });
+
+  test("uses active profile provider when selecting environment credential", async () => {
+    const { calls, fetchImpl } = makeFetch([
+      jsonResponse({ found: false }),
+      jsonResponse({ success: true }),
+    ]);
+
+    await configureHatchProviderApiKey({
+      gatewayUrl: "http://127.0.0.1:7830",
+      provider: resolveHatchProvider({
+        "llm.activeProfile": "work",
+        "llm.profiles.work.provider": "openai",
+      }),
+      bearerToken: "guardian-token",
+      env: { OPENAI_API_KEY: "test-openai-key" },
+      fetchImpl,
+      log: () => {},
+    });
+
+    expect(calls[0].body).toEqual({
+      type: "api_key",
+      name: "openai",
+      reveal: false,
+    });
+    expect(calls[1].body).toEqual({
+      type: "api_key",
+      name: "openai",
+      value: "test-openai-key",
+    });
+  });
+
+  test("keeps hatch recoverable when provider credentials are missing in a non-interactive shell", async () => {
+    const { fetchImpl } = makeFetch([jsonResponse({ found: false })]);
+    const logs: string[] = [];
+
+    await configureHatchProviderApiKey({
+      gatewayUrl: "http://127.0.0.1:7830",
+      provider: "anthropic",
+      env: {},
+      fetchImpl,
+      stdinIsTTY: false,
+      log: (message) => logs.push(message),
+    });
+
+    const output = logs.join("\n");
+    expect(output).toContain("Provider credential setup skipped");
+    expect(output).toContain("Missing ANTHROPIC_API_KEY");
+    expect(output).toContain("vellum setup --provider anthropic");
+  });
+
+  test("surfaces gateway validation failures without throwing or logging the key", async () => {
+    const { fetchImpl } = makeFetch([
+      jsonResponse({ found: false }),
+      jsonResponse(
+        { error: { message: "API key is invalid or expired." } },
+        400,
+      ),
+    ]);
+    const logs: string[] = [];
+
+    await configureHatchProviderApiKey({
+      gatewayUrl: "http://127.0.0.1:7830",
+      provider: "anthropic",
+      env: { ANTHROPIC_API_KEY: "test-anthropic-key" },
+      fetchImpl,
+      log: (message) => logs.push(message),
+    });
+
+    const output = logs.join("\n");
+    expect(output).toContain("Provider credential setup failed");
+    expect(output).toContain("API key is invalid or expired.");
+    expect(output).toContain("vellum setup --provider anthropic");
+    expect(output).not.toContain("test-anthropic-key");
+  });
+});