@mrgoonie/multix 0.7.3 → 0.9.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0](https://github.com/mrgoonie/multix-cli/compare/v0.8.0...v0.9.0) (2026-10-11)
+
+
+### Added
+
+* **core:** opt-in loading of legacy .claude env files ([#70](https://github.com/mrgoonie/multix-cli/issues/70)) ([48d9420](https://github.com/mrgoonie/multix-cli/commit/48d9420012a36ada0b5a35e2e51d90c1daa5042c))
+
+## [0.8.0](https://github.com/mrgoonie/multix-cli/compare/v0.7.3...v0.8.0) (2026-10-11)
+
+
+### Added
+
+* **gemini:** rotate across GEMINI_API_KEY_N keys on quota errors ([#65](https://github.com/mrgoonie/multix-cli/issues/65)) ([d24efd3](https://github.com/mrgoonie/multix-cli/commit/d24efd36676d3823f9aac6e2aa0a8bd7a393b282))
+
 ## [0.7.3](https://github.com/mrgoonie/multix-cli/compare/v0.7.2...v0.7.3) (2026-10-11)
 
 

package/README.md

@@ -56,6 +56,7 @@ Set at least one provider key. Add to `.env` in your project root or `~/.multix/
 | Variable | Required | Purpose |
 |---|---|---|
 | `GEMINI_API_KEY` | For Gemini | [AI Studio](https://aistudio.google.com/apikey) |
+| `GEMINI_API_KEY_2`, `GEMINI_API_KEY_3`, … | No | Extra Gemini keys for quota rotation (see below) |
 | `OPENAI_API_KEY` | For OpenAI API | [OpenAI](https://platform.openai.com/api-keys) |
 | `OPENROUTER_API_KEY` | For OpenRouter | [OpenRouter](https://openrouter.ai/settings/keys) |
 | `MINIMAX_API_KEY` | For MiniMax | [MiniMax](https://platform.minimax.io/user-center/basic-information/interface-key) |
@@ -95,7 +96,11 @@ Set at least one provider key. Add to `.env` in your project root or `~/.multix/
 | `GEMINI_MODEL` / `MULTIMODAL_MODEL` | No | Override Gemini analyze/transcribe/extract model (doc convert uses `--model`; default `gemini-3.6-flash`) |
 | `GEMINI_TTS_MODEL` / `TTS_MODEL` | No | Override Gemini TTS model (default `gemini-3.8-flash-lite-tts`) |
 
-Priority: `process.env` > `cwd/.env` > `~/.multix/.env`.
+### Gemini key rotation
+
+Set extra keys as `GEMINI_API_KEY_2`, `GEMINI_API_KEY_3`, … (any numeric suffix; numbered keys alone are enough). `multix` tries `GEMINI_API_KEY` first, then the numbered keys in ascending order, skipping duplicates. When a key returns HTTP 429 (or 400/403 with `RESOURCE_EXHAUSTED`), it cools down for the server's `Retry-After`/`retryDelay` (default 60s) and the same request is retried with the next ready key; other errors are not rotated. A Files API upload is repeated on the new key if the following generate call is rate-limited. Veo rotates on submit only, so a rate limit while polling or downloading never starts a second billed job. `doc convert` stops its own retries on a rate limit. Cooldowns last for the current process only, and logs name the env var, never the key. `multix check` lists the keys in rotation and pings each one. Quotas are per Google Cloud project: keys from the same project share one quota, so rotation only helps across projects.
+
+Priority: `process.env` > `cwd/.env` > `~/.multix/.env`. Set `MULTIX_LEGACY_CLAUDE_ENV=1` to also read legacy AgentKit files (`.claude/skills/{ai-multimodal,ak-ai-multimodal}/.env`, `.claude/skills/.env`, `.claude/.env`, project first, then home) with the lowest priority (credential names only, never endpoint/proxy settings); `multix check -v` lists the env files that were loaded.
 
 ## Commands
 

package/dist/cli.js

@@ -280,22 +280,78 @@ init_redact();
 import fs3 from "fs";
 import os from "os";
 import path3 from "path";
-import { config as dotenvConfig } from "dotenv";
+import { config as dotenvConfig, parse as dotenvParse } from "dotenv";
 var loaded = false;
+var loadedFiles = [];
+var LEGACY_SKILL_DIRS = ["ai-multimodal", "ak-ai-multimodal"];
+function legacyFilesUnder(root) {
+  const claude = path3.join(root, ".claude");
+  return [
+    ...LEGACY_SKILL_DIRS.map((dir) => path3.join(claude, "skills", dir, ".env")),
+    path3.join(claude, "skills", ".env"),
+    path3.join(claude, ".env")
+  ];
+}
+function samePath(a, b) {
+  const norm = (p) => {
+    const r = path3.resolve(p);
+    return process.platform === "win32" ? r.toLowerCase() : r;
+  };
+  return norm(a) === norm(b);
+}
+function legacyClaudeEnvFiles(cwd, home) {
+  const files = legacyFilesUnder(cwd);
+  if (home && !samePath(home, cwd)) files.push(...legacyFilesUnder(home));
+  return files;
+}
+function legacyClaudeEnvEnabled(env = process.env) {
+  const value = env.MULTIX_LEGACY_CLAUDE_ENV;
+  return value !== void 0 && ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
+}
+var LEGACY_ALLOWED_NAME = /^[A-Z][A-Z0-9_]*_(API_KEY(_\d+)?|API_TOKEN|ACCOUNT_ID|GATEWAY_ID)$|^(FAL_KEY|ARK_API_KEY)$/;
+function isLegacyAllowedName(name) {
+  return LEGACY_ALLOWED_NAME.test(name);
+}
+function isReadableFile(file) {
+  try {
+    return fs3.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+function loadFile(file) {
+  if (!isReadableFile(file)) return;
+  const result = dotenvConfig({ path: file, override: false });
+  if (!result.error) loadedFiles.push(file);
+}
+function loadLegacyFile(file) {
+  if (!isReadableFile(file)) return;
+  let parsed;
+  try {
+    parsed = dotenvParse(fs3.readFileSync(file));
+  } catch {
+    return;
+  }
+  for (const [name, value] of Object.entries(parsed)) {
+    if (isLegacyAllowedName(name) && process.env[name] === void 0) process.env[name] = value;
+  }
+  loadedFiles.push(file);
+}
 function loadEnv() {
   if (loaded) return;
   loaded = true;
-  const cwdEnv = path3.resolve(process.cwd(), ".env");
-  if (fs3.existsSync(cwdEnv)) {
-    dotenvConfig({ path: cwdEnv, override: false });
-  }
-  if (!process.env.MULTIX_DISABLE_HOME_ENV) {
-    const homeEnv = path3.join(os.homedir(), ".multix", ".env");
-    if (fs3.existsSync(homeEnv)) {
-      dotenvConfig({ path: homeEnv, override: false });
-    }
+  loadedFiles = [];
+  const cwd = process.cwd();
+  const home = process.env.MULTIX_DISABLE_HOME_ENV ? void 0 : os.homedir();
+  loadFile(path3.resolve(cwd, ".env"));
+  if (home) loadFile(path3.join(home, ".multix", ".env"));
+  if (legacyClaudeEnvEnabled()) {
+    for (const file of legacyClaudeEnvFiles(cwd, home)) loadLegacyFile(file);
   }
 }
+function getLoadedEnvFiles() {
+  return [...loadedFiles];
+}
 function resolveKey(name) {
   return process.env[name] || void 0;
 }
@@ -3090,9 +3146,72 @@ init_errors();
 import fs20 from "fs";
 
 // src/providers/gemini/client.ts
+init_errors();
 import fs18 from "fs";
 import path22 from "path";
+
+// src/providers/gemini/key-pool.ts
 init_errors();
+var PRIMARY_KEY_ENV = "GEMINI_API_KEY";
+var DEFAULT_COOLDOWN_MS = 6e4;
+var cooldownUntil = /* @__PURE__ */ new Map();
+function listGeminiKeys(env = process.env) {
+  const numbered = Object.keys(env).map((name) => ({ name, match: /^GEMINI_API_KEY_(\d+)$/.exec(name) })).filter((e) => e.match !== null).sort((a, b) => Number(a.match[1]) - Number(b.match[1])).map((e) => e.name);
+  const seen = /* @__PURE__ */ new Set();
+  const keys = [];
+  for (const name of [PRIMARY_KEY_ENV, ...numbered]) {
+    const value = env[name]?.trim();
+    if (!value || seen.has(value)) continue;
+    seen.add(value);
+    keys.push({ name, value });
+  }
+  return keys;
+}
+function isGeminiRateLimitError(error) {
+  if (!(error instanceof HttpError)) return false;
+  if (error.status === 429) return true;
+  return (error.status === 400 || error.status === 403) && error.snippet.includes("RESOURCE_EXHAUSTED");
+}
+function cooldownMs(error) {
+  if (!(error instanceof HttpError)) return DEFAULT_COOLDOWN_MS;
+  if (error.retryAfterMs !== void 0 && error.retryAfterMs > 0) return error.retryAfterMs;
+  const delay = /"retryDelay"\s*:\s*"(\d+(?:\.\d+)?)s"/.exec(error.snippet);
+  if (delay?.[1]) return Math.ceil(Number(delay[1]) * 1e3);
+  return DEFAULT_COOLDOWN_MS;
+}
+function keysToTry(keys, now) {
+  const until = (k) => cooldownUntil.get(k.value) ?? 0;
+  const ready = keys.filter((k) => until(k) <= now);
+  if (ready.length > 0) return ready;
+  const soonest = [...keys].sort((a, b) => until(a) - until(b))[0];
+  return soonest ? [soonest] : [];
+}
+async function withGeminiKey(fn, opts = {}) {
+  const now = opts.now ?? Date.now;
+  const keys = listGeminiKeys(opts.env);
+  if (keys.length === 0) {
+    throw new ConfigError(
+      "GEMINI_API_KEY is not set. Get one at https://aistudio.google.com/apikey"
+    );
+  }
+  const ordered = keysToTry(keys, now());
+  let lastError;
+  for (const [i, key] of ordered.entries()) {
+    try {
+      return await fn(key.value, key.name);
+    } catch (error) {
+      if (!isGeminiRateLimitError(error)) throw error;
+      lastError = error;
+      cooldownUntil.set(key.value, now() + cooldownMs(error));
+      const next = ordered[i + 1];
+      if (next) opts.logger?.warn(`${key.name} is rate-limited; retrying with ${next.name}`);
+    }
+  }
+  if (keys.length > 1) {
+    opts.logger?.warn(`All ${keys.length} Gemini keys are rate-limited; try again later`);
+  }
+  throw lastError;
+}
 
 // src/providers/gemini/task-resolver.ts
 import path21 from "path";
@@ -3147,19 +3266,16 @@ function requiresProcessingWait(mimeType) {
 var BASE = "https://generativelanguage.googleapis.com";
 var FILES_BASE = `${BASE}/upload/v1beta/files`;
 var GENERATE_BASE = `${BASE}/v1beta/models`;
-function requireApiKey() {
-  const key = resolveKey("GEMINI_API_KEY");
-  if (!key)
-    throw new ConfigError(
-      "GEMINI_API_KEY is not set. Get one at https://aistudio.google.com/apikey"
-    );
-  return key;
+function withKey(opts, fn) {
+  return opts.apiKey ? fn(opts.apiKey) : withGeminiKey(fn, { logger: opts.logger });
 }
 function authHeaders2(apiKey) {
   return { "x-goog-api-key": apiKey };
 }
 async function uploadFile(filePath, opts = {}) {
-  const apiKey = requireApiKey();
+  return withKey(opts, (apiKey) => uploadFileWithKey(filePath, apiKey, opts));
+}
+async function uploadFileWithKey(filePath, apiKey, opts) {
   const { timeoutMs = 3e5, logger } = opts;
   const mimeType = getMimeType(filePath);
   const fileBytes = fs18.readFileSync(filePath);
@@ -3195,10 +3311,7 @@ Content-Type: ${mimeType}\r
   });
   if (!resp.ok) {
     const txt = await resp.text();
-    throw new ProviderError(
-      `File upload failed (HTTP ${resp.status}): ${txt.slice(0, 500)}`,
-      "gemini"
-    );
+    throw new HttpError(resp.status, `File upload failed: ${txt.slice(0, 500)}`, FILES_BASE);
   }
   const data = await resp.json();
   let fileRef = data.file;
@@ -3220,26 +3333,30 @@ Content-Type: ${mimeType}\r
   logger?.debug(`Uploaded: ${fileRef.name} (${fileRef.uri})`);
   return fileRef;
 }
-async function generateContent(req) {
-  const apiKey = requireApiKey();
-  return httpJson({
-    url: `${GENERATE_BASE}/${req.model}:generateContent`,
-    method: "POST",
-    headers: authHeaders2(apiKey),
-    body: {
-      contents: req.contents,
-      ...req.generationConfig ? { generationConfig: req.generationConfig } : {}
-    }
-  });
+async function generateContent(req, opts = {}) {
+  return withKey(
+    opts,
+    (apiKey) => httpJson({
+      url: `${GENERATE_BASE}/${req.model}:generateContent`,
+      method: "POST",
+      headers: authHeaders2(apiKey),
+      body: {
+        contents: req.contents,
+        ...req.generationConfig ? { generationConfig: req.generationConfig } : {}
+      }
+    })
+  );
 }
-async function createInteraction(body) {
-  const apiKey = requireApiKey();
-  return httpJson({
-    url: `${BASE}/v1beta/interactions`,
-    method: "POST",
-    headers: authHeaders2(apiKey),
-    body
-  });
+async function createInteraction(body, opts = {}) {
+  return withKey(
+    opts,
+    (apiKey) => httpJson({
+      url: `${BASE}/v1beta/interactions`,
+      method: "POST",
+      headers: authHeaders2(apiKey),
+      body
+    })
+  );
 }
 function extractInteractionAudio(resp) {
   let found = null;
@@ -3418,22 +3535,30 @@ function registerAnalyzeCommand(parent) {
         const filePath = opts.files[i];
         logger.debug(`[${i + 1}/${opts.files.length}] Processing: ${filePath}`);
         try {
-          const useApi = shouldUseFileApi(filePath);
-          let contentParts;
-          if (useApi) {
-            logger.debug("File >20MB \u2014 using Files API");
-            const ref = await uploadFile(filePath, { logger });
-            contentParts = [
-              { text: opts.prompt },
-              { fileData: { mimeType: ref.mimeType, fileUri: ref.uri } }
-            ];
-          } else {
-            contentParts = [{ text: opts.prompt }, inlinePart(filePath)];
-          }
-          const resp = await generateContent({
-            model,
-            contents: [{ parts: contentParts }]
-          });
+          const resp = await withGeminiKey(
+            async (apiKey) => {
+              const useApi = shouldUseFileApi(filePath);
+              let contentParts;
+              if (useApi) {
+                logger.debug("File >20MB \u2014 using Files API");
+                const ref = await uploadFile(filePath, { logger, apiKey });
+                contentParts = [
+                  { text: opts.prompt },
+                  { fileData: { mimeType: ref.mimeType, fileUri: ref.uri } }
+                ];
+              } else {
+                contentParts = [{ text: opts.prompt }, inlinePart(filePath)];
+              }
+              return generateContent(
+                {
+                  model,
+                  contents: [{ parts: contentParts }]
+                },
+                { apiKey }
+              );
+            },
+            { logger }
+          );
           results.push({
             file: filePath,
             status: "success",
@@ -3472,22 +3597,30 @@ function registerExtractCommand(parent) {
         const filePath = opts.files[i];
         logger.debug(`[${i + 1}/${opts.files.length}] Extracting: ${filePath}`);
         try {
-          const useApi = shouldUseFileApi(filePath);
-          let contentParts;
-          if (useApi) {
-            const ref = await uploadFile(filePath, { logger });
-            contentParts = [
-              { text: opts.prompt },
-              { fileData: { mimeType: ref.mimeType, fileUri: ref.uri } }
-            ];
-          } else {
-            contentParts = [{ text: opts.prompt }, inlinePart(filePath)];
-          }
-          const resp = await generateContent({
-            model,
-            contents: [{ parts: contentParts }],
-            generationConfig
-          });
+          const resp = await withGeminiKey(
+            async (apiKey) => {
+              const useApi = shouldUseFileApi(filePath);
+              let contentParts;
+              if (useApi) {
+                const ref = await uploadFile(filePath, { logger, apiKey });
+                contentParts = [
+                  { text: opts.prompt },
+                  { fileData: { mimeType: ref.mimeType, fileUri: ref.uri } }
+                ];
+              } else {
+                contentParts = [{ text: opts.prompt }, inlinePart(filePath)];
+              }
+              return generateContent(
+                {
+                  model,
+                  contents: [{ parts: contentParts }],
+                  generationConfig
+                },
+                { apiKey }
+              );
+            },
+            { logger }
+          );
           results.push({ file: filePath, status: "success", response: extractText(resp) });
         } catch (e) {
           const msg = e instanceof Error ? e.message : String(e);
@@ -3591,11 +3724,14 @@ async function generateGeminiSpeech(opts) {
   logger?.debug(`Gemini TTS model=${model} mode=${speakers?.length ? "multi" : "single"}`);
   let resp;
   try {
-    resp = await generateContent({
-      model,
-      contents: [{ parts: [{ text }] }],
-      generationConfig
-    });
+    resp = await generateContent(
+      {
+        model,
+        contents: [{ parts: [{ text }] }],
+        generationConfig
+      },
+      { logger }
+    );
   } catch (e) {
     return { status: "error", error: e instanceof Error ? e.message : String(e) };
   }
@@ -3631,7 +3767,7 @@ async function generateInteractionsSpeech(opts) {
   }
   let resp;
   try {
-    resp = await createInteraction(buildInteractionsSpeechBody(opts));
+    resp = await createInteraction(buildInteractionsSpeechBody(opts), { logger });
   } catch (e) {
     return { status: "error", error: e instanceof Error ? e.message : String(e) };
   }
@@ -3787,9 +3923,9 @@ function collectSpeakers(value, prev) {
 }
 
 // src/providers/gemini/commands/generate-video.ts
+init_errors();
 import fs24 from "fs";
 import path25 from "path";
-init_errors();
 
 // src/providers/gemini/veo.ts
 import fs23 from "fs";
@@ -3907,6 +4043,7 @@ async function submitVeo(apiKey, model, body) {
       body
     });
   } catch (e) {
+    if (e instanceof HttpError) throw e;
     const msg = e instanceof Error ? e.message : String(e);
     throw new ProviderError(`Veo submit failed: ${msg}`, "gemini");
   }
@@ -3944,8 +4081,12 @@ async function downloadVeoVideo(apiKey, uri, dest) {
   }
   await downloadFile(uri, dest, 3e5, host === API_HOST ? headers(apiKey) : void 0);
 }
-async function runVeo(apiKey, model, request, dest, logger) {
-  const operation = await submitVeo(apiKey, model, buildVeoRequest(request));
+async function runVeo(model, request, dest, logger) {
+  const body = buildVeoRequest(request);
+  const { apiKey, operation } = await withGeminiKey(
+    async (key) => ({ apiKey: key, operation: await submitVeo(key, model, body) }),
+    { logger }
+  );
   logger.debug(`Operation: ${operation.name}`);
   const finalOp = await waitForVeo(apiKey, operation, logger);
   const uri = extractVeoVideoUri(finalOp);
@@ -3964,11 +4105,12 @@ function registerGenerateVideoCommand(parent) {
   parent.command("generate-video").description("Generate video with Veo via Gemini API [EXPERIMENTAL]").requiredOption("--prompt <text>", "Video generation prompt").option("--model <id>", "Veo model to use").option("--resolution <res>", "Video resolution: 720p|1080p", "1080p").option("--aspect-ratio <ratio>", "Aspect ratio", "16:9").option(
     "--reference-images <paths...>",
     "Reference images (first=opening frame, second=closing)"
-  ).option("--upload-timeout <ms>", "Upload timeout in ms", "120000").option("--output <path>", "Copy generated video to this path").option("--no-thumb", "Skip downloading the thumbnail if the API returns one").option("-v, --verbose", "Verbose logging").action(
+  ).option("--upload-timeout <ms>", "Deprecated and ignored (images are sent inline)").option("--output <path>", "Copy generated video to this path").option("--no-thumb", "Skip downloading the thumbnail if the API returns one").option("-v, --verbose", "Verbose logging").action(
     async (opts) => {
       const logger = createLogger({ verbose: opts.verbose ?? false });
-      const apiKey = resolveKey("GEMINI_API_KEY");
-      if (!apiKey) throw new ValidationError("GEMINI_API_KEY is not set");
+      if (opts.uploadTimeout !== void 0) {
+        logger.warn("--upload-timeout is deprecated and ignored (images are sent inline)");
+      }
       const model = opts.model ?? getDefaultModel("generate-video");
       if (!model.startsWith("veo-")) {
         throw new ValidationError(
@@ -3986,7 +4128,6 @@ function registerGenerateVideoCommand(parent) {
       const frames = veoFramesFromPaths(opts.referenceImages);
       const dest = path25.join(getOutputDir(), `veo_generated_${Date.now()}.mp4`);
       const finalOp = await runVeo(
-        apiKey,
         model,
         {
           prompt: opts.prompt,
@@ -4043,11 +4184,14 @@ function registerGenerateCommand(parent) {
       const savedFiles = [];
       for (let i = 0; i < numImages; i++) {
         try {
-          const resp = await generateContent({
-            model,
-            contents: [{ parts: [{ text: opts.prompt }] }],
-            generationConfig
-          });
+          const resp = await generateContent(
+            {
+              model,
+              contents: [{ parts: [{ text: opts.prompt }] }],
+              generationConfig
+            },
+            { logger }
+          );
           const images = extractImages(resp);
           if (images.length === 0) {
             logger.warn(
@@ -4135,7 +4279,7 @@ function registerGeminiImageToImageCommand(parent) {
         contents: [{ parts }],
         generationConfig: { responseModalities: ["IMAGE"] }
       };
-      const resp = await generateContent(req);
+      const resp = await generateContent(req, { logger });
       const images = extractImages(resp);
       if (images.length === 0) {
         logger.error(
@@ -4193,15 +4337,13 @@ function sniffImageMime(buf, url) {
 }
 
 // src/providers/gemini/commands/image-to-video.ts
+init_errors();
 import fs27 from "fs";
 import path28 from "path";
-init_errors();
 function registerGeminiImageToVideoCommand(parent) {
   parent.command("image-to-video <imagePath>").alias("i2v").description("Generate video from a starting image with Veo (image-to-video) [EXPERIMENTAL]").requiredOption("--prompt <text>", "Motion/scene prompt").option("--last-frame <path>", "Optional closing frame image (Veo 3.1)").option("--model <id>", "Veo model id").option("--resolution <res>", "720p|1080p", "1080p").option("--aspect-ratio <ratio>", "Aspect ratio", "16:9").option("--output <path>", "Copy generated video to this path").option("--no-thumb", "Skip downloading the thumbnail if the API returns one").option("-v, --verbose", "Verbose logging").action(
     async (imagePath, opts) => {
       const logger = createLogger({ verbose: opts.verbose ?? false });
-      const apiKey = resolveKey("GEMINI_API_KEY");
-      if (!apiKey) throw new ValidationError("GEMINI_API_KEY is not set");
       const model = opts.model ?? getDefaultModel("generate-video");
       if (!model.startsWith("veo-")) {
         throw new ValidationError(
@@ -4219,7 +4361,6 @@ function registerGeminiImageToVideoCommand(parent) {
       );
       const dest = path28.join(getOutputDir(), `veo_i2v_${Date.now()}.mp4`);
       const finalOp = await runVeo(
-        apiKey,
         model,
         {
           prompt: opts.prompt,
@@ -4264,22 +4405,30 @@ function registerTranscribeCommand2(parent) {
         const filePath = opts.files[i];
         logger.debug(`[${i + 1}/${opts.files.length}] Transcribing: ${filePath}`);
         try {
-          const useApi = shouldUseFileApi(filePath);
-          let contentParts;
-          if (useApi) {
-            logger.debug("File >20MB \u2014 using Files API");
-            const ref = await uploadFile(filePath, { logger });
-            contentParts = [
-              { text: opts.prompt },
-              { fileData: { mimeType: ref.mimeType, fileUri: ref.uri } }
-            ];
-          } else {
-            contentParts = [{ text: opts.prompt }, inlinePart(filePath)];
-          }
-          const resp = await generateContent({
-            model,
-            contents: [{ parts: contentParts }]
-          });
+          const resp = await withGeminiKey(
+            async (apiKey) => {
+              const useApi = shouldUseFileApi(filePath);
+              let contentParts;
+              if (useApi) {
+                logger.debug("File >20MB \u2014 using Files API");
+                const ref = await uploadFile(filePath, { logger, apiKey });
+                contentParts = [
+                  { text: opts.prompt },
+                  { fileData: { mimeType: ref.mimeType, fileUri: ref.uri } }
+                ];
+              } else {
+                contentParts = [{ text: opts.prompt }, inlinePart(filePath)];
+              }
+              return generateContent(
+                {
+                  model,
+                  contents: [{ parts: contentParts }]
+                },
+                { apiKey }
+              );
+            },
+            { logger }
+          );
           results.push({
             file: filePath,
             status: "success",
@@ -6815,6 +6964,10 @@ function registerOpenRouterCommands(program2) {
   registerOpenRouterVideoModelsCommand(openrouter);
 }
 
+// src/commands/check.ts
+import fs43 from "fs";
+import os3 from "os";
+
 // src/commands/check-helpers/binary-check.ts
 import { execa as execa2 } from "execa";
 async function checkBinary(binary, versionFlag = "--version") {
@@ -6940,6 +7093,10 @@ var PROVIDERS = [
   }
 ];
 function resolveProviderKey(p) {
+  if (p.envPrimary === "GEMINI_API_KEY") {
+    const first = listGeminiKeys()[0];
+    return first ? { key: first.value, envUsed: first.name } : {};
+  }
   const primary = resolveKey(p.envPrimary);
   if (primary) return { key: primary, envUsed: p.envPrimary };
   if (p.envFallback) {
@@ -6982,6 +7139,19 @@ function registerCheckCommand(program2) {
       if (opts.verbose) console.log(`  ${MAGICK_HINT}`);
     }
     logger.header("API Keys");
+    if (opts.verbose) {
+      const files = getLoadedEnvFiles();
+      logger.info(`Env files loaded: ${files.length > 0 ? files.join(", ") : "none"}`);
+    }
+    if (!legacyClaudeEnvEnabled()) {
+      const home = process.env.MULTIX_DISABLE_HOME_ENV ? void 0 : os3.homedir();
+      const legacy = legacyClaudeEnvFiles(process.cwd(), home).filter((f) => fs43.existsSync(f));
+      if (legacy.length > 0) {
+        logger.info(
+          `Found ${legacy.length} legacy .claude env file(s); set MULTIX_LEGACY_CLAUDE_ENV=1 to load them`
+        );
+      }
+    }
     let anyKey = false;
     const resolved = /* @__PURE__ */ new Map();
     for (const p of PROVIDERS) {
@@ -6991,6 +7161,14 @@ function registerCheckCommand(program2) {
       const envLabel = r.envUsed ?? p.envPrimary;
       if (r.key) {
         logger.success(`${envLabel} found \u2014 ${redact(r.key)}`);
+        if (p.name === "Gemini") {
+          const pool = listGeminiKeys();
+          if (pool.length > 1) {
+            logger.info(
+              `Gemini key rotation: ${pool.length} keys (${pool.map((k) => k.name).join(", ")})`
+            );
+          }
+        }
       } else if (p.optional) {
         const fbNote = p.envFallback ? ` (or ${p.envFallback})` : "";
         logger.info(`${p.envPrimary}${fbNote} not set (optional)`);
@@ -7036,14 +7214,18 @@ function registerCheckCommand(program2) {
     if (geminiKey) {
       logger.header("Gemini Connectivity");
       logger.info("Pinging Gemini models endpoint...");
-      const ping = await pingGemini(geminiKey);
-      if (ping.status === "success") {
-        logger.success(`Gemini API reachable \u2014 ${ping.modelCount ?? 0} models available`);
-      } else if (ping.status === "auth_error") {
-        logger.error(`Gemini auth failed \u2014 check GEMINI_API_KEY: ${ping.error ?? ""}`);
-        exitCode = 1;
-      } else {
-        logger.warn(`Gemini network error (API may be down): ${ping.error ?? ""}`);
+      for (const key of listGeminiKeys()) {
+        const ping = await pingGemini(key.value);
+        if (ping.status === "success") {
+          logger.success(
+            `${key.name}: Gemini API reachable \u2014 ${ping.modelCount ?? 0} models available`
+          );
+        } else if (ping.status === "auth_error") {
+          logger.error(`Gemini auth failed \u2014 check ${key.name}: ${ping.error ?? ""}`);
+          exitCode = 1;
+        } else {
+          logger.warn(`${key.name}: Gemini network error (API may be down): ${ping.error ?? ""}`);
+        }
       }
     }
     logger.header("Summary");
@@ -7068,7 +7250,7 @@ function registerCheckCommand(program2) {
 
 // src/commands/doc/convert.ts
 init_errors();
-import fs43 from "fs";
+import fs44 from "fs";
 import path45 from "path";
 
 // src/commands/doc/default-prompt.ts
@@ -7090,7 +7272,7 @@ async function convertDocuments(opts) {
   const model = opts.model ?? DOC_MODEL_DEFAULT;
   const prompt = opts.prompt ?? DEFAULT_CONVERT_PROMPT;
   for (const f of inputs) {
-    if (!fs43.existsSync(f)) throw new ValidationError(`Input file not found: ${f}`);
+    if (!fs44.existsSync(f)) throw new ValidationError(`Input file not found: ${f}`);
   }
   let outputPath;
   if (output) {
@@ -7101,7 +7283,7 @@ async function convertDocuments(opts) {
   } else {
     outputPath = path45.join(getOutputDir(), "document-extraction.md");
   }
-  fs43.mkdirSync(path45.dirname(outputPath), { recursive: true });
+  fs44.mkdirSync(path45.dirname(outputPath), { recursive: true });
   const results = [];
   for (let i = 0; i < inputs.length; i++) {
     const filePath = inputs[i];
@@ -7110,26 +7292,35 @@ async function convertDocuments(opts) {
     let errorMsg;
     for (let attempt = 0; attempt < 3; attempt++) {
       try {
-        const useApi = shouldUseFileApi(filePath);
-        let contentParts;
-        if (useApi) {
-          logger?.debug("File >20MB \u2014 using Files API");
-          const ref = await uploadFile(filePath, { logger });
-          contentParts = [
-            { text: prompt },
-            { fileData: { mimeType: ref.mimeType, fileUri: ref.uri } }
-          ];
-        } else {
-          contentParts = [{ text: prompt }, inlinePart(filePath)];
-        }
-        const resp = await generateContent({
-          model,
-          contents: [{ parts: contentParts }]
-        });
+        const resp = await withGeminiKey(
+          async (apiKey) => {
+            const useApi = shouldUseFileApi(filePath);
+            let contentParts;
+            if (useApi) {
+              logger?.debug("File >20MB \u2014 using Files API");
+              const ref = await uploadFile(filePath, { logger, apiKey });
+              contentParts = [
+                { text: prompt },
+                { fileData: { mimeType: ref.mimeType, fileUri: ref.uri } }
+              ];
+            } else {
+              contentParts = [{ text: prompt }, inlinePart(filePath)];
+            }
+            return generateContent(
+              {
+                model,
+                contents: [{ parts: contentParts }]
+              },
+              { apiKey }
+            );
+          },
+          { logger }
+        );
         markdown = extractText(resp);
         break;
       } catch (e) {
         errorMsg = e instanceof Error ? e.message : String(e);
+        if (isGeminiRateLimitError(e)) break;
         if (attempt < 2) {
           const wait = 2 ** attempt * 1e3;
           logger?.debug(`Retry ${attempt + 1} after ${wait / 1e3}s: ${errorMsg}`);
@@ -7165,7 +7356,7 @@ async function convertDocuments(opts) {
     }
     lines.push("\n---\n");
   }
-  fs43.writeFileSync(outputPath, lines.join("\n"), "utf8");
+  fs44.writeFileSync(outputPath, lines.join("\n"), "utf8");
   const succeeded = results.filter((r) => r.status === "success").length;
   console.log(`
 ${"=".repeat(50)}`);
@@ -7213,11 +7404,11 @@ function registerDocCommands(program2) {
 
 // src/commands/media/index.ts
 init_errors();
-import fs46 from "fs";
+import fs47 from "fs";
 import path48 from "path";
 
 // src/commands/media/batch.ts
-import fs44 from "fs";
+import fs45 from "fs";
 import path46 from "path";
 
 // src/commands/media/detect-type.ts
@@ -7414,8 +7605,8 @@ async function batchOptimize(opts) {
     verbose,
     logger
   } = opts;
-  fs44.mkdirSync(outputDir, { recursive: true });
-  const entries = fs44.readdirSync(inputDir);
+  fs45.mkdirSync(outputDir, { recursive: true });
+  const entries = fs45.readdirSync(inputDir);
   const mediaFiles = entries.filter((f) => {
     const ext = path46.extname(f).toLowerCase();
     return ALL_EXTS.has(ext);
@@ -7467,7 +7658,7 @@ async function batchOptimize(opts) {
 
 // src/commands/media/split-video.ts
 init_errors();
-import fs45 from "fs";
+import fs46 from "fs";
 import path47 from "path";
 async function splitVideo(opts) {
   await assertFfmpeg();
@@ -7479,7 +7670,7 @@ async function splitVideo(opts) {
     logger?.info("Video is short enough \u2014 no splitting needed");
     return [input];
   }
-  fs45.mkdirSync(outputDir, { recursive: true });
+  fs46.mkdirSync(outputDir, { recursive: true });
   const ext = path47.extname(input) || ".mp4";
   const baseName = path47.basename(input, ext);
   const outputPattern = path47.join(outputDir, `${baseName}_chunk_%03d${ext}`);
@@ -7502,7 +7693,7 @@ async function splitVideo(opts) {
   const files = [];
   for (let i = 0; i < numChunks + 1; i++) {
     const fname = path47.join(outputDir, `${baseName}_chunk_${String(i).padStart(3, "0")}${ext}`);
-    if (fs45.existsSync(fname)) files.push(fname);
+    if (fs46.existsSync(fname)) files.push(fname);
   }
   logger?.success(`Created ${files.length} chunks in ${outputDir}`);
   return files;
@@ -7516,8 +7707,8 @@ function registerMediaCommands(program2) {
   media.command("optimize").description("Optimize a single media file (video, audio, or image)").requiredOption("--input <file>", "Input media file").requiredOption("--output <file>", "Output file path").option("--target-size <MB>", "Target file size in MB").option("--quality <n>", "Quality: video CRF (0-51) or image (1-100)", "85").option("--max-width <px>", "Max image/video width in pixels", "1920").option("--bitrate <rate>", "Audio bitrate (e.g. 64k)", "64k").option("--resolution <WxH>", "Force video resolution (e.g. 1920x1080)").option("-v, --verbose", "Verbose logging").action(
     async (opts) => {
       const logger = createLogger({ verbose: opts.verbose ?? false });
-      if (!fs46.existsSync(opts.input)) throw new ValidationError(`Input not found: ${opts.input}`);
-      fs46.mkdirSync(path48.dirname(path48.resolve(opts.output)), { recursive: true });
+      if (!fs47.existsSync(opts.input)) throw new ValidationError(`Input not found: ${opts.input}`);
+      fs47.mkdirSync(path48.dirname(path48.resolve(opts.output)), { recursive: true });
       const ext = path48.extname(opts.input).toLowerCase();
       const kind = extToKind(ext);
       if (!kind) throw new ValidationError(`Unsupported file type: ${ext}`);
@@ -7558,7 +7749,7 @@ function registerMediaCommands(program2) {
   media.command("split").description("Split a long video into fixed-duration chunks").requiredOption("--input <file>", "Input video file").option("--output-dir <dir>", "Output directory for chunks", "./chunks").option("--chunk-duration <sec>", "Chunk duration in seconds", "3600").option("-v, --verbose", "Verbose logging").action(
     async (opts) => {
       const logger = createLogger({ verbose: opts.verbose ?? false });
-      if (!fs46.existsSync(opts.input)) throw new ValidationError(`Input not found: ${opts.input}`);
+      if (!fs47.existsSync(opts.input)) throw new ValidationError(`Input not found: ${opts.input}`);
       const chunks = await splitVideo({
         input: opts.input,
         outputDir: opts.outputDir,
@@ -7574,7 +7765,7 @@ Created ${chunks.length} chunk(s) in ${opts.outputDir}`);
   media.command("batch").description("Batch optimize all media files in a directory").requiredOption("--input-dir <dir>", "Input directory").requiredOption("--output-dir <dir>", "Output directory").option("--quality <n>", "Quality setting", "85").option("--max-width <px>", "Max image/video width", "1920").option("--bitrate <rate>", "Audio bitrate", "64k").option("-v, --verbose", "Verbose logging").action(
     async (opts) => {
       const logger = createLogger({ verbose: opts.verbose ?? false });
-      if (!fs46.existsSync(opts.inputDir))
+      if (!fs47.existsSync(opts.inputDir))
         throw new ValidationError(`Input dir not found: ${opts.inputDir}`);
       const result = await batchOptimize({
         inputDir: opts.inputDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrgoonie/multix",
-  "version": "0.7.3",
+  "version": "0.9.0",
   "description": "AI multimodal CLI — OpenAI, Gemini, MiniMax, OpenRouter, Leonardo, BytePlus, ElevenLabs, fal.ai, ffmpeg, ImageMagick, doc-to-md",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: multix
 description: AI multimodal CLI — generate and edit images (OpenAI, Codex driver, Gemini Nano Banana, Imagen, MiniMax, OpenRouter, Leonardo, BytePlus Seedream, Cloudflare Workers AI FLUX.1 Schnell, fal.ai FLUX), generate video (Gemini Veo, MiniMax Hailuo, OpenRouter via Veo/Seedance/Kling, Leonardo via Motion/Veo/Kling/Hailuo/Seedance/LTX, BytePlus Seedance, Cloudflare AI Gateway via Replicate, fal.ai queue models), TTS/STT/music (OpenAI, Gemini Flash TTS incl. Gemini 3.8 with delivery-style control, MiniMax, Cloudflare Workers AI MeloTTS, ElevenLabs), 3D models (BytePlus Hyper3D/Hitem3d), analyze/transcribe media, convert documents to Markdown, optimize media via ffmpeg/ImageMagick, and self-update the CLI. Use whenever the user wants to create, edit, or transform images/video/audio/3D/documents from a CLI, mentions any of: OpenAI, Codex image driver, image-to-image, i2i, image edit, watercolor/cyberpunk style transfer, reference image, OpenRouter, Nano Banana, Flux, Seedream, Veo, Hailuo, Seedance, Kling, Cloudflare Workers AI, AI Gateway, fal.ai, video generation, text-to-video, image-to-video, i2v, ElevenLabs voice cloning, updating/upgrading multix, or asks for batch media optimization.
-version: 0.7.3 # x-release-please-version
+version: 0.9.0 # x-release-please-version
 ---
 
 # multix — AI Multimodal CLI
@@ -35,7 +35,7 @@ Detects whether `multix` was installed via npm, pnpm, yarn, or bun global instal
 ## Required env (set at least one provider key)
 
 ```
-GEMINI_API_KEY        # Google AI Studio
+GEMINI_API_KEY        # Google AI Studio (extra keys: GEMINI_API_KEY_2, _3, … rotate on 429/RESOURCE_EXHAUSTED)
 OPENAI_API_KEY        # OpenAI API (image, image edit, TTS, STT)
 OPENROUTER_API_KEY    # OpenRouter (multi-model gateway: image + video via Veo, Seedance, Kling)
 MINIMAX_API_KEY       # MiniMax (image/video/speech/music)
@@ -48,7 +48,7 @@ CLOUDFLARE_API_TOKEN  # Cloudflare Workers AI / AI Gateway token
 # Video additionally requires CLOUDFLARE_AI_GATEWAY_ID and REPLICATE_API_TOKEN.
 ```
 
-Priority: `process.env` > `cwd/.env` > `~/.multix/.env`.
+Priority: `process.env` > `cwd/.env` > `~/.multix/.env`. Set `MULTIX_LEGACY_CLAUDE_ENV=1` to also read legacy AgentKit `.claude` env files (credential names only, lowest priority); `multix check -v` lists loaded env files.
 
 ## Gemini text-output tasks
 
@@ -323,7 +323,8 @@ Requires `cwebp` (libwebp: `brew install webp`, `apt install webp`) on `PATH`.
 | `CLOUDFLARE_AI_GATEWAY_COLLECT_LOG_PAYLOAD` | Set `true` to explicitly opt in to AI Gateway request-payload collection; defaults to `false` |
 | `REPLICATE_API_TOKEN` | Required for Cloudflare AI Gateway video |
 | `CLOUDFLARE_AI_IMAGE_MODEL` / `CLOUDFLARE_AI_TTS_MODEL` | Fixed-model settings: only `@cf/black-forest-labs/flux-1-schnell` and `@cf/myshell-ai/melotts` respectively are accepted |
-| `MULTIX_DISABLE_HOME_ENV` | `1` to skip `~/.multix/.env` |
+| `MULTIX_DISABLE_HOME_ENV` | `1` to skip every home-directory env file (`~/.multix/.env`, `~/.claude/...`) |
+| `MULTIX_LEGACY_CLAUDE_ENV` | `1` to also read legacy `.claude` env files (credential names only) |
 
 ## Quick examples for agents