@mrgoonie/multix 0.13.0 → 0.14.1

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.14.1](https://github.com/mrgoonie/multix-cli/compare/v0.14.0...v0.14.1) (2026-10-11)
+
+
+### Fixed
+
+* **replicate:** harden output downloads, --prefer-wait and create errors ([#88](https://github.com/mrgoonie/multix-cli/issues/88)) ([e29e81d](https://github.com/mrgoonie/multix-cli/commit/e29e81d7b3e54e5b65f4905c1adb629f2d4df6c4))
+
+## [0.14.0](https://github.com/mrgoonie/multix-cli/compare/v0.13.0...v0.14.0) (2026-10-11)
+
+
+### Added
+
+* **doc:** read convert input from piped stdin ([#84](https://github.com/mrgoonie/multix-cli/issues/84)) ([4596f7f](https://github.com/mrgoonie/multix-cli/commit/4596f7f09da2e8e7a95582296c220f4e007e3171))
+
+
+### Fixed
+
+* **heygen:** harden base URL, output downloads and multi-output paths ([#83](https://github.com/mrgoonie/multix-cli/issues/83)) ([fea7a95](https://github.com/mrgoonie/multix-cli/commit/fea7a950bdf37836a5344301829b028efe4c9a6d))
+
 ## [0.13.0](https://github.com/mrgoonie/multix-cli/compare/v0.12.0...v0.13.0) (2026-10-11)
 
 

package/README.md

@@ -71,7 +71,7 @@ Set at least one provider key. Add to `.env` in your project root or `~/.multix/
 | `FAL_IMAGE_MODEL` | No | Default fal image model (default `fal-ai/flux/schnell`) |
 | `FAL_VIDEO_MODEL` | No | Default fal text-to-video model (default `fal-ai/kling-video/v1.6/standard/text-to-video`) |
 | `HEYGEN_API_KEY` | For HeyGen | [HeyGen API settings](https://app.heygen.com/developers/api). API usage is billed separately from HeyGen web plans |
-| `HEYGEN_BASE_URL` | No | Override the HeyGen API base (default `https://api.heygen.com`; proxies/tests) |
+| `HEYGEN_BASE_URL` | No | Override the HeyGen API base (default `https://api.heygen.com`; proxies/tests). Must be `https://`, except `http://` on `localhost`/`127.0.0.1`/`[::1]` |
 | `FAL_VIDEO_IMAGE_MODEL` | No | Default fal image-to-video model, used when `--image-url` is passed without `-m` (default `fal-ai/kling-video/v1.6/standard/image-to-video`) |
 | `ATLASCLOUD_API_KEY` | For Atlas Cloud | [Atlas Cloud](https://www.atlascloud.ai/console/api-keys) |
 | `ATLASCLOUD_BASE_URL` | No | Override Atlas Cloud media API base (default `https://api.atlascloud.ai/api/v1`) |
@@ -98,6 +98,7 @@ Set at least one provider key. Add to `.env` in your project root or `~/.multix/
 | `CLOUDFLARE_AI_IMAGE_MODEL` | No | Image model setting; only `@cf/black-forest-labs/flux-1-schnell` is accepted |
 | `CLOUDFLARE_AI_TTS_MODEL` | No | Speech model setting; only `@cf/myshell-ai/melotts` is accepted |
 | `MULTIX_OUTPUT_DIR` | No | Override default output dir (`./multix-output`) |
+| `MULTIX_MAX_DOWNLOAD_MB` | No | Size limit per downloaded Replicate output file (default `2048`) |
 | `MULTIX_IMAGE_FORMAT` | No | `webp` (default) or `original` to keep provider image format/quality |
 | `OPENROUTER_IMAGE_MODEL` | No | Default OpenRouter model |
 | `OPENROUTER_FALLBACK_MODELS` | No | Comma-separated fallback model ids |
@@ -556,9 +557,11 @@ multix replicate cancel <prediction-id>
 
 **Notes:**
 - Auth: `Authorization: Bearer $REPLICATE_API_TOKEN` (`REPLICATE_API_KEY` accepted as fallback).
-- Default behavior waits with bounded polling; `--async` prints the prediction id plus resume/cancel commands. `--prefer-wait` sends `Prefer: wait=N` and keeps polling if the job is still running.
+- Default behavior waits with bounded polling; `--async` prints the prediction id plus resume/cancel commands. `--prefer-wait [seconds]` (an integer from 1 to 60; the bare flag means 60) sends `Prefer: wait=N` and keeps polling if the job is still running. Put the prompt before a bare `--prefer-wait`; any other value is rejected.
 - Only `succeeded` exits 0; `failed`, `canceled`, and `aborted` exit non-zero with Replicate's error.
+- If submitting fails with a network error, timeout, 5xx, or an unreadable 2xx response, the prediction may still have been created and billed (Replicate has no idempotency key). Check https://replicate.com/predictions before retrying.
 - Every media URL in the output (string, list, or nested object) is downloaded as `replicate-<id8>-NN.<ext>` (`<id8>` = first 8 characters of the prediction id); text outputs are printed. Output URLs expire, so download promptly. If any download fails, the command exits non-zero and prints `multix replicate status <id> --download` to retry.
+- Output downloads use `https://` only and refuse `localhost` and loopback, private, link-local, or other special-purpose IP literals (hostnames are not resolved), including on redirects. Files are written to `<path>.part` and renamed when complete, so a failed download never clobbers an existing file. Hosts other than `replicate.delivery` are downloaded with a warning that names the host. Each file is capped at `MULTIX_MAX_DOWNLOAD_MB` (default 2048).
 - `replicate image` converts images to WebP by default; `--image-format original`, `--no-webp`, `MULTIX_IMAGE_FORMAT=original`, an explicit `--output-format`, or a non-`.webp` `--output` extension keeps the provider format.
 - Local files (`--image`, `--file key=path`) up to 256 KB are inlined as data URIs; larger files (< 100 MB) are uploaded via the Replicate Files API.
 
@@ -581,7 +584,7 @@ multix heygen video --avatar <look-id> --audio ./voiceover.mp3
 
 # Translation (one job per language; all are downloaded), lipsync, TTS
 multix heygen languages
-multix heygen translate ./talk.mp4 --languages "Spanish, Chinese (Cantonese, Traditional)" [--mode speed|precision] [--output <dir>]
+multix heygen translate ./talk.mp4 --languages "Spanish, Chinese (Cantonese, Traditional)" [--mode speed|precision] [--output <dir|dub.mp4>]   # dub.mp4 -> dub-Spanish.mp4, ...
 multix heygen lipsync --video <ref> --audio <ref>
 multix heygen tts "Welcome to the show." --voice <voice-id> [--output hello.mp3]
 
@@ -624,13 +627,17 @@ multix media batch --input-dir <dir> --output-dir <dir> [--quality 85] [--max-wi
 ### `multix doc`
 
 ```bash
-multix doc convert --input <files...> [--output <path>] [--auto-name] [--model gemini-3.6-flash] [--prompt <str>] [-v]
+multix doc convert --input <files...> [--output <path>] [--auto-name] [--stdin-ext <ext>] [--model gemini-3.6-flash] [--prompt <str>] [-v]
+
+# Read piped stdin with "-" (PDF, images and text auto-detected; else pass --stdin-ext, e.g. pdf; "-" only once, ./- for a file named -)
+cat report.pdf | multix doc convert --input - --output report.md
 ```
 
 Converts PDFs, DOCX/XLSX/PPTX, images, and HTML/text files to Markdown via Gemini.
 Multiple inputs are concatenated with `---` separators into a single output.
+Piped stdin is labelled `<stdin>` in the output and error messages; its temp file is removed when the command ends.
 
-**Default output:** `./multix-output/document-extraction.md`
+**Default output:** `./multix-output/document-extraction.md` (with `--auto-name`: `<input-basename>-extraction.md`, or `stdin-extraction.md` for piped input)
 
 ## Output
 

package/dist/cli.js

@@ -1120,40 +1120,168 @@ import fs8 from "fs";
 import path7 from "path";
 
 // src/core/http-client.ts
-init_errors();
-import { once } from "events";
 import fs3 from "fs";
 import path3 from "path";
+import { Readable } from "stream";
 import { pipeline } from "stream/promises";
+init_errors();
+init_redact();
 async function httpJson(opts) {
   return fetchJson(opts);
 }
-async function downloadFile(url, dest, timeoutMs = DEFAULT_TIMEOUT_MS, headers2) {
-  fs3.mkdirSync(path3.dirname(dest), { recursive: true });
-  let response;
-  try {
-    response = await globalThis.fetch(url, {
-      signal: AbortSignal.timeout(timeoutMs),
-      ...headers2 ? { headers: headers2 } : {}
+var MAX_DOWNLOAD_ENV = "MULTIX_MAX_DOWNLOAD_MB";
+var DEFAULT_MAX_DOWNLOAD_MB = 2048;
+var MAX_REDIRECTS = 5;
+function formatMb2(bytes) {
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+var DownloadTooLargeError = class extends MultixError {
+  constructor(limitBytes, url) {
+    super(
+      `Download from ${redactUrl(url)} exceeds the ${formatMb2(limitBytes)} limit (set ${MAX_DOWNLOAD_ENV} to change it)`,
+      "DOWNLOAD_TOO_LARGE"
+    );
+    this.limitBytes = limitBytes;
+    this.name = "DownloadTooLargeError";
+  }
+  limitBytes;
+};
+function maxDownloadBytes() {
+  const raw = resolveKey(MAX_DOWNLOAD_ENV)?.trim();
+  if (!raw) return DEFAULT_MAX_DOWNLOAD_MB * 1024 * 1024;
+  const mb = Number(raw);
+  if (!Number.isFinite(mb) || mb <= 0) {
+    throw new ConfigError(
+      `${MAX_DOWNLOAD_ENV} must be a positive number of megabytes, got "${raw}"`
+    );
+  }
+  const bytes = Math.floor(mb * 1024 * 1024);
+  if (bytes < 1) {
+    throw new ConfigError(`${MAX_DOWNLOAD_ENV} is too small: "${raw}" MB is less than one byte`);
+  }
+  return bytes;
+}
+async function fetchWithValidatedRedirects(url, opts = {}) {
+  const doFetch = opts.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  const { validateUrl, signal } = opts;
+  const maxRedirects = opts.maxRedirects ?? MAX_REDIRECTS;
+  let current = url;
+  let headers2 = opts.headers;
+  for (let hop = 0; ; hop++) {
+    await validateUrl?.(current);
+    let response;
+    try {
+      response = await doFetch(current, {
+        ...signal ? { signal } : {},
+        ...headers2 ? { headers: headers2 } : {},
+        ...validateUrl ? { redirect: "manual" } : {}
+      });
+    } catch (cause) {
+      const msg = cause instanceof Error ? cause.message : String(cause);
+      throw new HttpError(0, msg, current);
+    }
+    const location = response.headers.get("location");
+    if (!validateUrl || !location || response.status < 300 || response.status >= 400) {
+      return { response, url: current };
+    }
+    await response.body?.cancel().catch(() => {
     });
-  } catch (cause) {
-    const msg = cause instanceof Error ? cause.message : String(cause);
-    throw new HttpError(0, msg, url);
+    if (hop >= maxRedirects) {
+      throw new HttpError(response.status, `too many redirects (over ${maxRedirects})`, current);
+    }
+    let next;
+    try {
+      next = new URL(location, current);
+    } catch {
+      throw new HttpError(response.status, "redirect with a malformed Location header", current);
+    }
+    if (next.origin !== new URL(current).origin) headers2 = void 0;
+    current = next.toString();
+  }
+}
+function removeQuietly(file) {
+  try {
+    fs3.rmSync(file, { force: true });
+  } catch {
   }
+}
+function replaceFile(from, to) {
+  try {
+    fs3.renameSync(from, to);
+  } catch (err2) {
+    const code = err2.code;
+    const existing = fs3.statSync(to, { throwIfNoEntry: false });
+    if (!existing?.isFile() || code !== "EEXIST" && code !== "EPERM" && code !== "EACCES") {
+      throw err2;
+    }
+    fs3.rmSync(to, { force: true });
+    fs3.renameSync(from, to);
+  }
+}
+async function downloadToFile(url, opts) {
+  const signal = AbortSignal.timeout(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  const { response, url: finalUrl } = await fetchWithValidatedRedirects(url, {
+    signal,
+    headers: opts.headers,
+    validateUrl: opts.validateUrl,
+    fetch: opts.fetch
+  });
   if (!response.ok) {
-    throw new HttpError(response.status, "(download failed)", url);
+    await response.body?.cancel().catch(() => {
+    });
+    throw new HttpError(response.status, "(download failed)", finalUrl);
   }
   if (!response.body) {
-    throw new HttpError(0, "Response body is null", url);
+    throw new HttpError(0, "Response body is null", finalUrl);
+  }
+  const body = response.body;
+  const { maxBytes } = opts;
+  const declared = Number(response.headers.get("content-length") ?? Number.NaN);
+  if (maxBytes !== void 0 && Number.isFinite(declared) && declared > maxBytes) {
+    await body.cancel().catch(() => {
+    });
+    throw new DownloadTooLargeError(maxBytes, finalUrl);
+  }
+  let dest;
+  try {
+    dest = typeof opts.dest === "function" ? opts.dest(response) : opts.dest;
+    fs3.mkdirSync(path3.dirname(dest), { recursive: true });
+  } catch (err2) {
+    await body.cancel().catch(() => {
+    });
+    throw err2;
   }
-  const fileStream = fs3.createWriteStream(dest);
+  let bytes = 0;
+  async function* countBytes(source) {
+    for await (const chunk of source) {
+      bytes += chunk.byteLength;
+      if (maxBytes !== void 0 && bytes > maxBytes)
+        throw new DownloadTooLargeError(maxBytes, finalUrl);
+      yield chunk;
+    }
+  }
+  const part = `${dest}.part`;
+  let fileStream;
   try {
-    await pipeline(response.body, fileStream);
+    fileStream = fs3.createWriteStream(part);
+    await pipeline(
+      Readable.fromWeb(body),
+      countBytes,
+      fileStream
+    );
+    replaceFile(part, dest);
   } catch (err2) {
-    if (!fileStream.closed) await once(fileStream, "close");
+    if (fileStream && !fileStream.closed) {
+      await new Promise((resolve) => fileStream?.once("close", () => resolve()));
+    }
+    removeQuietly(part);
     throw err2;
   }
-  return response.headers.get("content-type") ?? void 0;
+  return { dest, contentType: response.headers.get("content-type") ?? void 0, bytes };
+}
+async function downloadFile(url, dest, timeoutMs = DEFAULT_TIMEOUT_MS, headers2) {
+  const result = await downloadToFile(url, { dest, timeoutMs, headers: headers2 });
+  return result.contentType;
 }
 async function fetchBytes(urlOrDataUri) {
   if (urlOrDataUri.startsWith("data:")) {
@@ -1428,14 +1556,14 @@ function detectThumbUrl(obj) {
   }
   return null;
 }
-async function downloadThumbBeside(thumbUrl, videoPath, logger) {
+async function downloadThumbBeside(thumbUrl, videoPath, logger, download = downloadFile) {
   const match = thumbUrl.match(IMAGE_EXT_RE);
   const ext = match?.[1] ? match[1].toLowerCase().replace("jpeg", "jpg") : "jpg";
   const dir = path6.dirname(videoPath);
   const base = path6.basename(videoPath, path6.extname(videoPath));
   const dest = path6.join(dir, `${base}_thumb.${ext}`);
   try {
-    await downloadFile(thumbUrl, dest);
+    await download(thumbUrl, dest);
     logger?.success(`Saved thumb ${dest}`);
     return dest;
   } catch (e) {
@@ -1450,7 +1578,7 @@ async function maybeDownloadThumb(source, videoPath, opts = {}) {
     opts.logger?.debug("No thumbnail URL detected in provider response");
     return null;
   }
-  const saved = await downloadThumbBeside(url, videoPath, opts.logger);
+  const saved = await downloadThumbBeside(url, videoPath, opts.logger, opts.download);
   if (saved && opts.copyTo) {
     const copyExt = path6.extname(saved);
     const copyBase = path6.basename(opts.copyTo, path6.extname(opts.copyTo));
@@ -4611,11 +4739,15 @@ function trackTempDir(dir) {
   for (const s of SIGNALS) process.once(s, onSignal);
   return dispose;
 }
+var DEFAULT_FLAG = "--files";
+var DEFAULT_EXAMPLE = "cat clip.mp3 | multix gemini transcribe --files -";
+var DEFAULT_EXT_EXAMPLE = "mp3";
 async function stdinToTempFile(opts = {}) {
   const input = opts.input ?? process.stdin;
+  const flag = opts.flag ?? DEFAULT_FLAG;
   if (input.isTTY) {
     throw new ValidationError(
-      "`--files -` reads piped input, but stdin is a terminal. Example: cat clip.mp3 | multix gemini transcribe --files -"
+      `\`${flag} -\` reads piped input, but stdin is a terminal. Example: ${opts.example ?? DEFAULT_EXAMPLE}`
     );
   }
   const forcedExt = opts.ext ? normalizeExt(opts.ext) : void 0;
@@ -4624,7 +4756,8 @@ async function stdinToTempFile(opts = {}) {
   const cleanup = trackTempDir(dir);
   const rawPath = path23.join(dir, "input");
   const hint = setTimeout(() => {
-    process.stderr.write("Waiting for data on stdin (`--files -`)... press Ctrl+C to cancel\n");
+    process.stderr.write(`Waiting for data on stdin (\`${flag} -\`)... press Ctrl+C to cancel
+`);
   }, WAIT_HINT_MS);
   hint.unref?.();
   let head = Buffer.alloc(0);
@@ -4651,7 +4784,7 @@ async function stdinToTempFile(opts = {}) {
       clearTimeout(hint);
       fs20.closeSync(fd);
     }
-    if (size === 0) throw new ValidationError("`--files -` was given but stdin was empty");
+    if (size === 0) throw new ValidationError(`\`${flag} -\` was given but stdin was empty`);
     const detectedExt = forcedExt ?? detectExtension(head);
     const finalPath = path23.join(dir, `stdin${detectedExt ?? ".bin"}`);
     fs20.renameSync(rawPath, finalPath);
@@ -4665,10 +4798,11 @@ function labelError(message, input) {
   return input.path === input.label ? message : message.split(input.path).join(input.label);
 }
 async function resolveFileInputs(files, opts = {}) {
+  const flag = opts.flag ?? DEFAULT_FLAG;
   const stdinCount = files.filter((f) => f === STDIN_ARG).length;
-  if (stdinCount > 1) throw new ValidationError("`-` (stdin) can only be passed once to --files");
+  if (stdinCount > 1) throw new ValidationError(`\`-\` (stdin) can only be passed once to ${flag}`);
   if (opts.stdinExt && stdinCount === 0) {
-    throw new ValidationError("--stdin-ext only applies when --files includes `-`");
+    throw new ValidationError(`--stdin-ext only applies when ${flag} includes \`-\``);
   }
   for (const f of files) {
     if (f !== STDIN_ARG && !fs20.existsSync(f)) throw new ValidationError(`File not found: ${f}`);
@@ -4680,12 +4814,14 @@ async function resolveFileInputs(files, opts = {}) {
   const stdin = await stdinToTempFile({
     input: opts.input,
     ext: opts.stdinExt,
-    maxBytes: opts.maxBytes
+    maxBytes: opts.maxBytes,
+    flag: opts.flag,
+    example: opts.example
   });
   if (!stdin.detected) {
     stdin.cleanup();
     throw new ValidationError(
-      "Could not detect the type of piped stdin; pass --stdin-ext (e.g. --stdin-ext mp3)"
+      `Could not detect the type of piped stdin; pass --stdin-ext (e.g. --stdin-ext ${opts.extExample ?? DEFAULT_EXT_EXAMPLE})`
     );
   }
   return {
@@ -6072,8 +6208,10 @@ var HEYGEN_OPERATIONS = {
 };
 
 // src/providers/heygen/node-helpers.ts
+import { once } from "events";
 import fs29 from "fs";
 import path32 from "path";
+import { pipeline as pipeline2 } from "stream/promises";
 init_errors();
 init_redact();
 
@@ -6503,6 +6641,7 @@ function videoState(video, kind = "video", id = video.id, opts = {}) {
   return state;
 }
 function translationState(t) {
+  const audioOnly = !str(t.video_url) && !!str(t.audio_url);
   return {
     kind: "translation",
     id: t.id,
@@ -6510,6 +6649,7 @@ function translationState(t) {
     done: t.status === "completed" || t.status === "failed",
     succeeded: t.status === "completed",
     outputUrl: str(t.video_url) ?? str(t.audio_url),
+    ...audioOnly ? { outputIsAudio: true } : {},
     captionUrl: str(t.srt_caption_url) ?? str(t.vtt_caption_url),
     outputLanguage: str(t.output_language),
     failureMessage: str(t.failure_message),
@@ -6632,13 +6772,29 @@ function getJobState(client, kind, id, opts = {}) {
   return createJobStatusReader(client, kind, id, opts)();
 }
 var DEFAULT_POLL_INTERVAL_MS = 1e4;
-function waitForJob(client, kind, id, opts) {
-  const { burnCaptions, ...poll2 } = opts;
+var STAGGER_STEP_MS = 500;
+var STAGGER_MAX_MS = 5e3;
+function staggerOffsetMs(index, intervalMs) {
+  if (!Number.isFinite(index) || index <= 0) return 0;
+  const step = Math.min(STAGGER_STEP_MS, Math.max(0, intervalMs));
+  return Math.min(index * step, STAGGER_MAX_MS);
+}
+var defaultSleep3 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function waitForJob(client, kind, id, opts) {
+  const { burnCaptions, startDelayMs = 0, ...poll2 } = opts;
+  let pendingDelay = Math.min(Math.max(0, startDelayMs), Math.floor(poll2.timeoutMs / 2));
+  const read = createJobStatusReader(client, kind, id, { burnCaptions });
   return pollUntil({
     intervalMs: DEFAULT_POLL_INTERVAL_MS,
     maxIntervalMs: 3e4,
     ...poll2,
-    fetchStatus: createJobStatusReader(client, kind, id, { burnCaptions }),
+    fetchStatus: async (ctx) => {
+      const delay = pendingDelay;
+      if (delay <= 0) return read(ctx);
+      pendingDelay = 0;
+      await (poll2.sleep ?? defaultSleep3)(delay);
+      return read({ remainingMs: Math.max(1, ctx.remainingMs - delay) });
+    },
     isTerminal: (s) => s.done
   });
 }
@@ -6662,6 +6818,7 @@ function resumeCommand2(kind, id, opts = {}) {
 
 // src/providers/heygen/request-builders.ts
 init_errors();
+init_redact();
 function oneOf(value, allowed, flag) {
   if (value === void 0) return void 0;
   if (!allowed.includes(value)) {
@@ -6683,6 +6840,30 @@ function requireHttps(url, flag) {
   if (!/^https:\/\//i.test(url)) throw new ValidationError(`${flag} must be an https:// URL`);
   return url;
 }
+function isHttpsUrl(url) {
+  try {
+    return new URL(url).protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+function checkBaseUrl(raw, variable) {
+  const value = raw.trim();
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new ConfigError(`${variable} must be an absolute https:// URL`);
+  }
+  const loopbackHttp = url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+  if (url.protocol !== "https:" && !loopbackHttp) {
+    throw new ConfigError(
+      `${variable} must use https:// (got ${redactUrl(value)}); plain http:// is only allowed for localhost, 127.0.0.1, or [::1]`
+    );
+  }
+  return value;
+}
 function classifyMediaRef(value) {
   const v = value.trim();
   if (!v) throw new ValidationError("Media reference must not be empty");
@@ -6948,9 +7129,11 @@ function requireHeygenKey() {
   return key;
 }
 function createHeygenClientFromEnv() {
+  const apiKey = requireHeygenKey();
+  const override = resolveKey("HEYGEN_BASE_URL")?.trim();
   return new HeygenClient({
-    apiKey: requireHeygenKey(),
-    baseUrl: resolveKey("HEYGEN_BASE_URL") ?? DEFAULT_HEYGEN_BASE_URL
+    apiKey,
+    baseUrl: override ? checkBaseUrl(override, "HEYGEN_BASE_URL") : DEFAULT_HEYGEN_BASE_URL
   });
 }
 async function uploadLocalFile(client, filePath, logger) {
@@ -7012,9 +7195,15 @@ function addWaitOptions(cmd, defaultTimeoutMs = DEFAULT_WAIT_TIMEOUT_MS) {
     "--poll-interval <ms>",
     "Initial poll interval (backs off to 30s)",
     String(DEFAULT_POLL_INTERVAL_MS)
-  ).option("--no-download", "Do not download outputs; print output URLs instead").option("--output <path>", "Output file (or directory when several outputs are produced)").option("--captions", "Also download the caption/subtitle file when one is available").option("--no-thumb", "Skip downloading the video thumbnail").option("--json", "Print a JSON summary instead of human-readable output").option("-v, --verbose", "Verbose logging");
-}
-var OUTPUT_EXTS = /* @__PURE__ */ new Set(["mp4", "webm", "mov", "mp3", "wav", "m4a", "aac", "srt", "vtt"]);
+  ).option("--no-download", "Do not download outputs; print output URLs instead").option(
+    "--output <path>",
+    "Output file or directory. A path ending in / or \\, an existing directory, or a path without an extension is a directory; with several outputs, a media file name gets a per-language suffix (dub.mp4 -> dub-Spanish.mp4)"
+  ).option("--captions", "Also download the caption/subtitle file when one is available").option("--no-thumb", "Skip downloading the video thumbnail").option("--json", "Print a JSON summary instead of human-readable output").option("-v, --verbose", "Verbose logging");
+}
+var VIDEO_EXTS = /* @__PURE__ */ new Set(["mp4", "webm", "mov"]);
+var AUDIO_EXTS = /* @__PURE__ */ new Set(["mp3", "wav", "m4a", "aac"]);
+var MEDIA_EXTS = /* @__PURE__ */ new Set([...VIDEO_EXTS, ...AUDIO_EXTS]);
+var OUTPUT_EXTS = /* @__PURE__ */ new Set([...MEDIA_EXTS, "srt", "vtt"]);
 function inferExtension(url, fallback) {
   try {
     const ext = path32.extname(new URL(url).pathname).slice(1).toLowerCase();
@@ -7026,16 +7215,57 @@ function inferExtension(url, fallback) {
 function safeSlug(value) {
   return value.replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "out";
 }
+var MAX_REDIRECTS2 = 5;
+var isRedirect = (status) => [301, 302, 303, 307, 308].includes(status);
+async function downloadHttpsOnly(url, dest, timeoutMs) {
+  const signal = AbortSignal.timeout(timeoutMs);
+  let current = url;
+  for (let hop = 0; ; hop++) {
+    if (!isHttpsUrl(current)) {
+      throw new HttpError(0, "refusing to follow a redirect to a non-https URL", current);
+    }
+    let response;
+    try {
+      response = await globalThis.fetch(current, { signal, redirect: "manual" });
+    } catch (cause) {
+      throw new HttpError(0, cause instanceof Error ? cause.message : String(cause), current);
+    }
+    if (response.url && !isHttpsUrl(response.url)) {
+      await response.body?.cancel();
+      throw new HttpError(0, "redirected to a non-https URL", response.url);
+    }
+    const location = response.headers.get("location");
+    if (isRedirect(response.status) && location) {
+      await response.body?.cancel();
+      if (hop >= MAX_REDIRECTS2) throw new HttpError(0, "too many redirects", url);
+      current = new URL(location, current).href;
+      continue;
+    }
+    if (!response.ok) throw new HttpError(response.status, "(download failed)", current);
+    if (!response.body) throw new HttpError(0, "Response body is null", current);
+    fs29.mkdirSync(path32.dirname(dest), { recursive: true });
+    const fileStream = fs29.createWriteStream(dest);
+    try {
+      await pipeline2(response.body, fileStream);
+    } catch (err2) {
+      if (!fileStream.closed) await once(fileStream, "close");
+      throw err2;
+    }
+    return;
+  }
+}
 async function downloadOutput(url, dest, resumeHint) {
   if (!url) {
     throw new ValidationError(`HeyGen reported success but returned no output URL. ${resumeHint}`);
   }
-  if (!/^https?:\/\//i.test(url)) {
-    throw new ValidationError(`HeyGen returned an invalid output URL (${redactUrl(url)})`);
+  if (!isHttpsUrl(url)) {
+    throw new ValidationError(
+      `Refusing to download HeyGen output from a non-https URL (${redactUrl(url)})`
+    );
   }
   const tmp = `${dest}.${process.pid}-${Date.now()}.part`;
   try {
-    await downloadFile(url, tmp, 6e5);
+    await downloadHttpsOnly(url, tmp, 6e5);
     fs29.renameSync(tmp, dest);
   } catch (e) {
     fs29.rmSync(tmp, { force: true });
@@ -7052,15 +7282,55 @@ function defaultOutputPath(state, ext) {
   const lang = state.outputLanguage ? `-${safeSlug(state.outputLanguage)}` : "";
   return path32.join(getOutputDir(), `heygen-${state.kind}${lang}-${safeSlug(state.id)}.${ext}`);
 }
-function outputPathFor(state, ext, output, count) {
-  if (!output) return defaultOutputPath(state, ext);
-  if (count > 1) {
-    const dir = path32.resolve(output);
-    fs29.mkdirSync(dir, { recursive: true });
-    return path32.join(dir, path32.basename(defaultOutputPath(state, ext)));
+function statOrUndefined(p) {
+  try {
+    return fs29.statSync(p);
+  } catch {
+    return void 0;
   }
-  return path32.resolve(output);
 }
+function isDirectoryOutput2(output, target) {
+  if (/[\\/]$/.test(output)) return true;
+  const stat = statOrUndefined(target);
+  if (stat) return stat.isDirectory();
+  return path32.extname(target) === "";
+}
+function withMediaExt(file, ext) {
+  const given = path32.extname(file).slice(1).toLowerCase();
+  const mismatch = VIDEO_EXTS.has(given) && AUDIO_EXTS.has(ext) || AUDIO_EXTS.has(given) && VIDEO_EXTS.has(ext);
+  return mismatch ? `${file.slice(0, -(given.length + 1))}.${ext}` : file;
+}
+function outputPathFor(state, ext, output, count) {
+  if (!output) return defaultOutputPath(state, ext);
+  const target = path32.resolve(output);
+  const givenExt = path32.extname(target);
+  const isTemplate = count > 1 && MEDIA_EXTS.has(givenExt.slice(1).toLowerCase());
+  if (isDirectoryOutput2(output, target) || count > 1 && !isTemplate) {
+    fs29.mkdirSync(target, { recursive: true });
+    return path32.join(target, path32.basename(defaultOutputPath(state, ext)));
+  }
+  if (!isTemplate) return withMediaExt(target, ext);
+  const base = path32.basename(target, givenExt);
+  const suffix = safeSlug(state.outputLanguage ?? state.id);
+  return withMediaExt(path32.join(path32.dirname(target), `${base}-${suffix}${givenExt}`), ext);
+}
+function claimPath(dest, state, used) {
+  const ext = path32.extname(dest);
+  const stem = dest.slice(0, dest.length - ext.length);
+  let candidate = dest;
+  for (let n = 1; used.has(candidate.toLowerCase()); n++) {
+    const id = safeSlug(state.id);
+    candidate = n === 1 ? `${stem}-${id}${ext}` : `${stem}-${id}-${n}${ext}`;
+  }
+  used.add(candidate.toLowerCase());
+  return candidate;
+}
+function captionPathFor(dest, capExt) {
+  const stem = path32.join(path32.dirname(dest), path32.basename(dest, path32.extname(dest)));
+  const capDest = `${stem}.${capExt}`;
+  return capDest.toLowerCase() === dest.toLowerCase() ? `${stem}.captions.${capExt}` : capDest;
+}
+var downloadThumbHttpsOnly = (url, dest) => downloadHttpsOnly(url, dest, 12e4);
 function summarizeState(state) {
   const out = {
     kind: state.kind,
@@ -7078,7 +7348,7 @@ function summarizeState(state) {
   if (state.failureMessage) out.failure_message = state.failureMessage;
   return out;
 }
-async function deliverOne(state, opts, count, logger, files) {
+async function deliverOne(state, opts, count, logger, files, usedPaths) {
   const hint = `Refresh with: ${resumeCommand2(state.kind, state.id, opts)}`;
   if (opts.download === false) {
     if (!state.outputUrl) {
@@ -7091,39 +7361,42 @@ async function deliverOne(state, opts, count, logger, files) {
     };
     return { state, files, urls };
   }
-  const ext = inferExtension(state.outputUrl ?? "", "mp4");
-  const dest = outputPathFor(state, ext, opts.output, count);
+  const ext = inferExtension(state.outputUrl ?? "", state.outputIsAudio ? "mp3" : "mp4");
+  const dest = claimPath(outputPathFor(state, ext, opts.output, count), state, usedPaths);
   await downloadOutput(state.outputUrl, dest, hint);
   logger.success(`Saved ${dest}`);
   files.push(dest);
   if (opts.captions && state.captionUrl) {
     const capExt = inferExtension(state.captionUrl, "srt");
-    const capDest = path32.join(
-      path32.dirname(dest),
-      `${path32.basename(dest, path32.extname(dest))}.${capExt}`
-    );
+    const capDest = claimPath(captionPathFor(dest, capExt), state, usedPaths);
     await downloadOutput(state.captionUrl, capDest, hint);
     logger.success(`Saved ${capDest}`);
     files.push(capDest);
   } else if (opts.captions) {
     logger.warn(`No caption file available for ${state.kind} ${state.id}`);
   }
-  if (state.kind === "video" || state.kind === "agent") {
-    const thumb = await maybeDownloadThumb(state.raw, dest, {
-      skip: opts.thumb === false,
-      logger
-    });
-    if (thumb) files.push(thumb);
+  if ((state.kind === "video" || state.kind === "agent") && opts.thumb !== false) {
+    const thumbUrl = detectThumbUrl(state.raw);
+    if (thumbUrl && !isHttpsUrl(thumbUrl)) {
+      logger.warn(`Skipping thumbnail from a non-https URL (${redactUrl(thumbUrl)})`);
+    } else {
+      const thumb = await maybeDownloadThumb(state.raw, dest, {
+        logger,
+        download: downloadThumbHttpsOnly
+      });
+      if (thumb) files.push(thumb);
+    }
   }
   return { state, files };
 }
 async function deliverOutputs(states, opts, logger) {
   const finished = [];
   const failures = [];
+  const usedPaths = /* @__PURE__ */ new Set();
   for (const state of states) {
     const files = [];
     try {
-      finished.push(await deliverOne(state, opts, states.length, logger, files));
+      finished.push(await deliverOne(state, opts, states.length, logger, files, usedPaths));
     } catch (e) {
       failures.push(`${state.kind} ${state.id}: ${e instanceof Error ? e.message : String(e)}`);
       if (files.length > 0) finished.push({ state, files });
@@ -7176,9 +7449,10 @@ async function completeJobs(client, kind, ids, opts, logger) {
   );
   const settled = await Promise.allSettled(
     ids.map(
-      (id) => waitForJob(client, kind, id, {
+      (id, index) => waitForJob(client, kind, id, {
         timeoutMs,
         intervalMs,
+        startDelayMs: staggerOffsetMs(index, intervalMs),
         maxIntervalMs: Math.max(intervalMs, 3e4),
         burnCaptions: opts.burnCaptions,
         resumeHint: `Resume with: ${resumeCommand2(kind, id, opts)}`,
@@ -10391,6 +10665,19 @@ function mapReplicateError(error, subject) {
   }
   return new ReplicateApiError(message, status, retryAfterMs);
 }
+var ORPHAN_HINT = "The prediction may have been created anyway (Replicate has no idempotency key); check https://replicate.com/predictions before retrying to avoid paying twice";
+function withOrphanHint(error) {
+  if (error instanceof ReplicateApiError) {
+    const { status } = error;
+    const mayExist = status === 0 || status >= 200 && status < 300 || status >= 500;
+    if (!mayExist) return error;
+    return new ReplicateApiError(`${error.message}. ${ORPHAN_HINT}`, status, error.retryAfterMs);
+  }
+  if (error instanceof ProviderError) {
+    return new ProviderError(`${error.message}. ${ORPHAN_HINT}`, error.provider);
+  }
+  return error;
+}
 function validatePrediction(value) {
   if (value === null || typeof value !== "object" || typeof value.id !== "string" || typeof value.status !== "string") {
     throw new ProviderError("Malformed Replicate response: missing prediction id/status", PROVIDER);
@@ -10408,7 +10695,7 @@ function assertSucceeded(prediction2) {
     PROVIDER
   );
 }
-var defaultSleep3 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var defaultSleep4 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var ReplicateClient = class {
   apiKey;
   baseUrl;
@@ -10419,7 +10706,7 @@ var ReplicateClient = class {
     this.apiKey = opts.apiKey;
     this.baseUrl = (opts.baseUrl || DEFAULT_REPLICATE_BASE_URL).replace(/\/+$/, "");
     this.doFetch = opts.fetch ?? ((input, init) => globalThis.fetch(input, init));
-    this.sleep = opts.sleep ?? defaultSleep3;
+    this.sleep = opts.sleep ?? defaultSleep4;
   }
   headers(extra = {}) {
     return { accept: "application/json", authorization: `Bearer ${this.apiKey}`, ...extra };
@@ -10459,7 +10746,7 @@ var ReplicateClient = class {
           await this.sleep(delay);
           continue;
         }
-        throw mapReplicateError(error, subject);
+        throw withOrphanHint(mapReplicateError(error, subject));
       }
     }
   }
@@ -10606,23 +10893,137 @@ init_errors();
 
 // src/providers/replicate/commands/prediction-flow.ts
 init_errors();
+import { InvalidArgumentError, Option as Option2 } from "commander";
 
 // src/providers/replicate/node-outputs.ts
 init_errors();
-init_redact();
-import { once as once2 } from "events";
 import fs44 from "fs";
 import path51 from "path";
-import { Readable } from "stream";
-import { pipeline as pipeline2 } from "stream/promises";
+init_redact();
 
 // src/providers/replicate/output.ts
 init_redact();
+
+// src/core/url-safety.ts
+init_errors();
+function ipv4Octets(host) {
+  const parts = host.split(".");
+  if (parts.length !== 4 || !parts.every((p) => /^\d{1,3}$/.test(p))) return void 0;
+  const octets = parts.map(Number);
+  return octets.every((o) => o <= 255) ? octets : void 0;
+}
+function isNonPublicIpv4([a = 0, b = 0, c2 = 0]) {
+  return a === 0 || // "this network" / unspecified
+  a === 10 || a === 127 || // loopback
+  a === 100 && b >= 64 && b <= 127 || // carrier-grade NAT
+  a === 169 && b === 254 || // link-local (cloud metadata)
+  a === 172 && b >= 16 && b <= 31 || a === 192 && b === 0 && c2 === 0 || // IETF protocol assignments
+  a === 192 && b === 0 && c2 === 2 || // TEST-NET-1
+  a === 192 && b === 168 || a === 198 && (b === 18 || b === 19) || // benchmarking
+  a === 198 && b === 51 && c2 === 100 || // TEST-NET-2
+  a === 203 && b === 0 && c2 === 113 || // TEST-NET-3
+  a >= 224;
+}
+function ipv6Groups(host) {
+  if (!/^[0-9a-f:.]+$/i.test(host) || !host.includes(":")) return void 0;
+  let text = host;
+  const tail = /^(.*:)(\d+\.\d+\.\d+\.\d+)$/.exec(text);
+  if (tail) {
+    const octets = ipv4Octets(tail[2]);
+    if (!octets) return void 0;
+    const [a = 0, b = 0, c2 = 0, d = 0] = octets;
+    text = `${tail[1]}${(a << 8 | b).toString(16)}:${(c2 << 8 | d).toString(16)}`;
+  }
+  const halves = text.split("::");
+  if (halves.length > 2) return void 0;
+  const parse = (s) => s === "" ? [] : s.split(":");
+  const head = parse(halves[0]);
+  const rest = halves.length === 2 ? parse(halves[1]) : [];
+  const missing = 8 - head.length - rest.length;
+  if (halves.length === 2 ? missing < 1 : missing !== 0) return void 0;
+  const all = [...head, ...Array(halves.length === 2 ? missing : 0).fill("0"), ...rest];
+  if (!all.every((g) => /^[0-9a-f]{1,4}$/i.test(g))) return void 0;
+  return all.map((g) => Number.parseInt(g, 16));
+}
+function embeddedIpv4(hi, lo) {
+  return [hi >> 8, hi & 255, lo >> 8, lo & 255];
+}
+function isNonPublicIpv6(groups) {
+  const [g0 = 0, g1 = 0, g2 = 0, g3 = 0, g4 = 0, g5 = 0, g6 = 0, g7 = 0] = groups;
+  const zeroUpTo = (n) => groups.slice(0, n).every((g) => g === 0);
+  if (zeroUpTo(5) && g5 === 65535) return isNonPublicIpv4(embeddedIpv4(g6, g7));
+  if (g0 === 100 && g1 === 65435 && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0) {
+    return isNonPublicIpv4(embeddedIpv4(g6, g7));
+  }
+  if (g0 === 8194) return isNonPublicIpv4(embeddedIpv4(g1, g2));
+  return g0 === 0 || // unspecified (::), loopback (::1), IPv4-compatible and other reserved
+  g0 === 256 && g1 === 0 && g2 === 0 && g3 === 0 || // discard-only 100::/64
+  (g0 & 65024) === 64512 || // unique local fc00::/7
+  (g0 & 65472) === 65152 || // link-local fe80::/10
+  (g0 & 65472) === 65216 || // deprecated site-local fec0::/10
+  (g0 & 65280) === 65280;
+}
+function bareHost(hostname) {
+  const host = hostname.toLowerCase().replace(/\.$/, "");
+  return host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+}
+function isLoopbackHost(hostname) {
+  const host = bareHost(hostname);
+  if (host === "localhost" || host.endsWith(".localhost")) return true;
+  const octets = ipv4Octets(host);
+  if (octets) return octets[0] === 127;
+  const groups = ipv6Groups(host);
+  if (!groups) return false;
+  if (groups.slice(0, 5).every((g) => g === 0) && groups[5] === 65535) {
+    return groups[6] !== void 0 && groups[6] >> 8 === 127;
+  }
+  return groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1;
+}
+function isNonPublicHost(hostname) {
+  const host = bareHost(hostname);
+  if (host === "localhost" || host.endsWith(".localhost")) return true;
+  const octets = ipv4Octets(host);
+  if (octets) return isNonPublicIpv4(octets);
+  const groups = ipv6Groups(host);
+  return groups !== void 0 && isNonPublicIpv6(groups);
+}
+function checkUrlSafety(url, opts) {
+  const action = opts.action ?? "download from";
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new ProviderError(`Refusing to ${action} a malformed URL`, opts.provider);
+  }
+  const host = parsed.hostname.toLowerCase().replace(/\.$/, "");
+  const localOk = opts.allowLocalhostHttp === true && isLoopbackHost(host);
+  const httpOk = parsed.protocol === "https:" || localOk && parsed.protocol === "http:";
+  if (!httpOk) {
+    throw new ProviderError(
+      `Refusing to ${action} ${host || "this URL"}: only https:// URLs are allowed`,
+      opts.provider
+    );
+  }
+  if (!localOk && isNonPublicHost(host)) {
+    throw new ProviderError(
+      `Refusing to ${action} ${host}: it points to a local or private address`,
+      opts.provider
+    );
+  }
+  const trusted = (opts.trustedHosts ?? []).some((t) => host === t || host.endsWith(`.${t}`));
+  return { host, trusted };
+}
+
+// src/providers/replicate/output.ts
 var HTTP_RE = /^https?:\/\//i;
 var DATA_URI_RE = /^data:[^,]*,/i;
 function isMediaRef(value) {
   return typeof value === "string" && (HTTP_RE.test(value) || DATA_URI_RE.test(value));
 }
+var REPLICATE_DELIVERY_HOST = "replicate.delivery";
+function checkOutputUrl(url) {
+  return checkUrlSafety(url, { provider: "replicate", trustedHosts: [REPLICATE_DELIVERY_HOST] });
+}
 function extractOutput(output) {
   const result = { media: [], texts: [] };
   const seen = /* @__PURE__ */ new Set();
@@ -10781,59 +11182,53 @@ function resolveDestination(predictionId, index, count, ext, opts) {
   const base = givenExt ? output.slice(0, -givenExt.length) : output;
   return `${base}-${String(index + 1).padStart(2, "0")}${ext}`;
 }
-async function writeResponse(response, dest) {
-  if (!response.body) throw new HttpError(0, "Response body is null", response.url);
-  const fileStream = fs44.createWriteStream(dest);
-  try {
-    await pipeline2(
-      Readable.fromWeb(response.body),
-      fileStream
-    );
-  } catch (err2) {
-    if (!fileStream.closed) await once2(fileStream, "close");
-    throw err2;
-  }
-}
 async function saveOne(item, predictionId, index, count, opts) {
   if (item.url.startsWith("data:")) {
     const comma = item.url.indexOf(",");
     const meta = item.url.slice(5, comma);
     const payload = item.url.slice(comma + 1);
     const bytes = meta.endsWith(";base64") ? Buffer.from(payload, "base64") : Buffer.from(decodeURIComponent(payload));
-    const dest2 = resolveDestination(
+    const dest = resolveDestination(
       predictionId,
       index,
       count,
       extFromUrl4(item.url) ?? ".bin",
       opts
     );
-    fs44.mkdirSync(path51.dirname(dest2), { recursive: true });
-    fs44.writeFileSync(dest2, bytes);
-    return dest2;
-  }
-  const doFetch = opts.fetch ?? ((url, init) => globalThis.fetch(url, init));
-  let response;
-  try {
-    response = await doFetch(item.url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
-  } catch (cause) {
-    throw new HttpError(0, cause instanceof Error ? cause.message : String(cause), item.url);
-  }
-  if (!response.ok) {
-    const hint = response.status === 404 || response.status === 410 ? " (output may have expired)" : "";
-    throw new HttpError(response.status, `download failed${hint}`, item.url);
+    fs44.mkdirSync(path51.dirname(dest), { recursive: true });
+    fs44.writeFileSync(dest, bytes);
+    return dest;
   }
-  const ext = extFromUrl4(item.url) ?? extFromContentType(response.headers.get("content-type")) ?? ".bin";
-  const dest = resolveDestination(predictionId, index, count, ext, opts);
-  fs44.mkdirSync(path51.dirname(dest), { recursive: true });
+  const warned = opts.warnedHosts;
   try {
-    await writeResponse(response, dest);
+    const { dest } = await downloadToFile(item.url, {
+      dest: (response) => {
+        const ext = extFromUrl4(item.url) ?? extFromContentType(response.headers.get("content-type")) ?? ".bin";
+        return resolveDestination(predictionId, index, count, ext, opts);
+      },
+      timeoutMs: DOWNLOAD_TIMEOUT_MS,
+      maxBytes: opts.maxBytes,
+      fetch: opts.fetch,
+      validateUrl: (url) => {
+        const { host, trusted } = checkOutputUrl(url);
+        if (!trusted && !warned.has(host)) {
+          warned.add(host);
+          opts.logger.warn(
+            `Output ${item.path} is served from ${host}, not ${REPLICATE_DELIVERY_HOST}`
+          );
+        }
+      }
+    });
+    return dest;
   } catch (err2) {
-    fs44.rmSync(dest, { force: true });
+    if (err2 instanceof HttpError && (err2.status === 404 || err2.status === 410)) {
+      throw new HttpError(err2.status, "download failed (output may have expired)", err2.rawUrl);
+    }
     throw err2;
   }
-  return dest;
 }
 async function saveMediaOutputs(predictionId, media, opts) {
+  const withCap = { ...opts, maxBytes: maxDownloadBytes(), warnedHosts: /* @__PURE__ */ new Set() };
   const saved = [];
   const failed = [];
   for (let i = 0; i < media.length; i++) {
@@ -10841,7 +11236,7 @@ async function saveMediaOutputs(predictionId, media, opts) {
     if (!item) continue;
     opts.logger.debug(`Downloading ${item.path} from ${redactUrl(item.url).slice(0, 200)}`);
     try {
-      const dest = await saveOne(item, predictionId, i, media.length, opts);
+      const dest = await saveOne(item, predictionId, i, media.length, withCap);
       saved.push(dest);
       opts.logger.success(`Saved ${dest}`);
     } catch (e) {
@@ -10858,10 +11253,22 @@ async function saveMediaOutputs(predictionId, media, opts) {
 }
 
 // src/providers/replicate/commands/prediction-flow.ts
+var DEFAULT_PREFER_WAIT_SECONDS = 60;
+function parsePreferWaitSeconds(raw) {
+  const n = Number(raw);
+  if (!/^\d+$/.test(raw.trim()) || n < 1 || n > 60) {
+    throw new InvalidArgumentError(
+      `Expected an integer number of seconds from 1 to 60 (a bare --prefer-wait means ${DEFAULT_PREFER_WAIT_SECONDS}); put the prompt before the flag.`
+    );
+  }
+  return n;
+}
 function addFlowOptions(cmd, defaultTimeoutMs) {
-  return cmd.option("--async", "Submit and return immediately with the prediction id").option("--wait", "Wait for a terminal status (default unless --async)").option(
-    "--prefer-wait [seconds]",
-    "Ask Replicate to hold the create request open (1-60s, default 60); keeps polling if still running"
+  return cmd.option("--async", "Submit and return immediately with the prediction id").option("--wait", "Wait for a terminal status (default unless --async)").addOption(
+    new Option2(
+      "--prefer-wait [seconds]",
+      "Ask Replicate to hold the create request open for 1-60s (bare flag: 60); keeps polling if still running"
+    ).argParser(parsePreferWaitSeconds).preset(String(DEFAULT_PREFER_WAIT_SECONDS))
   ).option("--wait-timeout <ms>", "Polling timeout in milliseconds", String(defaultTimeoutMs)).option("--download", "Download media outputs (default)").option("--no-download", "Print output URLs instead of downloading").option("--output <path>", "Output file path, or a directory for multiple outputs").option("-v, --verbose", "Verbose logging");
 }
 function parsePositiveInt2(raw, flag, max) {
@@ -10873,11 +11280,6 @@ function parsePositiveInt2(raw, flag, max) {
   }
   return n;
 }
-function parsePreferWait(value) {
-  if (value === void 0 || value === false) return void 0;
-  if (value === true) return 60;
-  return parsePositiveInt2(value, "--prefer-wait", 60);
-}
 function resumeCommand3(id) {
   return `multix replicate status ${id} --wait --download`;
 }
@@ -10932,13 +11334,16 @@ async function executePrediction2(params) {
   const { client, model, input, opts, logger } = params;
   if (opts.async && opts.wait)
     throw new ValidationError("--async and --wait are mutually exclusive");
-  if (opts.async && opts.preferWait) {
+  if (opts.async && opts.preferWait !== void 0) {
     throw new ValidationError("--async and --prefer-wait are mutually exclusive");
   }
   const waitTimeoutMs = parsePositiveInt2(opts.waitTimeout, "--wait-timeout");
-  const preferWaitSeconds = parsePreferWait(opts.preferWait);
   logger.info(`Submitting to Replicate ${describeModelRef(model)}...`);
-  const prediction2 = await client.createPrediction({ model, input, preferWaitSeconds });
+  const prediction2 = await client.createPrediction({
+    model,
+    input,
+    preferWaitSeconds: opts.preferWait
+  });
   if (opts.async) {
     printAsyncHandle(prediction2);
     return;
@@ -11010,7 +11415,7 @@ import fs45 from "fs";
 import path52 from "path";
 var DATA_URI_MAX_BYTES = 256 * 1024;
 var UPLOAD_MAX_BYTES = 100 * 1024 * 1024;
-function formatMb2(bytes) {
+function formatMb3(bytes) {
   return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
 }
 async function resolveFileInput(value, client, logger) {
@@ -11026,7 +11431,7 @@ async function resolveFileInput(value, client, logger) {
   if (stat.size === 0) throw new ValidationError(`Input file is empty: ${value}`);
   if (stat.size >= UPLOAD_MAX_BYTES) {
     throw new ValidationError(
-      `Input file ${value} is ${formatMb2(stat.size)}; Replicate accepts uploads under 100MB. Host it and pass an https URL instead.`
+      `Input file ${value} is ${formatMb3(stat.size)}; Replicate accepts uploads under 100MB. Host it and pass an https URL instead.`
     );
   }
   const filename = path52.basename(filePath);
@@ -11036,7 +11441,7 @@ async function resolveFileInput(value, client, logger) {
     logger.debug(`Inlining ${filename} (${stat.size} bytes) as a data URI`);
     return `data:${contentType};base64,${bytes.toString("base64")}`;
   }
-  logger.info(`Uploading ${filename} (${formatMb2(stat.size)}) to Replicate Files...`);
+  logger.info(`Uploading ${filename} (${formatMb3(stat.size)}) to Replicate Files...`);
   const file = await client.uploadFile({
     data: new Blob([bytes], { type: contentType }),
     filename,
@@ -11460,7 +11865,6 @@ function registerCheckCommand(program2) {
 }
 
 // src/commands/doc/convert.ts
-init_errors();
 import fs47 from "fs";
 import path53 from "path";
 
@@ -11478,27 +11882,45 @@ Requirements:
 Output only the markdown content without any preamble or explanation.`;
 
 // src/commands/doc/convert.ts
+function autoNameBase(input) {
+  if (input === STDIN_ARG) return "stdin";
+  return path53.basename(input, path53.extname(input));
+}
 async function convertDocuments(opts) {
-  const { inputs, output, autoName = false, verbose, logger } = opts;
+  const { output, autoName = false, verbose, logger } = opts;
   const model = opts.model ?? DOC_MODEL_DEFAULT;
   const prompt = opts.prompt ?? DEFAULT_CONVERT_PROMPT;
-  for (const f of inputs) {
-    if (!fs47.existsSync(f)) throw new ValidationError(`Input file not found: ${f}`);
-  }
-  let outputPath;
-  if (output) {
-    outputPath = path53.resolve(output);
-  } else if (autoName && inputs.length === 1 && inputs[0]) {
-    const base = path53.basename(inputs[0], path53.extname(inputs[0]));
-    outputPath = path53.join(getOutputDir(), `${base}-extraction.md`);
-  } else {
-    outputPath = path53.join(getOutputDir(), "document-extraction.md");
+  const { inputs, cleanup } = await resolveFileInputs(opts.inputs, {
+    stdinExt: opts.stdinExt,
+    input: opts.stdin,
+    flag: "--input",
+    example: "cat report.pdf | multix doc convert --input -",
+    extExample: "pdf"
+  });
+  let failed;
+  try {
+    let outputPath;
+    if (output) {
+      outputPath = path53.resolve(output);
+    } else if (autoName && opts.inputs.length === 1 && opts.inputs[0]) {
+      outputPath = path53.join(getOutputDir(), `${autoNameBase(opts.inputs[0])}-extraction.md`);
+    } else {
+      outputPath = path53.join(getOutputDir(), "document-extraction.md");
+    }
+    fs47.mkdirSync(path53.dirname(outputPath), { recursive: true });
+    failed = await convertResolved(inputs, { outputPath, model, prompt, verbose, logger });
+  } finally {
+    cleanup();
   }
-  fs47.mkdirSync(path53.dirname(outputPath), { recursive: true });
+  if (failed > 0) process.exit(1);
+}
+async function convertResolved(inputs, ctx) {
+  const { outputPath, model, prompt, verbose, logger } = ctx;
   const results = [];
   for (let i = 0; i < inputs.length; i++) {
-    const filePath = inputs[i];
-    logger?.debug(`[${i + 1}/${inputs.length}] Converting: ${filePath}`);
+    const input = inputs[i];
+    const filePath = input.path;
+    logger?.debug(`[${i + 1}/${inputs.length}] Converting: ${input.label}`);
     let markdown;
     let errorMsg;
     for (let attempt = 0; attempt < 3; attempt++) {
@@ -11530,7 +11952,7 @@ async function convertDocuments(opts) {
         markdown = extractText(resp);
         break;
       } catch (e) {
-        errorMsg = e instanceof Error ? e.message : String(e);
+        errorMsg = labelError(e instanceof Error ? e.message : String(e), input);
         if (isGeminiRateLimitError(e)) break;
         if (attempt < 2) {
           const wait = 2 ** attempt * 1e3;
@@ -11539,8 +11961,11 @@ async function convertDocuments(opts) {
         }
       }
     }
+    if (markdown === void 0) {
+      logger?.error(`Failed: ${input.label} \u2014 ${errorMsg}`);
+    }
     results.push({
-      file: filePath,
+      file: input.label,
       status: markdown !== void 0 ? "success" : "error",
       markdown,
       error: errorMsg
@@ -11554,7 +11979,7 @@ async function convertDocuments(opts) {
 `);
   for (const r of results) {
     lines.push(`
-## ${path53.basename(r.file)}
+## ${path53.basename(r.file).replace(/[<>]/g, "\\$&")}
 `);
     if (r.status === "success" && r.markdown) {
       lines.push(`${r.markdown}
@@ -11580,8 +12005,7 @@ ${"=".repeat(50)}`);
       console.log(`  [${r.status}] ${r.file}`);
     }
   }
-  const failed = results.filter((r) => r.status === "error").length;
-  if (failed > 0) process.exit(1);
+  return results.length - succeeded;
 }
 function sleep4(ms) {
   return new Promise((r) => setTimeout(r, ms));
@@ -11594,14 +12018,21 @@ function registerDocCommands(program2) {
   );
   doc.command("convert").description("Convert documents to Markdown using Gemini Files API").requiredOption(
     "--input <files...>",
-    "Input file(s) to convert",
+    "Input file(s) to convert (use - to read piped stdin)",
     (val, prev) => [...prev, val],
     []
-  ).alias("-i").option("--output <path>", "Output markdown file path").option("--auto-name", "Derive output filename from input basename (single file only)").option("--model <id>", `Gemini model to use (default: ${DOC_MODEL_DEFAULT})`).option("--prompt <text>", "Custom conversion prompt").option("-v, --verbose", "Verbose logging").action(
+  ).alias("-i").option(
+    "--stdin-ext <ext>",
+    "Extension for piped stdin when auto-detection fails (e.g. pdf, txt)"
+  ).option("--output <path>", "Output markdown file path").option(
+    "--auto-name",
+    "Derive output filename from input basename (single file only; stdin becomes stdin-extraction.md)"
+  ).option("--model <id>", `Gemini model to use (default: ${DOC_MODEL_DEFAULT})`).option("--prompt <text>", "Custom conversion prompt").option("-v, --verbose", "Verbose logging").action(
     async (opts) => {
       const logger = createLogger({ verbose: opts.verbose ?? false });
       await convertDocuments({
         inputs: opts.input,
+        stdinExt: opts.stdinExt,
         output: opts.output,
         autoName: opts.autoName,
         model: opts.model,
@@ -11623,13 +12054,13 @@ import fs48 from "fs";
 import path54 from "path";
 
 // src/commands/media/detect-type.ts
-var VIDEO_EXTS = /* @__PURE__ */ new Set([".mp4", ".mov", ".avi", ".mkv", ".webm", ".flv", ".mpg", ".mpeg"]);
-var AUDIO_EXTS = /* @__PURE__ */ new Set([".mp3", ".wav", ".m4a", ".flac", ".aac", ".ogg", ".aiff"]);
+var VIDEO_EXTS2 = /* @__PURE__ */ new Set([".mp4", ".mov", ".avi", ".mkv", ".webm", ".flv", ".mpg", ".mpeg"]);
+var AUDIO_EXTS2 = /* @__PURE__ */ new Set([".mp3", ".wav", ".m4a", ".flac", ".aac", ".ogg", ".aiff"]);
 var IMAGE_EXTS2 = /* @__PURE__ */ new Set([".jpg", ".jpeg", ".png", ".webp", ".heic", ".heif", ".gif", ".bmp"]);
 function extToKind(ext) {
   const lower = ext.toLowerCase();
-  if (VIDEO_EXTS.has(lower)) return "video";
-  if (AUDIO_EXTS.has(lower)) return "audio";
+  if (VIDEO_EXTS2.has(lower)) return "video";
+  if (AUDIO_EXTS2.has(lower)) return "audio";
   if (IMAGE_EXTS2.has(lower)) return "image";
   return void 0;
 }
@@ -11805,7 +12236,7 @@ async function optimizeVideo(opts) {
 }
 
 // src/commands/media/batch.ts
-var ALL_EXTS = /* @__PURE__ */ new Set([...VIDEO_EXTS, ...AUDIO_EXTS, ...IMAGE_EXTS2]);
+var ALL_EXTS = /* @__PURE__ */ new Set([...VIDEO_EXTS2, ...AUDIO_EXTS2, ...IMAGE_EXTS2]);
 async function batchOptimize(opts) {
   const {
     inputDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrgoonie/multix",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "AI multimodal CLI — OpenAI, Gemini, MiniMax, OpenRouter, Leonardo, BytePlus, ElevenLabs, fal.ai, Atlas Cloud, Replicate, HeyGen, 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, Replicate 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, Replicate direct API models incl. P-Video, HeyGen Video Agent and scripted avatar videos), video translation and lipsync (HeyGen), 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, Atlas Cloud, Replicate, replicate.com models, Replicate predictions, HeyGen, avatar video, talking head, Video Agent, video translation, dubbing, lipsync, video generation, text-to-video, image-to-video, i2v, ElevenLabs voice cloning, updating/upgrading multix, or asks for batch media optimization.
-version: 0.13.0 # x-release-please-version
+version: 0.14.1 # x-release-please-version
 ---
 
 # multix — AI Multimodal CLI
@@ -178,7 +178,9 @@ multix replicate status <prediction-id> --wait --download
 multix replicate cancel <prediction-id>
 ```
 
-Shared flags: `--async`, `--wait`, `--prefer-wait [seconds]` (sends `Prefer: wait=N`, still polls if unfinished), `--wait-timeout <ms>`, `--no-download` (print URLs), `--output <path|dir/>`. `failed`/`canceled`/`aborted` predictions exit non-zero. Local files up to 256 KB are inlined as data URIs; larger files (< 100 MB) go through the Replicate Files API.
+Shared flags: `--async`, `--wait`, `--prefer-wait [seconds]` (integer 1-60, bare flag = 60; sends `Prefer: wait=N`, still polls if unfinished; put the prompt before a bare flag), `--wait-timeout <ms>`, `--no-download` (print URLs), `--output <path|dir/>`. `failed`/`canceled`/`aborted` predictions exit non-zero. Local files up to 256 KB are inlined as data URIs; larger files (< 100 MB) go through the Replicate Files API.
+
+Output downloads are `https://` only; `localhost` and loopback/private/link-local/special-purpose IP literals (including redirects; hostnames are not resolved) are refused, non-`replicate.delivery` hosts are downloaded with a warning, and each file is capped at `MULTIX_MAX_DOWNLOAD_MB` (default 2048). If submitting fails with a network error, timeout, 5xx, or an unreadable 2xx response, the prediction may still exist and bill: check https://replicate.com/predictions before retrying instead of resubmitting blindly.
 
 ## HeyGen
 
@@ -194,7 +196,7 @@ multix heygen video-agent "45-second explainer for a note app" [--avatar <look-i
 multix heygen avatars [--type photo_avatar] [--cursor <token>]
 multix heygen voices [--language English]
 multix heygen video "Hello!" --avatar <look-id> [--voice <id>] [--aspect-ratio 9:16] [--engine avatar_iv|avatar_v|avatar_iii] [--burn-captions]
-multix heygen translate <ref> --languages "Spanish, Chinese (Cantonese, Traditional)" [--output <dir>]
+multix heygen translate <ref> --languages "Spanish, Chinese (Cantonese, Traditional)" [--output <dir|dub.mp4>]   # several languages: dub.mp4 -> dub-Spanish.mp4, ...
 multix heygen lipsync --video <ref> --audio <ref>
 multix heygen tts "Hello" --voice <voice-id>
 multix heygen template <template-id> --input @vars.json
@@ -354,6 +356,7 @@ multix byteplus 3d --input-image ./front.png ./side.png --prompt "Generate from
 
 # Docs → Markdown (Gemini)
 multix doc convert --input report.pdf [--auto-name] [--output ./out.md]
+cat report.pdf | multix doc convert --input - --output ./out.md   # "-" reads stdin; --stdin-ext <ext> (e.g. pdf) if undetected
 
 # Media optimization (ffmpeg + ImageMagick)
 multix media optimize --input <file> --output <file> [--target-size <MB>] [--quality 85] [--max-width 1920]
@@ -383,6 +386,7 @@ Requires `cwebp` (libwebp: `brew install webp`, `apt install webp`) on `PATH`.
 | Variable | Purpose |
 |---|---|
 | `MULTIX_OUTPUT_DIR` | Override default output dir |
+| `MULTIX_MAX_DOWNLOAD_MB` | Size limit per downloaded Replicate output file (default 2048) |
 | `OPENAI_IMAGE_MODEL` / `OPENAI_TTS_MODEL` / `OPENAI_STT_MODEL` | OpenAI model defaults |
 | `OPENROUTER_IMAGE_MODEL` | Default OpenRouter image model |
 | `OPENROUTER_FALLBACK_MODELS` | CSV; applies to `generate` AND `i2i` |