kairn-cli 1.7.0 → 1.8.0

package/dist/cli.js

@@ -1,6 +1,6 @@
 // src/cli.ts
-import { Command as Command10 } from "commander";
-import chalk12 from "chalk";
+import { Command as Command11 } from "commander";
+import chalk14 from "chalk";
 
 // src/commands/init.ts
 import { Command } from "commander";
@@ -90,7 +90,7 @@ var ui = {
   // Key-value pairs
   kv: (key, value) => `  ${chalk.cyan(key.padEnd(14))} ${value}`,
   // File list
-  file: (path13) => chalk.dim(`    ${path13}`),
+  file: (path15) => chalk.dim(`    ${path15}`),
   // Tool display
   tool: (name, reason) => `    ${warm("\u25CF")} ${chalk.bold(name)}
       ${chalk.dim(reason)}`,
@@ -339,7 +339,7 @@ var initCommand = new Command("init").description("Set up Kairn with your API ke
 // src/commands/describe.ts
 import { Command as Command2 } from "commander";
 import { input, confirm } from "@inquirer/prompts";
-import chalk4 from "chalk";
+import chalk5 from "chalk";
 import ora from "ora";
 
 // src/compiler/compile.ts
@@ -926,25 +926,39 @@ function isCodeProject(spec) {
   const commands = spec.harness.commands ?? {};
   return "status" in commands || "test" in commands;
 }
-function resolveSettings(spec) {
+var ENV_LOADER_HOOK = {
+  matcher: "",
+  hooks: [{
+    type: "command",
+    command: 'if [ -f .env ] && [ -n "$CLAUDE_ENV_FILE" ]; then grep -v "^#" .env | grep -v "^$" | grep "=" >> "$CLAUDE_ENV_FILE"; fi'
+  }]
+};
+function resolveSettings(spec, options) {
   const settings = spec.harness.settings;
-  if (!settings || Object.keys(settings).length === 0) return null;
-  if ("statusLine" in settings) return settings;
-  if (isCodeProject(spec)) {
-    return { ...settings, statusLine: STATUS_LINE };
-  }
-  return settings;
+  const base = settings && Object.keys(settings).length > 0 ? { ...settings } : {};
+  if (!("statusLine" in base) && isCodeProject(spec)) {
+    base.statusLine = STATUS_LINE;
+  }
+  if (options?.hasEnvVars) {
+    const hooks = base.hooks ?? {};
+    const sessionStart = hooks.SessionStart ?? [];
+    sessionStart.push(ENV_LOADER_HOOK);
+    hooks.SessionStart = sessionStart;
+    base.hooks = hooks;
+  }
+  if (Object.keys(base).length === 0) return null;
+  return base;
 }
 async function writeFile(filePath, content) {
   await fs5.mkdir(path5.dirname(filePath), { recursive: true });
   await fs5.writeFile(filePath, content, "utf-8");
 }
-function buildFileMap(spec) {
+function buildFileMap(spec, options) {
   const files = /* @__PURE__ */ new Map();
   if (spec.harness.claude_md) {
     files.set(".claude/CLAUDE.md", spec.harness.claude_md);
   }
-  const resolvedSettings = resolveSettings(spec);
+  const resolvedSettings = resolveSettings(spec, options);
   if (resolvedSettings) {
     files.set(".claude/settings.json", JSON.stringify(resolvedSettings, null, 2));
   }
@@ -981,7 +995,7 @@ function buildFileMap(spec) {
   }
   return files;
 }
-async function writeEnvironment(spec, targetDir) {
+async function writeEnvironment(spec, targetDir, options) {
   const claudeDir = path5.join(targetDir, ".claude");
   const written = [];
   if (spec.harness.claude_md) {
@@ -989,7 +1003,7 @@ async function writeEnvironment(spec, targetDir) {
     await writeFile(p, spec.harness.claude_md);
     written.push(".claude/CLAUDE.md");
   }
-  const resolvedSettings = resolveSettings(spec);
+  const resolvedSettings = resolveSettings(spec, options);
   if (resolvedSettings) {
     const p = path5.join(claudeDir, "settings.json");
     await writeFile(p, JSON.stringify(resolvedSettings, null, 2));
@@ -1192,6 +1206,114 @@ async function writeHermesEnvironment(spec, registry) {
   return written;
 }
 
+// src/secrets.ts
+import { password as password2 } from "@inquirer/prompts";
+import chalk4 from "chalk";
+import fs7 from "fs/promises";
+import path7 from "path";
+async function collectAndWriteKeys(envSetup, targetDir) {
+  console.log(ui.section("API Keys"));
+  console.log(
+    chalk4.dim("  Some tools need API keys. Enter them now or press Enter to skip.\n")
+  );
+  const envEntries = [
+    "# Generated by Kairn \u2014 API keys for MCP servers",
+    "# Do NOT commit this file to git",
+    ""
+  ];
+  let keysEntered = 0;
+  let keysSkipped = 0;
+  const seen = /* @__PURE__ */ new Set();
+  for (const env of envSetup) {
+    if (seen.has(env.envVar)) continue;
+    seen.add(env.envVar);
+    console.log(chalk4.bold(`  ${env.envVar}`) + chalk4.dim(` (${env.toolName})`));
+    if (env.signupUrl) {
+      console.log(chalk4.dim(`    Get one at: ${env.signupUrl}`));
+    }
+    const value = await password2({
+      message: env.envVar,
+      mask: "\u2022"
+    });
+    if (value && value.trim()) {
+      envEntries.push(`${env.envVar}=${value.trim()}`);
+      console.log(chalk4.green("  \u2713 saved\n"));
+      keysEntered++;
+    } else {
+      envEntries.push(`${env.envVar}=`);
+      console.log(chalk4.dim("  (skipped)\n"));
+      keysSkipped++;
+    }
+  }
+  const envPath = path7.join(targetDir, ".env");
+  await fs7.writeFile(envPath, envEntries.join("\n") + "\n", "utf-8");
+  await ensureGitignoreEntry(targetDir, ".env");
+  console.log(chalk4.green(`  \u2713 ${keysEntered} key(s) saved to .env (gitignored)`));
+  if (keysSkipped > 0) {
+    console.log(chalk4.dim("  Skipped keys can be added later: kairn keys"));
+  }
+  return { keysEntered, keysSkipped, envPath };
+}
+async function writeEmptyEnvFile(envSetup, targetDir) {
+  const envEntries = [
+    "# Generated by Kairn \u2014 API keys for MCP servers",
+    "# Do NOT commit this file to git",
+    ""
+  ];
+  const seen = /* @__PURE__ */ new Set();
+  for (const env of envSetup) {
+    if (seen.has(env.envVar)) continue;
+    seen.add(env.envVar);
+    envEntries.push(`${env.envVar}=`);
+  }
+  const envPath = path7.join(targetDir, ".env");
+  await fs7.writeFile(envPath, envEntries.join("\n") + "\n", "utf-8");
+  await ensureGitignoreEntry(targetDir, ".env");
+}
+async function ensureGitignoreEntry(targetDir, entry) {
+  const gitignorePath = path7.join(targetDir, ".gitignore");
+  let gitignore = "";
+  try {
+    gitignore = await fs7.readFile(gitignorePath, "utf-8");
+  } catch {
+  }
+  if (!gitignore.split("\n").some((line) => line.trim() === entry)) {
+    const separator = gitignore.length > 0 && !gitignore.endsWith("\n") ? "\n" : "";
+    await fs7.writeFile(gitignorePath, gitignore + separator + entry + "\n", "utf-8");
+  }
+}
+async function readEnvFile(targetDir) {
+  const envPath = path7.join(targetDir, ".env");
+  const entries = /* @__PURE__ */ new Map();
+  try {
+    const content = await fs7.readFile(envPath, "utf-8");
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const eqIndex = trimmed.indexOf("=");
+      if (eqIndex === -1) continue;
+      const key = trimmed.slice(0, eqIndex);
+      const value = trimmed.slice(eqIndex + 1);
+      entries.set(key, value);
+    }
+  } catch {
+  }
+  return entries;
+}
+async function detectRequiredEnvVars(targetDir) {
+  const mcpPath = path7.join(targetDir, ".mcp.json");
+  const envVars = /* @__PURE__ */ new Set();
+  try {
+    const content = await fs7.readFile(mcpPath, "utf-8");
+    const matches = content.matchAll(/\$\{([A-Z_][A-Z0-9_]*)\}/g);
+    for (const match of matches) {
+      envVars.add(match[1]);
+    }
+  } catch {
+  }
+  return [...envVars];
+}
+
 // src/commands/describe.ts
 var describeCommand = new Command2("describe").description("Describe your workflow and generate a Claude Code environment").argument("[intent]", "What you want your agent to do").option("-y, --yes", "Skip confirmation prompt").option("-q, --quick", "Skip clarification questions").option("--runtime <runtime>", "Target runtime (claude-code or hermes)", "claude-code").action(async (intentArg, options) => {
   printFullBanner("The Agent Environment Compiler");
@@ -1200,7 +1322,7 @@ var describeCommand = new Command2("describe").description("Describe your workfl
     console.log(
       ui.errorBox(
         "No configuration found",
-        `Run ${chalk4.bold("kairn init")} to set up your API key.`
+        `Run ${chalk5.bold("kairn init")} to set up your API key.`
       )
     );
     process.exit(1);
@@ -1209,14 +1331,14 @@ var describeCommand = new Command2("describe").description("Describe your workfl
     message: "What do you want your agent to do?"
   });
   if (!intentRaw.trim()) {
-    console.log(chalk4.red("\n  No description provided. Aborting.\n"));
+    console.log(chalk5.red("\n  No description provided. Aborting.\n"));
     process.exit(1);
   }
   let finalIntent = intentRaw;
   if (!options.quick) {
     console.log(ui.section("Clarification"));
-    console.log(chalk4.dim("  Let me understand your project better."));
-    console.log(chalk4.dim("  Press Enter to accept the suggestion, or type your own answer.\n"));
+    console.log(chalk5.dim("  Let me understand your project better."));
+    console.log(chalk5.dim("  Press Enter to accept the suggestion, or type your own answer.\n"));
     let clarifications = [];
     try {
       clarifications = await generateClarifications(intentRaw);
@@ -1249,7 +1371,7 @@ ${clarificationLines}`;
   } catch (err) {
     spinner.fail("Compilation failed");
     const msg = err instanceof Error ? err.message : String(err);
-    console.log(chalk4.red(`
+    console.log(chalk5.red(`
   ${msg}
 `));
     process.exit(1);
@@ -1279,7 +1401,7 @@ ${clarificationLines}`;
     default: true
   });
   if (!proceed) {
-    console.log(chalk4.dim("\n  Aborted. Environment saved to ~/.kairn/envs/\n"));
+    console.log(chalk5.dim("\n  Aborted. Environment saved to ~/.kairn/envs/\n"));
     return;
   }
   const targetDir = process.cwd();
@@ -1288,25 +1410,24 @@ ${clarificationLines}`;
     await writeHermesEnvironment(spec, registry);
     console.log("\n" + ui.success("Environment written for Hermes"));
     console.log(
-      chalk4.cyan("\n  Ready! Run ") + chalk4.bold("hermes") + chalk4.cyan(" to start.\n")
+      chalk5.cyan("\n  Ready! Run ") + chalk5.bold("hermes") + chalk5.cyan(" to start.\n")
     );
   } else {
-    const written = await writeEnvironment(spec, targetDir);
+    const hasEnvVars = summary.envSetup.length > 0;
+    const written = await writeEnvironment(spec, targetDir, { hasEnvVars });
     console.log(ui.section("Files Written"));
     console.log("");
     for (const file of written) {
       console.log(ui.file(file));
     }
-    if (summary.envSetup.length > 0) {
-      console.log(ui.section("Setup Required"));
-      console.log("");
-      const seen = /* @__PURE__ */ new Set();
-      for (const env of summary.envSetup) {
-        if (seen.has(env.envVar)) continue;
-        seen.add(env.envVar);
-        console.log(ui.envVar(env.envVar, env.description, env.signupUrl));
-        console.log("");
+    if (hasEnvVars) {
+      if (options.quick) {
+        await writeEmptyEnvFile(summary.envSetup, targetDir);
+        console.log(ui.success("Empty .env written (gitignored) \u2014 fill in keys later: kairn keys"));
+      } else {
+        await collectAndWriteKeys(summary.envSetup, targetDir);
       }
+      console.log("");
     }
     if (summary.pluginCommands.length > 0) {
       console.log(ui.section("Plugins"));
@@ -1324,28 +1445,28 @@ ${clarificationLines}`;
 
 // src/commands/list.ts
 import { Command as Command3 } from "commander";
-import chalk5 from "chalk";
-import fs7 from "fs/promises";
-import path7 from "path";
+import chalk6 from "chalk";
+import fs8 from "fs/promises";
+import path8 from "path";
 var listCommand = new Command3("list").description("Show saved environments").action(async () => {
   printCompactBanner();
   const envsDir = getEnvsDir();
   let files;
   try {
-    files = await fs7.readdir(envsDir);
+    files = await fs8.readdir(envsDir);
   } catch {
-    console.log(chalk5.dim("  No environments yet. Run ") + chalk5.bold("kairn describe") + chalk5.dim(" to create one.\n"));
+    console.log(chalk6.dim("  No environments yet. Run ") + chalk6.bold("kairn describe") + chalk6.dim(" to create one.\n"));
     return;
   }
   const jsonFiles = files.filter((f) => f.endsWith(".json"));
   if (jsonFiles.length === 0) {
-    console.log(chalk5.dim("  No environments yet. Run ") + chalk5.bold("kairn describe") + chalk5.dim(" to create one.\n"));
+    console.log(chalk6.dim("  No environments yet. Run ") + chalk6.bold("kairn describe") + chalk6.dim(" to create one.\n"));
     return;
   }
   let first = true;
   for (const file of jsonFiles) {
     try {
-      const data = await fs7.readFile(path7.join(envsDir, file), "utf-8");
+      const data = await fs8.readFile(path8.join(envsDir, file), "utf-8");
       const spec = JSON.parse(data);
       const date = new Date(spec.created_at).toLocaleDateString();
       const toolCount = spec.tools?.length ?? 0;
@@ -1353,10 +1474,10 @@ var listCommand = new Command3("list").description("Show saved environments").ac
         console.log(ui.divider());
       }
       first = false;
-      console.log(ui.kv("Name", chalk5.bold(spec.name)));
+      console.log(ui.kv("Name", chalk6.bold(spec.name)));
       console.log(ui.kv("Description", spec.description));
       console.log(ui.kv("Date", `${date} \xB7 ${toolCount} tools`));
-      console.log(ui.kv("ID", chalk5.dim(spec.id)));
+      console.log(ui.kv("ID", chalk6.dim(spec.id)));
       console.log("");
     } catch {
     }
@@ -1365,9 +1486,9 @@ var listCommand = new Command3("list").description("Show saved environments").ac
 
 // src/commands/activate.ts
 import { Command as Command4 } from "commander";
-import chalk6 from "chalk";
-import fs8 from "fs/promises";
-import path8 from "path";
+import chalk7 from "chalk";
+import fs9 from "fs/promises";
+import path9 from "path";
 var activateCommand = new Command4("activate").description("Re-deploy a saved environment to the current directory").argument("<env_id>", "Environment ID (from kairn list)").action(async (envId) => {
   printCompactBanner();
   const envsDir = getEnvsDir();
@@ -1377,7 +1498,7 @@ var activateCommand = new Command4("activate").description("Re-deploy a saved en
   let fromTemplate = false;
   let envFiles = [];
   try {
-    envFiles = await fs8.readdir(envsDir);
+    envFiles = await fs9.readdir(envsDir);
   } catch {
   }
   match = envFiles.find(
@@ -1388,7 +1509,7 @@ var activateCommand = new Command4("activate").description("Re-deploy a saved en
   } else {
     let templateFiles = [];
     try {
-      templateFiles = await fs8.readdir(templatesDir);
+      templateFiles = await fs9.readdir(templatesDir);
     } catch {
     }
     match = templateFiles.find(
@@ -1399,16 +1520,16 @@ var activateCommand = new Command4("activate").description("Re-deploy a saved en
       fromTemplate = true;
     } else {
       console.log(ui.error(`Environment "${envId}" not found.`));
-      console.log(chalk6.dim("  Run kairn list to see saved environments."));
-      console.log(chalk6.dim("  Run kairn templates to see available templates.\n"));
+      console.log(chalk7.dim("  Run kairn list to see saved environments."));
+      console.log(chalk7.dim("  Run kairn templates to see available templates.\n"));
       process.exit(1);
     }
   }
-  const data = await fs8.readFile(path8.join(sourceDir, match), "utf-8");
+  const data = await fs9.readFile(path9.join(sourceDir, match), "utf-8");
   const spec = JSON.parse(data);
-  const label = fromTemplate ? chalk6.dim(" (template)") : "";
-  console.log(chalk6.cyan(`  Activating: ${spec.name}`) + label);
-  console.log(chalk6.dim(`  ${spec.description}
+  const label = fromTemplate ? chalk7.dim(" (template)") : "";
+  console.log(chalk7.cyan(`  Activating: ${spec.name}`) + label);
+  console.log(chalk7.dim(`  ${spec.description}
 `));
   const targetDir = process.cwd();
   const written = await writeEnvironment(spec, targetDir);
@@ -1421,22 +1542,22 @@ var activateCommand = new Command4("activate").description("Re-deploy a saved en
 
 // src/commands/update-registry.ts
 import { Command as Command5 } from "commander";
-import chalk7 from "chalk";
-import fs9 from "fs/promises";
-import path9 from "path";
+import chalk8 from "chalk";
+import fs10 from "fs/promises";
+import path10 from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 var REGISTRY_URL = "https://raw.githubusercontent.com/ashtonperlroth/kairn/main/src/registry/tools.json";
 async function getLocalRegistryPath() {
   const __filename3 = fileURLToPath3(import.meta.url);
-  const __dirname3 = path9.dirname(__filename3);
+  const __dirname3 = path10.dirname(__filename3);
   const candidates = [
-    path9.resolve(__dirname3, "../registry/tools.json"),
-    path9.resolve(__dirname3, "../src/registry/tools.json"),
-    path9.resolve(__dirname3, "../../src/registry/tools.json")
+    path10.resolve(__dirname3, "../registry/tools.json"),
+    path10.resolve(__dirname3, "../src/registry/tools.json"),
+    path10.resolve(__dirname3, "../../src/registry/tools.json")
   ];
   for (const candidate of candidates) {
     try {
-      await fs9.access(candidate);
+      await fs10.access(candidate);
       return candidate;
     } catch {
       continue;
@@ -1447,15 +1568,15 @@ async function getLocalRegistryPath() {
 var updateRegistryCommand = new Command5("update-registry").description("Fetch the latest tool registry from GitHub").option("--url <url>", "Custom registry URL").action(async (options) => {
   printCompactBanner();
   const url = options.url || REGISTRY_URL;
-  console.log(chalk7.dim(`  Fetching registry from ${url}...`));
+  console.log(chalk8.dim(`  Fetching registry from ${url}...`));
   try {
     const response = await fetch(url);
     if (!response.ok) {
       console.log(
         ui.error(`Failed to fetch registry: ${response.status} ${response.statusText}`)
       );
-      console.log(chalk7.dim("  The remote registry may not be available yet."));
-      console.log(chalk7.dim("  Your local registry is still active.\n"));
+      console.log(chalk8.dim("  The remote registry may not be available yet."));
+      console.log(chalk8.dim("  Your local registry is still active.\n"));
       return;
     }
     const text = await response.text();
@@ -1473,35 +1594,35 @@ var updateRegistryCommand = new Command5("update-registry").description("Fetch t
     const registryPath = await getLocalRegistryPath();
     const backupPath = registryPath + ".bak";
     try {
-      await fs9.copyFile(registryPath, backupPath);
+      await fs10.copyFile(registryPath, backupPath);
     } catch {
     }
-    await fs9.writeFile(registryPath, JSON.stringify(tools, null, 2), "utf-8");
+    await fs10.writeFile(registryPath, JSON.stringify(tools, null, 2), "utf-8");
     console.log(ui.success(`Registry updated: ${tools.length} tools`));
-    console.log(chalk7.dim(`  Saved to: ${registryPath}`));
-    console.log(chalk7.dim(`  Backup: ${backupPath}
+    console.log(chalk8.dim(`  Saved to: ${registryPath}`));
+    console.log(chalk8.dim(`  Backup: ${backupPath}
 `));
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.log(ui.error(`Network error: ${msg}`));
-    console.log(chalk7.dim("  Your local registry is still active.\n"));
+    console.log(chalk8.dim("  Your local registry is still active.\n"));
   }
 });
 
 // src/commands/optimize.ts
 import { Command as Command6 } from "commander";
 import { confirm as confirm2 } from "@inquirer/prompts";
-import chalk8 from "chalk";
+import chalk9 from "chalk";
 import ora2 from "ora";
-import fs11 from "fs/promises";
-import path11 from "path";
+import fs12 from "fs/promises";
+import path12 from "path";
 
 // src/scanner/scan.ts
-import fs10 from "fs/promises";
-import path10 from "path";
+import fs11 from "fs/promises";
+import path11 from "path";
 async function fileExists(p) {
   try {
-    await fs10.access(p);
+    await fs11.access(p);
     return true;
   } catch {
     return false;
@@ -1509,7 +1630,7 @@ async function fileExists(p) {
 }
 async function readJsonSafe(p) {
   try {
-    const data = await fs10.readFile(p, "utf-8");
+    const data = await fs11.readFile(p, "utf-8");
     return JSON.parse(data);
   } catch {
     return null;
@@ -1517,14 +1638,14 @@ async function readJsonSafe(p) {
 }
 async function readFileSafe(p) {
   try {
-    return await fs10.readFile(p, "utf-8");
+    return await fs11.readFile(p, "utf-8");
   } catch {
     return null;
   }
 }
 async function listDirSafe(p) {
   try {
-    const entries = await fs10.readdir(p);
+    const entries = await fs11.readdir(p);
     return entries.filter((e) => !e.startsWith("."));
   } catch {
     return [];
@@ -1576,7 +1697,7 @@ function extractEnvKeys(content) {
   return keys;
 }
 async function scanProject(dir) {
-  const pkg = await readJsonSafe(path10.join(dir, "package.json"));
+  const pkg = await readJsonSafe(path11.join(dir, "package.json"));
   const deps = pkg?.dependencies ? Object.keys(pkg.dependencies) : [];
   const devDeps = pkg?.devDependencies ? Object.keys(pkg.devDependencies) : [];
   const allDeps = [...deps, ...devDeps];
@@ -1604,19 +1725,19 @@ async function scanProject(dir) {
   const framework = detectFramework(allDeps);
   const typescript = keyFiles.includes("tsconfig.json") || allDeps.includes("typescript");
   const testCommand = scripts.test && scripts.test !== 'echo "Error: no test specified" && exit 1' ? scripts.test : null;
-  const hasTests = testCommand !== null || await fileExists(path10.join(dir, "tests")) || await fileExists(path10.join(dir, "__tests__")) || await fileExists(path10.join(dir, "test"));
+  const hasTests = testCommand !== null || await fileExists(path11.join(dir, "tests")) || await fileExists(path11.join(dir, "__tests__")) || await fileExists(path11.join(dir, "test"));
   const buildCommand = scripts.build || null;
   const lintCommand = scripts.lint || null;
-  const hasSrc = await fileExists(path10.join(dir, "src"));
-  const hasDocker = await fileExists(path10.join(dir, "docker-compose.yml")) || await fileExists(path10.join(dir, "Dockerfile"));
-  const hasCi = await fileExists(path10.join(dir, ".github/workflows"));
-  const hasEnvFile = await fileExists(path10.join(dir, ".env")) || await fileExists(path10.join(dir, ".env.example"));
+  const hasSrc = await fileExists(path11.join(dir, "src"));
+  const hasDocker = await fileExists(path11.join(dir, "docker-compose.yml")) || await fileExists(path11.join(dir, "Dockerfile"));
+  const hasCi = await fileExists(path11.join(dir, ".github/workflows"));
+  const hasEnvFile = await fileExists(path11.join(dir, ".env")) || await fileExists(path11.join(dir, ".env.example"));
   let envKeys = [];
-  const envExample = await readFileSafe(path10.join(dir, ".env.example"));
+  const envExample = await readFileSafe(path11.join(dir, ".env.example"));
   if (envExample) {
     envKeys = extractEnvKeys(envExample);
   }
-  const claudeDir = path10.join(dir, ".claude");
+  const claudeDir = path11.join(dir, ".claude");
   const hasClaudeDir = await fileExists(claudeDir);
   let existingClaudeMd = null;
   let existingSettings = null;
@@ -1628,21 +1749,21 @@ async function scanProject(dir) {
   let mcpServerCount = 0;
   let claudeMdLineCount = 0;
   if (hasClaudeDir) {
-    existingClaudeMd = await readFileSafe(path10.join(claudeDir, "CLAUDE.md"));
+    existingClaudeMd = await readFileSafe(path11.join(claudeDir, "CLAUDE.md"));
     if (existingClaudeMd) {
       claudeMdLineCount = existingClaudeMd.split("\n").length;
     }
-    existingSettings = await readJsonSafe(path10.join(claudeDir, "settings.json"));
-    existingMcpConfig = await readJsonSafe(path10.join(dir, ".mcp.json"));
+    existingSettings = await readJsonSafe(path11.join(claudeDir, "settings.json"));
+    existingMcpConfig = await readJsonSafe(path11.join(dir, ".mcp.json"));
     if (existingMcpConfig?.mcpServers) {
       mcpServerCount = Object.keys(existingMcpConfig.mcpServers).length;
     }
-    existingCommands = (await listDirSafe(path10.join(claudeDir, "commands"))).filter((f) => f.endsWith(".md")).map((f) => f.replace(".md", ""));
-    existingRules = (await listDirSafe(path10.join(claudeDir, "rules"))).filter((f) => f.endsWith(".md")).map((f) => f.replace(".md", ""));
-    existingSkills = await listDirSafe(path10.join(claudeDir, "skills"));
-    existingAgents = (await listDirSafe(path10.join(claudeDir, "agents"))).filter((f) => f.endsWith(".md")).map((f) => f.replace(".md", ""));
+    existingCommands = (await listDirSafe(path11.join(claudeDir, "commands"))).filter((f) => f.endsWith(".md")).map((f) => f.replace(".md", ""));
+    existingRules = (await listDirSafe(path11.join(claudeDir, "rules"))).filter((f) => f.endsWith(".md")).map((f) => f.replace(".md", ""));
+    existingSkills = await listDirSafe(path11.join(claudeDir, "skills"));
+    existingAgents = (await listDirSafe(path11.join(claudeDir, "agents"))).filter((f) => f.endsWith(".md")).map((f) => f.replace(".md", ""));
   }
-  const name = pkg?.name || path10.basename(dir);
+  const name = pkg?.name || path11.basename(dir);
   const description = pkg?.description || "";
   return {
     name,
@@ -1687,31 +1808,31 @@ function simpleDiff(oldContent, newContent) {
     const oldLine = oldLines[i];
     const newLine = newLines[i];
     if (oldLine === void 0) {
-      output.push(chalk8.green(`+ ${newLine}`));
+      output.push(chalk9.green(`+ ${newLine}`));
     } else if (newLine === void 0) {
-      output.push(chalk8.red(`- ${oldLine}`));
+      output.push(chalk9.red(`- ${oldLine}`));
     } else if (oldLine !== newLine) {
-      output.push(chalk8.red(`- ${oldLine}`));
-      output.push(chalk8.green(`+ ${newLine}`));
+      output.push(chalk9.red(`- ${oldLine}`));
+      output.push(chalk9.green(`+ ${newLine}`));
     }
   }
   return output;
 }
-async function generateDiff(spec, targetDir) {
-  const fileMap = buildFileMap(spec);
+async function generateDiff(spec, targetDir, options) {
+  const fileMap = buildFileMap(spec, options);
   const results = [];
   for (const [relativePath, newContent] of fileMap) {
-    const absolutePath = path11.join(targetDir, relativePath);
+    const absolutePath = path12.join(targetDir, relativePath);
     let oldContent = null;
     try {
-      oldContent = await fs11.readFile(absolutePath, "utf-8");
+      oldContent = await fs12.readFile(absolutePath, "utf-8");
     } catch {
     }
     if (oldContent === null) {
       results.push({
         path: relativePath,
         status: "new",
-        diff: chalk8.green("+ NEW FILE")
+        diff: chalk9.green("+ NEW FILE")
       });
     } else if (oldContent === newContent) {
       results.push({
@@ -1857,7 +1978,7 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
       console.log(ui.success("No obvious issues found"));
     }
     if (options.auditOnly) {
-      console.log(chalk8.dim("\n  Audit complete. Run without --audit-only to generate optimized environment.\n"));
+      console.log(chalk9.dim("\n  Audit complete. Run without --audit-only to generate optimized environment.\n"));
       return;
     }
     if (!options.yes) {
@@ -1867,19 +1988,19 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
         default: false
       });
       if (!proceed) {
-        console.log(chalk8.dim("\n  Aborted.\n"));
+        console.log(chalk9.dim("\n  Aborted.\n"));
         return;
       }
     }
   } else {
-    console.log(chalk8.dim("\n  No existing .claude/ directory found \u2014 generating from scratch.\n"));
+    console.log(chalk9.dim("\n  No existing .claude/ directory found \u2014 generating from scratch.\n"));
     if (!options.yes) {
       const proceed = await confirm2({
         message: "Generate Claude Code environment for this project?",
         default: true
       });
       if (!proceed) {
-        console.log(chalk8.dim("\n  Aborted.\n"));
+        console.log(chalk9.dim("\n  Aborted.\n"));
         return;
       }
     }
@@ -1915,8 +2036,9 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
       console.log(ui.tool(name, tool.reason));
     }
   }
+  const hasEnvVars = summary.envSetup.length > 0;
   if (options.diff) {
-    const diffs = await generateDiff(spec, targetDir);
+    const diffs = await generateDiff(spec, targetDir, { hasEnvVars });
     const changedDiffs = diffs.filter((d) => d.status !== "unchanged");
     if (changedDiffs.length === 0) {
       console.log(ui.success("No changes needed \u2014 environment is already up to date."));
@@ -1925,7 +2047,7 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
     }
     console.log(ui.section("Changes Preview"));
     for (const d of changedDiffs) {
-      console.log(chalk8.cyan(`
+      console.log(chalk9.cyan(`
   --- ${d.path}`));
       if (d.status === "new") {
         console.log(`    ${d.diff}`);
@@ -1941,7 +2063,7 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
       default: true
     });
     if (!apply) {
-      console.log(chalk8.dim("\n  Aborted.\n"));
+      console.log(chalk9.dim("\n  Aborted.\n"));
       return;
     }
   }
@@ -1952,20 +2074,14 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
     console.log(ui.success(`Ready! Run: $ hermes`));
     console.log("");
   } else {
-    const written = await writeEnvironment(spec, targetDir);
+    const written = await writeEnvironment(spec, targetDir, { hasEnvVars });
     console.log(ui.section("Files Written"));
     for (const file of written) {
       console.log(ui.file(file));
     }
-    if (summary.envSetup.length > 0) {
-      console.log(ui.section("Setup Required"));
-      const seen = /* @__PURE__ */ new Set();
-      for (const env of summary.envSetup) {
-        if (seen.has(env.envVar)) continue;
-        seen.add(env.envVar);
-        console.log(ui.envVar(env.envVar, env.description, env.signupUrl));
-        console.log("");
-      }
+    if (hasEnvVars) {
+      await collectAndWriteKeys(summary.envSetup, targetDir);
+      console.log("");
     }
     if (summary.pluginCommands.length > 0) {
       console.log(ui.section("Plugins"));
@@ -1982,7 +2098,7 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
 
 // src/commands/doctor.ts
 import { Command as Command7 } from "commander";
-import chalk9 from "chalk";
+import chalk10 from "chalk";
 function runChecks(profile) {
   const checks = [];
   if (!profile.existingClaudeMd) {
@@ -2114,12 +2230,12 @@ var doctorCommand = new Command7("doctor").description(
 ).action(async () => {
   printFullBanner("Doctor");
   const targetDir = process.cwd();
-  console.log(chalk9.dim("  Checking .claude/ environment...\n"));
+  console.log(chalk10.dim("  Checking .claude/ environment...\n"));
   const profile = await scanProject(targetDir);
   if (!profile.hasClaudeDir) {
     console.log(ui.error("No .claude/ directory found.\n"));
     console.log(
-      chalk9.dim("  Run ") + chalk9.bold("kairn describe") + chalk9.dim(" or ") + chalk9.bold("kairn optimize") + chalk9.dim(" to generate one.\n")
+      chalk10.dim("  Run ") + chalk10.bold("kairn describe") + chalk10.dim(" or ") + chalk10.bold("kairn optimize") + chalk10.dim(" to generate one.\n")
     );
     process.exit(1);
   }
@@ -2142,7 +2258,7 @@ var doctorCommand = new Command7("doctor").description(
     return sum;
   }, 0);
   const percentage = Math.round(score / maxScore * 100);
-  const scoreColor = percentage >= 80 ? chalk9.green : percentage >= 50 ? chalk9.yellow : chalk9.red;
+  const scoreColor = percentage >= 80 ? chalk10.green : percentage >= 50 ? chalk10.yellow : chalk10.red;
   console.log(
     `
   Score: ${scoreColor(`${score}/${maxScore}`)} (${scoreColor(`${percentage}%`)})
@@ -2150,14 +2266,14 @@ var doctorCommand = new Command7("doctor").description(
   );
   if (percentage < 80) {
     console.log(
-      chalk9.dim("  Run ") + chalk9.bold("kairn optimize") + chalk9.dim(" to fix issues.\n")
+      chalk10.dim("  Run ") + chalk10.bold("kairn optimize") + chalk10.dim(" to fix issues.\n")
     );
   }
 });
 
 // src/commands/registry.ts
 import { Command as Command8 } from "commander";
-import chalk10 from "chalk";
+import chalk11 from "chalk";
 import { input as input2, select as select2 } from "@inquirer/prompts";
 var listCommand2 = new Command8("list").description("List tools in the registry").option("--category <cat>", "Filter by category").option("--user-only", "Show only user-defined tools").action(async (options) => {
   printCompactBanner();
@@ -2182,7 +2298,7 @@ var listCommand2 = new Command8("list").description("List tools in the registry"
     );
   }
   if (tools.length === 0) {
-    console.log(chalk10.dim("\n  No tools found.\n"));
+    console.log(chalk11.dim("\n  No tools found.\n"));
     return;
   }
   const bundledCount = all.filter((t) => !userIds.has(t.id)).length;
@@ -2196,13 +2312,13 @@ var listCommand2 = new Command8("list").description("List tools in the registry"
       `tier ${tool.tier}`,
       tool.auth
     ].join(", ");
-    console.log(`  ${ui.accent(tool.id)}` + chalk10.dim(` (${meta})`));
-    console.log(chalk10.dim(`    ${tool.description}`));
+    console.log(`  ${ui.accent(tool.id)}` + chalk11.dim(` (${meta})`));
+    console.log(chalk11.dim(`    ${tool.description}`));
     if (tool.best_for.length > 0) {
-      console.log(chalk10.dim(`    Best for: ${tool.best_for.join(", ")}`));
+      console.log(chalk11.dim(`    Best for: ${tool.best_for.join(", ")}`));
     }
     if (isUser) {
-      console.log(chalk10.yellow("    [USER-DEFINED]"));
+      console.log(chalk11.yellow("    [USER-DEFINED]"));
     }
     console.log("");
   }
@@ -2210,7 +2326,7 @@ var listCommand2 = new Command8("list").description("List tools in the registry"
   const shownUser = tools.filter((t) => userIds.has(t.id)).length;
   const shownBundled = totalShown - shownUser;
   console.log(
-    chalk10.dim(
+    chalk11.dim(
       `  ${totalShown} tool${totalShown !== 1 ? "s" : ""} (${shownBundled} bundled, ${shownUser} user-defined)`
     ) + "\n"
   );
@@ -2334,20 +2450,20 @@ var registryCommand = new Command8("registry").description("Manage the tool regi
 
 // src/commands/templates.ts
 import { Command as Command9 } from "commander";
-import chalk11 from "chalk";
-import fs12 from "fs/promises";
-import path12 from "path";
+import chalk12 from "chalk";
+import fs13 from "fs/promises";
+import path13 from "path";
 var templatesCommand = new Command9("templates").description("Browse available templates").option("--category <cat>", "filter templates by category keyword").option("--json", "output raw JSON array").action(async (options) => {
   printCompactBanner();
   const templatesDir = getTemplatesDir();
   let files;
   try {
-    files = await fs12.readdir(templatesDir);
+    files = await fs13.readdir(templatesDir);
   } catch {
     console.log(
-      chalk11.dim(
+      chalk12.dim(
         "  No templates found. Templates will be installed with "
-      ) + chalk11.bold("kairn init") + chalk11.dim(
+      ) + chalk12.bold("kairn init") + chalk12.dim(
         " or you can add .json files to ~/.kairn/templates/\n"
       )
     );
@@ -2356,9 +2472,9 @@ var templatesCommand = new Command9("templates").description("Browse available t
   const jsonFiles = files.filter((f) => f.endsWith(".json"));
   if (jsonFiles.length === 0) {
     console.log(
-      chalk11.dim(
+      chalk12.dim(
         "  No templates found. Templates will be installed with "
-      ) + chalk11.bold("kairn init") + chalk11.dim(
+      ) + chalk12.bold("kairn init") + chalk12.dim(
         " or you can add .json files to ~/.kairn/templates/\n"
       )
     );
@@ -2367,8 +2483,8 @@ var templatesCommand = new Command9("templates").description("Browse available t
   const templates = [];
   for (const file of jsonFiles) {
     try {
-      const data = await fs12.readFile(
-        path12.join(templatesDir, file),
+      const data = await fs13.readFile(
+        path13.join(templatesDir, file),
         "utf-8"
       );
       const spec = JSON.parse(data);
@@ -2386,7 +2502,7 @@ var templatesCommand = new Command9("templates").description("Browse available t
   }
   if (filtered.length === 0) {
     console.log(
-      chalk11.dim(`  No templates matched category "${options.category}".
+      chalk12.dim(`  No templates matched category "${options.category}".
 `)
     );
     return;
@@ -2397,8 +2513,8 @@ var templatesCommand = new Command9("templates").description("Browse available t
     const toolCount = spec.tools?.length ?? 0;
     const commandCount = Object.keys(spec.harness?.commands ?? {}).length;
     const ruleCount = Object.keys(spec.harness?.rules ?? {}).length;
-    console.log(ui.kv("Name", chalk11.bold(spec.name)));
-    console.log(ui.kv("ID", chalk11.dim(spec.id)));
+    console.log(ui.kv("Name", chalk12.bold(spec.name)));
+    console.log(ui.kv("ID", chalk12.dim(spec.id)));
     console.log(ui.kv("Description", spec.description));
     console.log(
       ui.kv("Contents", `${toolCount} tools \xB7 ${commandCount} commands \xB7 ${ruleCount} rules`)
@@ -2406,16 +2522,139 @@ var templatesCommand = new Command9("templates").description("Browse available t
     console.log("");
   }
   console.log(
-    chalk11.dim(`  ${filtered.length} template${filtered.length === 1 ? "" : "s"} available
+    chalk12.dim(`  ${filtered.length} template${filtered.length === 1 ? "" : "s"} available
 `)
   );
 });
 
+// src/commands/keys.ts
+import { Command as Command10 } from "commander";
+import { password as password3 } from "@inquirer/prompts";
+import chalk13 from "chalk";
+import fs14 from "fs/promises";
+import path14 from "path";
+var keysCommand = new Command10("keys").description("Add or update API keys for the current environment").option("--show", "Show which keys are set vs missing").action(async (options) => {
+  printCompactBanner();
+  const targetDir = process.cwd();
+  const requiredVars = await detectRequiredEnvVars(targetDir);
+  if (requiredVars.length === 0) {
+    console.log(
+      ui.info("No MCP servers found in .mcp.json \u2014 no API keys needed.")
+    );
+    console.log("");
+    return;
+  }
+  const existing = await readEnvFile(targetDir);
+  const registry = await loadRegistry();
+  const envSetupMap = /* @__PURE__ */ new Map();
+  for (const tool of registry) {
+    if (!tool.env_vars) continue;
+    for (const ev of tool.env_vars) {
+      if (requiredVars.includes(ev.name)) {
+        envSetupMap.set(ev.name, {
+          toolName: tool.name,
+          envVar: ev.name,
+          description: ev.description,
+          signupUrl: tool.signup_url
+        });
+      }
+    }
+  }
+  for (const varName of requiredVars) {
+    if (!envSetupMap.has(varName)) {
+      envSetupMap.set(varName, {
+        toolName: "unknown",
+        envVar: varName,
+        description: "Required by MCP server"
+      });
+    }
+  }
+  if (options.show) {
+    console.log(ui.section("API Key Status"));
+    console.log("");
+    for (const varName of requiredVars) {
+      const value = existing.get(varName);
+      const info = envSetupMap.get(varName);
+      const toolLabel = info?.toolName !== "unknown" ? chalk13.dim(` (${info?.toolName})`) : "";
+      if (value && value.length > 0) {
+        const masked = value.slice(0, 4) + "\u2022".repeat(Math.max(0, value.length - 4));
+        console.log(chalk13.green(`  \u2713 ${varName}`) + toolLabel + chalk13.dim(` = ${masked}`));
+      } else {
+        console.log(chalk13.yellow(`  \u2717 ${varName}`) + toolLabel + chalk13.dim(" = (not set)"));
+        if (info?.signupUrl) {
+          console.log(chalk13.dim(`      Get one at: ${info.signupUrl}`));
+        }
+      }
+    }
+    const setCount = requiredVars.filter((v) => {
+      const val = existing.get(v);
+      return val && val.length > 0;
+    }).length;
+    const missingCount = requiredVars.length - setCount;
+    console.log("");
+    if (missingCount === 0) {
+      console.log(ui.success(`All ${setCount} key(s) configured`));
+    } else {
+      console.log(
+        ui.warn(`${missingCount} key(s) missing \u2014 run ${chalk13.bold("kairn keys")} to add them`)
+      );
+    }
+    console.log("");
+    return;
+  }
+  const missing = requiredVars.filter((v) => {
+    const val = existing.get(v);
+    return !val || val.length === 0;
+  });
+  if (missing.length === 0) {
+    console.log(ui.success("All API keys are already configured."));
+    console.log(chalk13.dim("  Use --show to see current keys.\n"));
+    return;
+  }
+  console.log(ui.section("API Keys"));
+  console.log(chalk13.dim(`  ${missing.length} key(s) need to be set. Press Enter to skip.
+`));
+  const envEntries = new Map(existing);
+  let keysEntered = 0;
+  for (const varName of missing) {
+    const info = envSetupMap.get(varName);
+    console.log(
+      chalk13.bold(`  ${varName}`) + (info?.toolName !== "unknown" ? chalk13.dim(` (${info?.toolName})`) : "")
+    );
+    if (info?.signupUrl) {
+      console.log(chalk13.dim(`    Get one at: ${info.signupUrl}`));
+    }
+    const value = await password3({
+      message: varName,
+      mask: "\u2022"
+    });
+    if (value && value.trim()) {
+      envEntries.set(varName, value.trim());
+      console.log(chalk13.green("  \u2713 saved\n"));
+      keysEntered++;
+    } else {
+      console.log(chalk13.dim("  (skipped)\n"));
+    }
+  }
+  const envLines = [
+    "# Generated by Kairn \u2014 API keys for MCP servers",
+    "# Do NOT commit this file to git",
+    ""
+  ];
+  for (const [key, value] of envEntries) {
+    envLines.push(`${key}=${value}`);
+  }
+  const envPath = path14.join(targetDir, ".env");
+  await fs14.writeFile(envPath, envLines.join("\n") + "\n", "utf-8");
+  console.log(chalk13.green(`  \u2713 ${keysEntered} key(s) saved to .env`));
+  console.log("");
+});
+
 // src/cli.ts
-var program = new Command10();
+var program = new Command11();
 program.name("kairn").description(
   "Compile natural language intent into optimized Claude Code environments"
-).version("1.7.0").option("--no-color", "Disable colored output");
+).version("1.8.0").option("--no-color", "Disable colored output");
 program.addCommand(initCommand);
 program.addCommand(describeCommand);
 program.addCommand(optimizeCommand);
@@ -2425,8 +2664,9 @@ program.addCommand(updateRegistryCommand);
 program.addCommand(doctorCommand);
 program.addCommand(registryCommand);
 program.addCommand(templatesCommand);
+program.addCommand(keysCommand);
 if (process.argv.includes("--no-color") || process.env.NO_COLOR) {
-  chalk12.level = 0;
+  chalk14.level = 0;
 }
 program.parse();
 //# sourceMappingURL=cli.js.map