@vellumai/cli 0.8.2 → 0.8.3

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.3",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

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");
+  });
+});

package/src/__tests__/setup.test.ts

@@ -75,7 +75,10 @@ function writeLockfile(entry: AssistantEntry): void {
 }
 
 function installFetchStub(
-  options: { refreshedToken?: GuardianTokenData } = {},
+  options: {
+    leasedToken?: GuardianTokenData;
+    refreshedToken?: GuardianTokenData;
+  } = {},
 ) {
   fetchCalls = [];
   globalThis.fetch = (async (input, init) => {
@@ -103,6 +106,19 @@ function installFetchStub(
       });
     }
 
+    if (url.endsWith("/v1/guardian/init")) {
+      if (!options.leasedToken) {
+        return new Response(JSON.stringify({ error: "not allowed" }), {
+          status: 401,
+          headers: { "Content-Type": "application/json" },
+        });
+      }
+      return new Response(JSON.stringify(options.leasedToken), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+
     if (url.endsWith("/v1/secrets/read")) {
       return new Response(JSON.stringify({ found: false }), {
         status: 200,
@@ -209,6 +225,54 @@ describe("setup command", () => {
     );
   });
 
+  test("leases a guardian token for local assistants when no token exists", async () => {
+    process.env.ANTHROPIC_API_KEY = "test-anthropic-key";
+    writeLockfile({
+      assistantId: "assistant-123",
+      runtimeUrl: "http://runtime.example",
+      localUrl: "http://127.0.0.1:3000",
+      cloud: "local",
+    });
+    installFetchStub({
+      leasedToken: guardianTokenFixture({
+        accessToken: "leased-guardian-token",
+      }),
+    });
+
+    await setup();
+
+    expect(fetchCalls[0].url).toBe("http://127.0.0.1:3000/v1/guardian/init");
+    expect(fetchCalls[1].url).toBe("http://127.0.0.1:3000/v1/secrets/read");
+    expect(fetchCalls[1].headers.get("Authorization")).toBe(
+      "Bearer leased-guardian-token",
+    );
+  });
+
+  test("uses saved bootstrap secret when leasing a Docker guardian token", async () => {
+    process.env.ANTHROPIC_API_KEY = "test-anthropic-key";
+    writeLockfile({
+      assistantId: "assistant-123",
+      runtimeUrl: "http://localhost:7831",
+      cloud: "docker",
+      guardianBootstrapSecret: "test-bootstrap-secret",
+    });
+    installFetchStub({
+      leasedToken: guardianTokenFixture({
+        accessToken: "leased-docker-token",
+      }),
+    });
+
+    await setup();
+
+    expect(fetchCalls[0].url).toBe("http://localhost:7831/v1/guardian/init");
+    expect(fetchCalls[0].headers.get("x-bootstrap-secret")).toBe(
+      "test-bootstrap-secret",
+    );
+    expect(fetchCalls[1].headers.get("Authorization")).toBe(
+      "Bearer leased-docker-token",
+    );
+  });
+
   test("falls back to runtime URL and lockfile bearer token", async () => {
     process.env.ANTHROPIC_API_KEY = "test-anthropic-key";
     writeLockfile({

package/src/__tests__/teleport.test.ts

@@ -779,6 +779,7 @@ describe("resolveOrHatchTarget", () => {
       "new-one",
       false,
       {},
+      { setupProviderCredentials: false },
     );
     expect(result).toBe(newEntry);
   });