alvin-bot 4.23.1 → 4.24.0

package/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.24.0] — 2026-05-12
+
+### Switch AI providers cleanly after install — new `alvin-bot provider` command
+
+End-to-end UX gap closed: until now, the only way to change AI provider after the initial install was to re-run the full setup wizard (Telegram, AI provider, tools menu, …) or hand-edit `~/.alvin-bot/.env` without guidance. Both options leak past the user's actual intent — "I just want to change the AI provider, please."
+
+```bash
+alvin-bot provider list                 # show all providers + per-provider install/key status
+alvin-bot provider show                 # detailed info on the current provider
+alvin-bot provider switch <key>         # interactive setup + targeted .env merge
+alvin-bot provider doctor               # validate current provider's auth/key against its API
+```
+
+`<key>` accepts both canonical slugs (`claude-sdk`, `groq`, `gemini-2.5-flash`, …) and short aliases (`claude`, `codex`, `gemini`, `nvidia`, `gpt`, `gemma`).
+
+### Provider-specific guided setup, reused from the setup wizard
+
+The same install-the-CLI / run-OAuth-login / prompt-for-API-key logic that the setup wizard already uses for first-time configuration is now reusable. Refactored into three small primitives:
+
+- **`configureClaudeSdkInline()`** — detects native `claude` binary, offers `curl -fsSL https://claude.ai/install.sh | sh` if missing, runs `claude auth login --claudeai` if not authenticated, re-validates.
+- **`configureCodexCliInline()`** — new. Detects `codex` binary, offers `npm install -g @openai/codex` if missing, runs `codex login` (ChatGPT OAuth) if not authenticated.
+- **`configureApiKeyInline(provider, opts)`** — for groq / nvidia / gemini / openai / openrouter. Tests an existing key in `.env` first, prompts for a new one if invalid, retries once, "save anyway" path for offline first-time setup.
+
+### Safe `.env` merge — never destroys, never duplicates
+
+The new `setEnvKey()` + `commentEnvKey()` helpers do **byte-preserving** in-place updates of `~/.alvin-bot/.env`:
+
+- `PRIMARY_PROVIDER` line is **updated in place**, not appended. No duplicates.
+- The new provider's API key (if any) is set the same way — also handles "previously commented out by an earlier switch" → uncomment + update.
+- The previous provider's API key is **parked, not deleted**: e.g. `# GROQ_API_KEY=...  # parked 2026-05-12: was for groq, kept for rollback`. Rollback by un-commenting; secret never lost.
+- Everything else (`BOT_TOKEN`, `ALLOWED_USERS`, `FALLBACK_PROVIDERS`, `WEB_*`, custom comments, blank lines, custom additions) is preserved byte-for-byte.
+
+### Auto-restart under launchd
+
+After a successful switch, on macOS with `~/Library/LaunchAgents/com.alvinbot.app.plist` present, the command offers to run `launchctl kickstart -k gui/$UID/com.alvinbot.app` to apply the new provider without manual intervention. Default is Yes; press Enter to restart, `n` to defer.
+
+### Robustness: `ask()` no longer crashes on stdin EOF
+
+`readline.question` throws `ERR_USE_AFTER_CLOSE` once stdin emits 'close' (piped input drained, terminal closed). The `ask()` helper now catches this and returns `""` — same semantic as "user pressed Enter on a prompt", so the calling wizard step picks its default. Fixes a class of crashes for users running setup wizards over `expect` / SSH-piped install scripts / CI.
+
+### Manual end-to-end test on a fresh-ish Apple Silicon Mac (.75)
+
+- `provider list` shows all 8 providers with per-provider status (CLI installed, API key present, OAuth-authenticated)
+- `provider show` reports current = `claude-sdk` with model + key var + fallbacks
+- `provider doctor` validates auth/key against the live API
+- `provider switch groq` with a deliberately invalid key: API returns 401, "Save anyway" path is taken, `.env` is mutated correctly: `PRIMARY_PROVIDER=groq`, `GROQ_API_KEY=…` set, all other vars + comments preserved byte-for-byte
+- `provider switch claude-sdk` (rollback): existing claude binary detected, auth-status warning surfaced, login prompt declined, `.env` mutated: `PRIMARY_PROVIDER=claude-sdk` back, `GROQ_API_KEY` line **commented and stamped** `# GROQ_API_KEY=...  # parked 2026-05-12: was for groq, kept for rollback`, every other line untouched
+
 ## [4.23.1] — 2026-05-12
 
 ### Fixed: install.sh now installs via npm (no more git clone collision)

package/bin/cli.js

@@ -42,7 +42,21 @@ const ensureRL = () => {
   return rl;
 };
 const closeRL = () => { if (rl) { rl.close(); rl = null; } };
-const ask = (q) => new Promise((r) => ensureRL().question(q, r));
+// Robust ask(): if stdin has already closed (piped input EOF, or a previous
+// ask completed and the interface emitted 'close'), `rl.question` throws
+// ERR_USE_AFTER_CLOSE. Treat that as empty input rather than crashing the
+// wizard — the caller can decide whether empty means "default" or "skip".
+const ask = (q) => new Promise((resolve, reject) => {
+  try {
+    ensureRL().question(q, resolve);
+  } catch (err) {
+    if (err && err.code === "ERR_USE_AFTER_CLOSE") {
+      resolve("");
+    } else {
+      reject(err);
+    }
+  }
+});
 
 const LOGO = `
   ╔══════════════════════════════════════╗
@@ -727,6 +741,578 @@ async function validateProviderKey(providerKey, apiKey) {
   }
 }
 
+// ─── Provider config (shared between setup wizard and `provider switch`) ─────
+//
+// Encapsulates the CLI-install + auth-login flow for OAuth-style providers
+// (claude-sdk, codex-cli) and the API-key prompt+validate flow for everything
+// else. Returns a `{ ok, apiKey }` so callers can decide what to do with the
+// .env (the setup wizard writes everything at once; `provider switch` does a
+// targeted merge).
+
+const PROVIDER_KEY_MAP = {
+  groq: "GROQ_API_KEY",
+  "nvidia-llama-3.3-70b": "NVIDIA_API_KEY",
+  "nvidia-kimi-k2.5": "NVIDIA_API_KEY",
+  "gemini-2.5-flash": "GOOGLE_API_KEY",
+  openai: "OPENAI_API_KEY",
+  "gpt-4o": "OPENAI_API_KEY",
+  openrouter: "OPENROUTER_API_KEY",
+};
+
+/**
+ * Find the codex CLI binary if installed. Returns the absolute path or null.
+ */
+function findCodexBinary() {
+  try {
+    const out = execSync("command -v codex", { stdio: "pipe", encoding: "utf-8" });
+    return out.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find the claude CLI binary, checking PATH and common install paths.
+ * Returns the absolute path or null. Mirrors the search in
+ * validateProviderKey("claude-sdk", ...).
+ */
+function findClaudeBinary() {
+  try {
+    const out = execSync("command -v claude", { stdio: "pipe", encoding: "utf-8" });
+    if (out.trim()) return out.trim();
+  } catch {}
+  for (const p of [join(homedir(), ".local", "bin", "claude"), "/usr/local/bin/claude"]) {
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * Interactive Claude SDK setup: ensures the native claude CLI is installed,
+ * runs `claude auth login` if not authenticated. Returns { ok: bool }.
+ *
+ * Designed to be called both from the setup wizard and from
+ * `alvin-bot provider switch claude-sdk`.
+ */
+async function configureClaudeSdkInline() {
+  let cliPath = findClaudeBinary();
+  if (cliPath) {
+    console.log(`  ✅ Claude CLI found at ${cliPath}`);
+  } else {
+    console.log(`  ⚠️  Claude CLI not found (native binary required).`);
+    console.log(`\n  The Claude Agent SDK needs the native Claude Code binary.`);
+    console.log(`  Install with:\n    curl -fsSL https://claude.ai/install.sh | sh`);
+    console.log(`  (npm install @anthropic-ai/claude-code is the alternative path.)\n`);
+
+    const yc = getLocale() === "de" ? ["j", "ja", "y", "yes"] : ["y", "yes"];
+    const doInstall = (await ask(`  Install now via the official installer? (y/n): `)).trim().toLowerCase();
+    if (yc.includes(doInstall)) {
+      console.log(`\n  Installing Claude CLI...`);
+      try {
+        execSync("curl -fsSL https://claude.ai/install.sh | sh", { stdio: "inherit", timeout: 120_000 });
+        const localBin = join(homedir(), ".local", "bin");
+        if (!process.env.PATH.includes(localBin)) {
+          process.env.PATH = `${localBin}:${process.env.PATH || ""}`;
+        }
+        cliPath = findClaudeBinary();
+        if (cliPath) console.log(`  ✅ Claude CLI installed at ${cliPath}\n`);
+      } catch {
+        console.log(`  ❌ Installation failed. Run manually:  curl -fsSL https://claude.ai/install.sh | sh`);
+      }
+    }
+  }
+
+  if (!cliPath) return { ok: false };
+
+  console.log(`  Checking Claude SDK authentication...`);
+  const authResult = await validateProviderKey("claude-sdk", null);
+  if (authResult.ok && !authResult.warning) {
+    console.log(`  ✅ ${authResult.detail}\n`);
+    return { ok: true };
+  }
+
+  // ok-with-warning OR not-ok — offer login.
+  if (authResult.warning) {
+    console.log(`  ⚠️  ${authResult.warning}\n`);
+  } else {
+    console.log(`  ⚠️  ${authResult.error}\n`);
+  }
+  const yc = getLocale() === "de" ? ["j", "ja", "y", "yes"] : ["y", "yes"];
+  const doLogin = (await ask(`  Run 'claude auth login' now? (Y/n): `)).trim().toLowerCase();
+  if (doLogin === "" || yc.includes(doLogin)) {
+    try {
+      execSync(`"${cliPath}" auth login --claudeai`, { stdio: "inherit", timeout: 180_000 });
+    } catch {
+      console.log(`\n  ⚠️  Auto-login failed/cancelled. Run in another terminal:  claude auth login`);
+      await ask(`  Press Enter when you've logged in (or to continue without): `);
+    }
+    const recheck = await validateProviderKey("claude-sdk", null);
+    if (recheck.ok && !recheck.warning) {
+      console.log(`\n  ✅ Claude SDK authenticated.\n`);
+      return { ok: true };
+    }
+    if (recheck.ok && recheck.warning) {
+      console.log(`\n  ⚠️  ${recheck.warning}`);
+      console.log(`     The bot will still try to use the Agent SDK at runtime.\n`);
+      return { ok: true };
+    }
+    console.log(`\n  ❌ Still not authenticated: ${recheck.error}`);
+    return { ok: false };
+  }
+  console.log(`  Skipping login. Run 'claude auth login' later to enable AI responses.`);
+  return { ok: true };  // CLI present, user explicitly skipped login — let it through
+}
+
+/**
+ * Interactive OpenAI Codex CLI setup: ensures `codex` is installed, runs
+ * `codex login` if not authenticated (ChatGPT-Plus/Pro/Max OAuth).
+ */
+async function configureCodexCliInline() {
+  let cliPath = findCodexBinary();
+  if (cliPath) {
+    console.log(`  ✅ codex CLI found at ${cliPath}`);
+  } else {
+    console.log(`  ⚠️  codex CLI not installed.`);
+    console.log(`\n  Install with one of:`);
+    console.log(`    npm install -g @openai/codex     (recommended)`);
+    console.log(`    brew install codex\n`);
+    const yc = getLocale() === "de" ? ["j", "ja", "y", "yes"] : ["y", "yes"];
+    const doInstall = (await ask(`  Install via npm now? (y/n): `)).trim().toLowerCase();
+    if (yc.includes(doInstall)) {
+      console.log(`\n  Installing @openai/codex...`);
+      try {
+        execSync("npm install -g @openai/codex", { stdio: "inherit", timeout: 120_000 });
+        cliPath = findCodexBinary();
+        if (cliPath) console.log(`  ✅ codex CLI installed at ${cliPath}\n`);
+      } catch {
+        console.log(`  ❌ Installation failed. Run manually:  npm install -g @openai/codex`);
+      }
+    }
+  }
+
+  if (!cliPath) return { ok: false };
+
+  // Check login status — `codex login status` exits 0 when logged in.
+  let loggedIn = false;
+  try {
+    const out = execSync(`"${cliPath}" login status 2>&1`, { stdio: "pipe", encoding: "utf-8", timeout: 5000 });
+    if (/Logged in/i.test(out)) loggedIn = true;
+  } catch {}
+
+  if (loggedIn) {
+    console.log(`  ✅ codex CLI is logged in.\n`);
+    return { ok: true };
+  }
+
+  console.log(`  ⚠️  codex CLI not logged in.`);
+  console.log(`     'codex login' opens a browser — sign in with your ChatGPT account.\n`);
+  const yc = getLocale() === "de" ? ["j", "ja", "y", "yes"] : ["y", "yes"];
+  const doLogin = (await ask(`  Run 'codex login' now? (Y/n): `)).trim().toLowerCase();
+  if (doLogin === "" || yc.includes(doLogin)) {
+    try {
+      execSync(`"${cliPath}" login`, { stdio: "inherit", timeout: 240_000 });
+    } catch {
+      console.log(`\n  ⚠️  codex login failed/cancelled.`);
+    }
+    try {
+      const out = execSync(`"${cliPath}" login status 2>&1`, { stdio: "pipe", encoding: "utf-8" });
+      if (/Logged in/i.test(out)) {
+        console.log(`\n  ✅ codex CLI is logged in.\n`);
+        return { ok: true };
+      }
+    } catch {}
+    console.log(`\n  ⚠️  Still not logged in — run 'codex login' later to enable.`);
+    return { ok: false };
+  }
+  console.log(`  Skipping login. Run 'codex login' later to enable AI responses.`);
+  return { ok: true };
+}
+
+/**
+ * Interactive API-key flow for providers that authenticate with a key
+ * (groq, nvidia, gemini, openai, openrouter, …). Validates the key against
+ * the provider's API where possible. Returns { ok, apiKey }.
+ */
+async function configureApiKeyInline(provider, opts = {}) {
+  const envKey = provider.envKey;
+  if (!envKey) return { ok: true, apiKey: "" };
+
+  const existing = opts.existingKey || "";
+  if (existing) {
+    console.log(`\n  Existing ${envKey} found in .env — validating first...`);
+    const test = await validateProviderKey(provider.key, existing);
+    if (test.ok) {
+      console.log(`  ✅ ${test.detail}\n`);
+      return { ok: true, apiKey: existing };
+    }
+    console.log(`  ⚠️  Existing key invalid: ${test.error}\n`);
+  }
+
+  console.log(`  Get an API key for ${provider.name}: ${provider.signup || "(see provider docs)"}\n`);
+  let apiKey = (await ask(`  ${envKey}: `)).trim();
+  if (!apiKey) {
+    console.log(`  ⚠️  No API key provided — provider won't work until configured.`);
+    return { ok: false, apiKey: "" };
+  }
+
+  console.log(`\n  Validating...`);
+  let result = await validateProviderKey(provider.key, apiKey);
+  if (result.ok) {
+    console.log(`  ✅ ${result.detail}\n`);
+    return { ok: true, apiKey };
+  }
+  console.log(`  ❌ ${result.error}\n`);
+
+  const yc = getLocale() === "de" ? ["j", "ja", "y", "yes"] : ["y", "yes"];
+  const retry = (await ask(`  Try a different key? (y/n): `)).trim().toLowerCase();
+  if (yc.includes(retry)) {
+    apiKey = (await ask(`  ${envKey}: `)).trim();
+    if (apiKey) {
+      result = await validateProviderKey(provider.key, apiKey);
+      if (result.ok) {
+        console.log(`  ✅ ${result.detail}\n`);
+        return { ok: true, apiKey };
+      }
+      console.log(`  ❌ ${result.error}`);
+    }
+  }
+  console.log(`  ⚠️  Saving the key anyway — fix later in ~/.alvin-bot/.env if it's wrong.`);
+  return { ok: !!apiKey, apiKey };
+}
+
+// ─── .env merge helpers ──────────────────────────────────────────────────────
+//
+// `provider switch` mutates ~/.alvin-bot/.env by touching exactly two lines:
+// PRIMARY_PROVIDER and the new provider's API-key entry. Everything else
+// (BOT_TOKEN, ALLOWED_USERS, FALLBACK_PROVIDERS, WEB_*, comments, blank
+// lines, custom additions) is preserved byte-for-byte. The OLD provider's
+// API key is commented out — never deleted — so the user can roll back
+// without re-pasting secrets they may not have anywhere else.
+
+/**
+ * Set (or append) `KEY=value` in .env content. If a matching commented line
+ * (`# KEY=...`) exists, it's replaced with the active form. Otherwise the
+ * new line is appended at the end with a leading blank line if needed.
+ */
+function setEnvKey(content, key, value) {
+  const lines = content.split("\n");
+  const activeRe = new RegExp(`^${key}\\s*=`);
+  const commentedRe = new RegExp(`^#\\s*${key}\\s*=`);
+  for (let i = 0; i < lines.length; i++) {
+    if (activeRe.test(lines[i]) || commentedRe.test(lines[i])) {
+      lines[i] = `${key}=${value}`;
+      return lines.join("\n");
+    }
+  }
+  // Append. Ensure there's a separating blank line.
+  if (lines.length && lines[lines.length - 1].trim() !== "") lines.push("");
+  lines.push(`${key}=${value}`);
+  return lines.join("\n");
+}
+
+/**
+ * Comment out an active `KEY=...` line with a note. Leaves already-commented
+ * lines alone, leaves the line absent if it wasn't there. Returns the new
+ * content + a `changed` flag for caller logging.
+ */
+function commentEnvKey(content, key, note) {
+  const lines = content.split("\n");
+  const activeRe = new RegExp(`^${key}\\s*=`);
+  let changed = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (activeRe.test(lines[i])) {
+      const today = new Date().toISOString().slice(0, 10);
+      const stamp = note ? `  # parked ${today}: ${note}` : `  # parked ${today}`;
+      lines[i] = `# ${lines[i]}${stamp}`;
+      changed = true;
+      break;
+    }
+  }
+  return { content: lines.join("\n"), changed };
+}
+
+/**
+ * Read PRIMARY_PROVIDER from .env content (handles "...=value" with optional
+ * quotes/whitespace). Returns the key or null if not set.
+ */
+function readPrimaryProvider(content) {
+  const m = content.match(/^PRIMARY_PROVIDER\s*=\s*"?([^"#\s]+)"?\s*$/m);
+  return m ? m[1] : null;
+}
+
+/**
+ * Read an arbitrary key from .env content. Returns the value or null.
+ */
+function readEnvValue(content, key) {
+  const re = new RegExp(`^${key}\\s*=\\s*"?([^"#\\n]+?)"?\\s*(?:#.*)?$`, "m");
+  const m = content.match(re);
+  return m ? m[1].trim() : null;
+}
+
+// ─── `alvin-bot provider` subcommands ────────────────────────────────────────
+
+/**
+ * Resolve a provider key (or aliases) to a PROVIDERS entry. Returns null if
+ * unknown. Lets users use "claude" → "claude-sdk", "codex" → "codex-cli",
+ * "nvidia" → "nvidia-kimi-k2.5", "gemini" → "gemini-2.5-flash" — so they
+ * don't have to remember the exact slug.
+ */
+function resolveProviderKey(input) {
+  const lower = input.trim().toLowerCase();
+  const aliases = {
+    "claude": "claude-sdk",
+    "claudesdk": "claude-sdk",
+    "codex": "codex-cli",
+    "nvidia": "nvidia-kimi-k2.5",
+    "nim": "nvidia-kimi-k2.5",
+    "kimi": "nvidia-kimi-k2.5",
+    "gemini": "gemini-2.5-flash",
+    "google": "gemini-2.5-flash",
+    "gpt": "openai",
+    "gpt4": "openai",
+    "gpt4o": "openai",
+    "offline": "offline-gemma4",
+    "gemma": "offline-gemma4",
+    "gemma4": "offline-gemma4",
+  };
+  const resolved = aliases[lower] || lower;
+  // Codex-cli isn't in PROVIDERS but is supported by switch/list.
+  if (resolved === "codex-cli") {
+    return {
+      key: "codex-cli",
+      name: "OpenAI Codex CLI (ChatGPT OAuth)",
+      desc: () => "Use your ChatGPT Plus/Pro/Max subscription via the codex CLI. OAuth login, no API key needed.",
+      free: false,
+      envKey: null,
+      signup: "https://chat.openai.com",
+      model: "gpt-5",
+      needsCLI: false,
+      needsCodexCLI: true,
+    };
+  }
+  return PROVIDERS.find(p => p.key === resolved) || null;
+}
+
+/**
+ * Compute installed / authenticated / has-key status for a provider, given
+ * the current .env content. Returns a short status string with an icon.
+ */
+function providerStatus(provider, envContent) {
+  if (provider.offline) {
+    return hasOllama() ? "✓ Ollama installed" : "· Ollama not installed";
+  }
+  if (provider.needsCLI) {
+    return findClaudeBinary() ? "✓ Claude CLI installed" : "· Claude CLI not installed";
+  }
+  if (provider.needsCodexCLI) {
+    return findCodexBinary() ? "✓ codex CLI installed" : "· codex CLI not installed";
+  }
+  if (provider.envKey) {
+    const v = readEnvValue(envContent, provider.envKey);
+    return v ? `✓ ${provider.envKey} set` : `· ${provider.envKey} not set`;
+  }
+  return "—";
+}
+
+function envPath() {
+  return join(DATA_DIR, ".env");
+}
+
+function loadEnvOrExit(silent = false) {
+  const p = envPath();
+  if (!existsSync(p)) {
+    if (!silent) {
+      console.log(`\n❌ No .env at ${p}`);
+      console.log(`   Run 'alvin-bot setup' first to configure the bot.\n`);
+    }
+    return null;
+  }
+  return { path: p, content: readFileSync(p, "utf-8") };
+}
+
+async function providerList() {
+  const loaded = loadEnvOrExit(true);
+  const env = loaded?.content || "";
+  const current = readPrimaryProvider(env);
+
+  console.log(`\n📋 AI providers — current: ${current ? `🟢 ${current}` : "(not configured)"}\n`);
+
+  // Build a uniform list: wizard PROVIDERS + codex-cli alias.
+  const ALL = [...PROVIDERS, resolveProviderKey("codex-cli")];
+  for (const p of ALL) {
+    const marker = p.key === current ? "→" : " ";
+    const badge = p.offline ? "🔒" : p.free ? "🆓" : "💰";
+    const status = providerStatus(p, env);
+    console.log(`  ${marker} ${badge} ${p.key.padEnd(22)}  ${status}`);
+    console.log(`       ${p.name}`);
+  }
+  console.log(`\n  Switch with:  alvin-bot provider switch <key>`);
+  console.log(`  Aliases: claude, codex, gemini, nvidia, gpt, gemma\n`);
+}
+
+async function providerShow() {
+  const loaded = loadEnvOrExit();
+  if (!loaded) return;
+  const current = readPrimaryProvider(loaded.content);
+  if (!current) {
+    console.log(`\n⚠️  PRIMARY_PROVIDER not set in .env.\n`);
+    return;
+  }
+  const provider = resolveProviderKey(current);
+  if (!provider) {
+    console.log(`\n⚠️  PRIMARY_PROVIDER='${current}' but no matching provider definition found.\n`);
+    return;
+  }
+  console.log(`\n📍 Current AI provider\n`);
+  console.log(`  Key:     ${provider.key}`);
+  console.log(`  Name:    ${provider.name}`);
+  console.log(`  Model:   ${provider.model || "(default)"}`);
+  console.log(`  Status:  ${providerStatus(provider, loaded.content)}`);
+  if (provider.envKey) {
+    const v = readEnvValue(loaded.content, provider.envKey);
+    console.log(`  Key var: ${provider.envKey}${v ? " (set)" : " (missing!)"}`);
+  }
+  console.log(``);
+  const fb = readEnvValue(loaded.content, "FALLBACK_PROVIDERS");
+  if (fb) console.log(`  Fallbacks: ${fb}\n`);
+  console.log(`  Doctor:  alvin-bot provider doctor`);
+  console.log(`  Switch:  alvin-bot provider switch <key>\n`);
+}
+
+/**
+ * Switch the bot to a different AI provider. Runs the same interactive
+ * configuration as the setup wizard (CLI install + auth login or API-key
+ * prompt) but only touches the provider-related lines in .env. The previous
+ * provider's API key is commented out (never deleted) so rollback is trivial.
+ */
+async function providerSwitch(targetKey) {
+  if (!targetKey) {
+    console.log(`Usage: alvin-bot provider switch <key>`);
+    console.log(`Available keys: see 'alvin-bot provider list'`);
+    return;
+  }
+  const target = resolveProviderKey(targetKey);
+  if (!target) {
+    console.log(`\n❌ Unknown provider: '${targetKey}'`);
+    console.log(`   See 'alvin-bot provider list' for valid keys.\n`);
+    return;
+  }
+  const loaded = loadEnvOrExit();
+  if (!loaded) return;
+
+  let content = loaded.content;
+  const fromKey = readPrimaryProvider(content);
+  const fromProvider = fromKey ? resolveProviderKey(fromKey) : null;
+
+  console.log(`\n🔁 Switching AI provider`);
+  console.log(`   from:  ${fromKey || "(not set)"}${fromProvider ? `  (${fromProvider.name})` : ""}`);
+  console.log(`   to:    ${target.key}  (${target.name})\n`);
+
+  if (fromKey === target.key) {
+    console.log(`  ℹ️  Already on ${target.key}. Nothing to do.\n`);
+    return;
+  }
+
+  // ── Run provider-specific configuration ────────────────────────────────
+  let newKey = "";
+  if (target.offline) {
+    const ok = await setupOfflineGemma4();
+    if (!ok) {
+      console.log(`  ❌ Offline setup didn't complete — keeping current provider.\n`);
+      return;
+    }
+  } else if (target.needsCLI) {
+    const res = await configureClaudeSdkInline();
+    if (!res.ok) {
+      console.log(`  ❌ Claude SDK setup didn't complete — keeping current provider.\n`);
+      return;
+    }
+  } else if (target.needsCodexCLI) {
+    const res = await configureCodexCliInline();
+    if (!res.ok) {
+      console.log(`  ❌ Codex CLI setup didn't complete — keeping current provider.\n`);
+      return;
+    }
+  } else if (target.envKey) {
+    const existingKey = readEnvValue(content, target.envKey) || "";
+    const res = await configureApiKeyInline(target, { existingKey });
+    if (!res.ok) {
+      console.log(`  ❌ No usable API key — keeping current provider.\n`);
+      return;
+    }
+    newKey = res.apiKey;
+  }
+
+  // ── Merge-update .env ──────────────────────────────────────────────────
+  content = setEnvKey(content, "PRIMARY_PROVIDER", target.offline ? "ollama" : target.key);
+  if (target.envKey && newKey) {
+    content = setEnvKey(content, target.envKey, newKey);
+  }
+  // Park the previous provider's API key (if it had one and the new
+  // provider uses a *different* key). Same-key reuse (e.g. switching
+  // between OpenAI and gpt-4o which both use OPENAI_API_KEY) is left alone.
+  if (fromProvider && fromProvider.envKey && fromProvider.envKey !== target.envKey) {
+    const parked = commentEnvKey(content, fromProvider.envKey, `was for ${fromProvider.key}, kept for rollback`);
+    if (parked.changed) {
+      console.log(`  📦 Parked old ${fromProvider.envKey} (commented out, not deleted).`);
+    }
+    content = parked.content;
+  }
+
+  writeFileSync(loaded.path, content, { mode: 0o600 });
+  console.log(`\n  ✅ ${loaded.path} updated.`);
+
+  // ── Offer restart under launchd ─────────────────────────────────────────
+  if (process.platform === "darwin") {
+    const { plistPath, label } = launchdPaths();
+    if (existsSync(plistPath)) {
+      const yc = getLocale() === "de" ? ["j", "ja", "y", "yes"] : ["y", "yes"];
+      const doRestart = (await ask(`  Restart the launchd-managed bot to apply? (Y/n): `)).trim().toLowerCase();
+      if (doRestart === "" || yc.includes(doRestart)) {
+        try {
+          execSync(`launchctl kickstart -k gui/$UID/${label}`, { stdio: "inherit" });
+          console.log(`  ✅ Bot restarted.`);
+        } catch (err) {
+          console.log(`  ⚠️  Restart failed — run manually: launchctl kickstart -k gui/$(id -u)/${label}`);
+        }
+      } else {
+        console.log(`  ℹ️  Restart later with: launchctl kickstart -k gui/$(id -u)/${label}`);
+      }
+    } else {
+      console.log(`  ℹ️  Restart the bot to apply (whatever your process manager is).`);
+    }
+  }
+  console.log(``);
+}
+
+async function providerDoctor() {
+  const loaded = loadEnvOrExit();
+  if (!loaded) return;
+  const current = readPrimaryProvider(loaded.content);
+  if (!current) {
+    console.log(`\n⚠️  PRIMARY_PROVIDER not set.\n`);
+    return;
+  }
+  const provider = resolveProviderKey(current);
+  console.log(`\n🩺 Provider health: ${current}\n`);
+  if (!provider) {
+    console.log(`  ❌ No definition for '${current}' in PROVIDERS.\n`);
+    return;
+  }
+  const key = provider.envKey ? readEnvValue(loaded.content, provider.envKey) : null;
+  const result = await validateProviderKey(provider.key, key);
+  if (result.ok && result.warning) {
+    console.log(`  ⚠️  ${result.warning}`);
+    console.log(`     ${result.detail}\n`);
+  } else if (result.ok) {
+    console.log(`  ✅ ${result.detail}\n`);
+  } else {
+    console.log(`  ❌ ${result.error}\n`);
+    console.log(`  Fix:  alvin-bot provider switch ${provider.key}`);
+    console.log(`        (or:  alvin-bot provider switch <other>)\n`);
+  }
+}
+
 /**
  * Validate a Telegram bot token by calling getMe.
  * Returns { ok: true, botName: "@username" } or { ok: false, error: "reason" }.
@@ -2179,6 +2765,34 @@ switch (cmd) {
     }
     break;
   }
+  case "provider": {
+    const sub = (process.argv[3] || "list").toLowerCase();
+    const arg = process.argv[4];
+    const done = (p) => p.then(() => closeRL()).catch(err => { console.error(err); closeRL(); });
+    if (sub === "list" || sub === "ls") {
+      done(providerList());
+    } else if (sub === "show" || sub === "current") {
+      done(providerShow());
+    } else if (sub === "switch" || sub === "use" || sub === "set") {
+      done(providerSwitch(arg));
+    } else if (sub === "doctor" || sub === "check" || sub === "validate") {
+      done(providerDoctor());
+    } else {
+      console.log("Usage: alvin-bot provider <list|show|switch <key>|doctor>");
+      console.log("");
+      console.log("  list                    — Show all providers + current selection + per-provider status");
+      console.log("  show                    — Detailed info on the currently configured provider");
+      console.log("  switch <key>            — Switch to a different provider (interactive setup + .env merge)");
+      console.log("  doctor                  — Validate the current provider's auth/key against its API");
+      console.log("");
+      console.log("Aliases accepted for <key>: claude, codex, gemini, nvidia, gpt, gemma");
+      console.log("Examples:");
+      console.log("  alvin-bot provider switch groq");
+      console.log("  alvin-bot provider switch claude-sdk");
+      console.log("  alvin-bot provider switch codex");
+    }
+    break;
+  }
   case "update":
     update().catch(console.error);
     break;
@@ -2542,6 +3156,7 @@ ${t("cli.commands")}
   audit     Security health check (permissions, secrets, config)
   search    Search your assets, memories, and skills
   tools     List / install optional capability tools (ffmpeg, pandoc, …)
+  provider  List / switch AI provider (claude, codex, groq, gemini, …)
   browser   Manage bot-owned Chromium (start/stop/goto/shot/doctor)
   update    ${t("cli.updateDesc")}
   start     ${t("cli.startDesc")} (background via PM2)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alvin-bot",
-  "version": "4.23.1",
+  "version": "4.24.0",
   "description": "Alvin Bot — Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
   "type": "module",
   "main": "dist/index.js",