feat: add interactive API key prompt for missing LLM credentials

Author: tomcant

README.md

@@ -64,13 +64,18 @@ Install dependencies:
 bun install
 ```
 
-Set your API key and start an interactive chat:
+Start an interactive chat:
 
 ```sh
-export ANTHROPIC_API_KEY="sk-ant-..."
 bun run src/index.ts
 ```
 
+The agent prompts for your Anthropic API key on launch if it isn't already set. To skip the prompt, set it in your environment beforehand:
+
+```sh
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
 ### Standalone binary
 
 Compile a self-contained executable (bundles the Bun runtime and all dependencies):

src/adapters/llm/index.ts

@@ -6,10 +6,11 @@ type LlmFromEnv = (env: Env, systemPrompt?: string) => LlmClient | null;
 
 const adapters: LlmFromEnv[] = [anthropicFromEnv];
 
-export function resolveLlmClient(systemPrompt?: string, env: Env = process.env): LlmClient {
+// Returns the first provider whose keys are present in the environment.
+export function resolveLlmClient(systemPrompt?: string, env: Env = process.env): LlmClient | null {
   for (const fromEnv of adapters) {
     const client = fromEnv(env, systemPrompt);
     if (client) return client;
   }
-  throw new Error("No LLM provider configured. Hint: set `ANTHROPIC_API_KEY`");
+  return null;
 }

src/index.ts

@@ -7,6 +7,7 @@ import { createDemoAgent } from "./demo";
 import systemPrompt from "./prompt.md";
 import { App } from "./tui/App.tsx";
 import { initColorScheme } from "./tui/color-scheme.ts";
+import { ApiKeyPrompt } from "./tui/components/ApiKeyPrompt.tsx";
 
 await initColorScheme();
 
@@ -21,7 +22,9 @@ for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
 }
 
 const agent =
-  process.env.DEMO === "1" ? await createDemoAgent() : await createAgent(resolveLlmClientOrExit());
+  process.env.DEMO === "1"
+    ? await createDemoAgent()
+    : await createAgent(await resolveLlmClientInteractive());
 
 const { waitUntilExit } = render(createElement(App, { agent }), { exitOnCtrlC: true });
 try {
@@ -30,24 +33,60 @@ try {
   leaveAltScreen();
 }
 
-function resolveLlmClientOrExit() {
-  try {
-    return resolveLlmClient(systemPrompt);
-  } catch (error) {
-    leaveAltScreen();
-    console.error(`Error: ${error instanceof Error ? error.message : error}`);
-    process.exit(1);
-  }
+async function resolveLlmClientInteractive() {
+  const configured = resolveLlmClient(systemPrompt);
+  if (configured) return configured;
+
+  const key = await promptForApiKey("ANTHROPIC_API_KEY");
+  process.env.ANTHROPIC_API_KEY = key;
+
+  clearScreen();
+
+  const client = resolveLlmClient(systemPrompt);
+  if (client) return client;
+
+  leaveAltScreen();
+  console.error("Error: could not initialise an LLM client from the provided key.");
+  process.exit(1);
+}
+
+function promptForApiKey(envVarName: string): Promise<string> {
+  return new Promise((resolve) => {
+    let submitted = false;
+    const { unmount, waitUntilExit } = render(
+      createElement(ApiKeyPrompt, {
+        envVarName,
+        onSubmit: (key: string) => {
+          submitted = true;
+          unmount();
+          resolve(key);
+        },
+      }),
+      { exitOnCtrlC: true },
+    );
+    void waitUntilExit().then(() => {
+      if (!submitted) {
+        leaveAltScreen();
+        process.exit(0);
+      }
+    });
+  });
 }
 
 function enterAltScreen() {
   if (!process.stdout.isTTY) return;
-  writeSync(process.stdout.fd, "\x1b[?1049h\x1b[2J\x1b[H");
+  writeSync(process.stdout.fd, "\x1b[?1049h");
   altScreenActive = true;
+  clearScreen();
 }
 
 function leaveAltScreen() {
   if (!altScreenActive) return;
   writeSync(process.stdout.fd, "\x1b[?1049l\x1b[?25h");
   altScreenActive = false;
 }
+
+function clearScreen() {
+  if (!process.stdout.isTTY) return;
+  writeSync(process.stdout.fd, "\x1b[2J\x1b[H");
+}

src/tui/color-scheme.ts

@@ -38,7 +38,7 @@ function detectColorScheme(): Promise<ColorScheme> {
   return new Promise<ColorScheme>((resolve) => {
     const timeout = setTimeout(() => {
       restore();
-      resolve("dark");
+      settle("dark");
     }, 200);
 
     let response = "";
@@ -48,7 +48,7 @@ function detectColorScheme(): Promise<ColorScheme> {
       if (!DA1_RESPONSE.test(response)) return;
 
       restore();
-      resolve(classify(response));
+      settle(classify(response));
     }
 
     function restore() {
@@ -58,6 +58,10 @@ function detectColorScheme(): Promise<ColorScheme> {
       process.stdin.pause();
     }
 
+    function settle(scheme: ColorScheme) {
+      setTimeout(() => resolve(scheme), 0);
+    }
+
     process.stdin.setRawMode(true);
     process.stdin.resume();
     process.stdin.on("data", onData);

src/tui/components/ApiKeyPrompt.tsx

@@ -0,0 +1,44 @@
+import { PasswordInput } from "@inkjs/ui";
+import { Box, Text } from "ink";
+import { isLightScheme } from "../color-scheme.ts";
+import { theme } from "../theme.ts";
+
+type ApiKeyPromptProps = {
+  envVarName: string;
+  onSubmit: (key: string) => void;
+};
+
+export function ApiKeyPrompt({ envVarName, onSubmit }: ApiKeyPromptProps) {
+  const handleSubmit = (value: string) => {
+    const key = value.trim();
+    if (key === "") return;
+    onSubmit(key);
+  };
+
+  return (
+    <Box flexDirection="column" gap={1}>
+      <Box paddingX={1}>
+        <Text>
+          <Text dimColor>
+            No LLM provider is configured. Paste an Anthropic API key to continue, or press{" "}
+          </Text>
+          <Text color={theme.accent}>Ctrl+C</Text>
+          <Text dimColor> to quit.</Text>
+        </Text>
+      </Box>
+      <Box
+        paddingX={1}
+        borderStyle="round"
+        borderColor={theme.accent}
+        borderDimColor={!isLightScheme()}
+      >
+        <Text color={theme.accent} bold>
+          {`${envVarName} `}
+        </Text>
+        <Box flexGrow={1}>
+          <PasswordInput placeholder="sk-ant-..." onSubmit={handleSubmit} />
+        </Box>
+      </Box>
+    </Box>
+  );
+}

tests/adapters/llm/resolve.test.ts

@@ -5,8 +5,8 @@ describe("LLM client resolution", () => {
   test("returns an Anthropic client when ANTHROPIC_API_KEY is set", () => {
     const client = resolveLlmClient(undefined, { ANTHROPIC_API_KEY: "test-key" });
 
-    expect(client.provider).toBe("anthropic");
-    expect(client.model).toBe("claude-sonnet-4-6");
+    expect(client?.provider).toBe("anthropic");
+    expect(client?.model).toBe("claude-sonnet-4-6");
   });
 
   test("honours the MODEL override", () => {
@@ -15,10 +15,10 @@ describe("LLM client resolution", () => {
       MODEL: "claude-opus-4-8",
     });
 
-    expect(client.model).toBe("claude-opus-4-8");
+    expect(client?.model).toBe("claude-opus-4-8");
   });
 
-  test("throws an error when no provider is configured", () => {
-    expect(() => resolveLlmClient(undefined, {})).toThrow("No LLM provider configured");
+  test("returns null when no provider is configured", () => {
+    expect(resolveLlmClient(undefined, {})).toBeNull();
   });
 });