ima2-gen 1.1.16 → 1.1.18

package/README.md

@@ -35,6 +35,13 @@ npx @openai/codex login
 npx ima2-gen serve
 ```
 
+To generate a video from the CLI:
+
+```bash
+ima2 video "a cat playing piano" --duration 5 --resolution 720p
+ima2 video "animate this scene" --ref photo.png --duration 10
+```
+
 If `3333` is already occupied, `ima2-gen` binds the next available port and writes the actual URL to `~/.ima2/server.json`. Use `ima2 open` or the URL printed in the terminal instead of assuming the port.
 
 You can also install it globally:
@@ -44,6 +51,17 @@ npm install -g ima2-gen
 ima2 serve
 ```
 
+### Setup
+
+`ima2 setup` offers four authentication choices:
+
+1. **GPT OAuth** — login with ChatGPT account (free, images only)
+2. **Grok OAuth** — login with xAI/Grok account (images + video)
+3. **Both** — GPT OAuth + Grok OAuth (full feature access)
+4. **API Key** — paste your OpenAI API key (paid)
+
+Video generation requires Grok OAuth (option 2 or 3). Run `ima2 grok login` separately if you already have GPT OAuth configured and want to add video support.
+
 Before updating a global install on Windows, stop any running `ima2 serve`
 process. If npm reports `EBUSY` or `resource busy or locked`, close ima2
 terminals, end stale `node.exe` processes if needed, and retry. If the lock
@@ -54,9 +72,10 @@ persists, reboot and run the update before starting ima2 again.
 - **Classic mode**: generate, edit, reuse the current image, paste references, and continue from history.
 - **Node mode**: branch a good image into multiple directions without losing the original.
 - **Multimode batches**: launch several Classic outputs from one prompt, watch slot-by-slot progress, and continue from the best result.
+- **Video generation**: create short videos from text, a single image, or multiple reference images via Grok video models. SSE streaming shows planning → submitted → progress % → done.
 - **Canvas Mode**: zoom, pan, annotate, erase, clean backgrounds, keep transparent previews, and export either alpha or matte-backed versions.
 - **Local gallery**: keep generated assets on your machine with session-aware history. By default the gallery shows the current session and an All Images toggle reveals the full history; the default scope is sticky across sessions. Each image records its generation time and reasoning effort in the result metadata, so they persist across reloads.
-- **Reference images**: drag, drop, paste, and attach up to 5 references; large images are compressed before upload.
+- **Reference images**: drag, drop, paste, and attach up to 5 references (images) or up to 7 references (video); large images are compressed before upload.
 - **Prompt library imports**: import local prompt packs, GitHub folders, and curated GPT-image prompt hints into the built-in prompt library.
 - **Mobile shell**: use the app bar, compose sheet, and compact settings toggle on smaller screens.
 - **Observable jobs**: active and recent jobs are tracked with safe logs and request IDs.
@@ -73,7 +92,7 @@ Image generation can run through the local Codex/ChatGPT OAuth path, a configure
 
 If no provider is specified, the app keeps the current OAuth/default behavior. API-key generation defaults to `gpt-5.4-mini`, `low` reasoning, and `1024x1024` unless the request passes validated model, reasoning, size, or web-search options. Grok defaults to `grok-imagine-image`; `quality: "high"` promotes the final image call to `grok-imagine-image-quality`.
 
-Grok video generation (T2V/I2V) is not shipped in `1.1.15`. The video files in `docs/grok-video-i2v-plan.md` and `docs/grok-video-i2v-research.md` are implementation planning and research notes only; the published runtime remains image-only.
+Grok video generation uses `grok-imagine-video` (default) or `grok-imagine-video-1.5-preview`. Three modes are auto-detected from reference count: text-to-video (0 refs), image-to-video (1 ref), and reference-to-video (2–7 refs, max 10s duration). Video controls include duration (1–15s), resolution (480p, 720p), and aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto).
 
 ![Settings workspace showing OAuth active and API key provider available.](assets/screenshots/settings-oauth-generation.png)
 
@@ -166,6 +185,7 @@ These require a running `ima2 serve`. The CLI covers every server route. The mos
 | `ima2 gen <prompt>` | Generate from the CLI |
 | `ima2 edit <file> --prompt <text>` | Edit an existing image |
 | `ima2 multimode <prompt>` | Multi-image SSE generation |
+| `ima2 video <prompt>` | Video generation via Grok (SSE streaming with progress) |
 | `ima2 ls [--session <id>] [--favorites]` | List recent history |
 | `ima2 show <name> [--metadata]` | Reveal a generated asset |
 | `ima2 prompt ls -q <search>` | Search the prompt library |
@@ -179,6 +199,8 @@ The server advertises its actual port at `~/.ima2/server.json`. If `3333` is bus
 ima2 gen "poster" --model gpt-5.4 --reasoning-effort high
 ima2 edit input.png --prompt "make it rainy" --web-search
 ima2 multimode "two cats playing" -n 2
+ima2 video "a cat playing piano" --duration 5 --resolution 720p
+ima2 video "animate this" --ref photo.png --aspect-ratio 16:9
 ima2 inflight ls --terminal
 ima2 config set imageModels.reasoningEffort high
 ```

package/bin/commands/capabilities.js

@@ -70,6 +70,12 @@ function printText(capabilities) {
     if (capabilities.valid?.imageModels?.grokSupported?.length) {
         out(`  grok models: ${capabilities.valid.imageModels.grokSupported.join(", ")}`);
     }
+    if (capabilities.valid?.videoModels?.supported?.length) {
+        out(`  video models: ${capabilities.valid.videoModels.supported.join(", ")}`);
+        out(`  video resolutions: ${capabilities.valid.videoModels.resolutions?.join(", ")}`);
+        out(`  video aspect ratios: ${capabilities.valid.videoModels.aspectRatios?.join(", ")}`);
+        out(`  video duration: ${capabilities.valid.videoModels.durationRange?.[0]}-${capabilities.valid.videoModels.durationRange?.[1]}s`);
+    }
     out(`  reasoning: ${capabilities.valid?.reasoningEfforts?.join(", ")}`);
     out(`  quality: ${capabilities.valid?.quality?.join(", ")}`);
     out(`  modes: ${capabilities.valid?.modes?.join(", ")}`);

package/bin/commands/capabilities.ts

@@ -74,6 +74,12 @@ function printText(capabilities: any): void {
   if (capabilities.valid?.imageModels?.grokSupported?.length) {
     out(`  grok models: ${capabilities.valid.imageModels.grokSupported.join(", ")}`);
   }
+  if (capabilities.valid?.videoModels?.supported?.length) {
+    out(`  video models: ${capabilities.valid.videoModels.supported.join(", ")}`);
+    out(`  video resolutions: ${capabilities.valid.videoModels.resolutions?.join(", ")}`);
+    out(`  video aspect ratios: ${capabilities.valid.videoModels.aspectRatios?.join(", ")}`);
+    out(`  video duration: ${capabilities.valid.videoModels.durationRange?.[0]}-${capabilities.valid.videoModels.durationRange?.[1]}s`);
+  }
   out(`  reasoning: ${capabilities.valid?.reasoningEfforts?.join(", ")}`);
   out(`  quality: ${capabilities.valid?.quality?.join(", ")}`);
   out(`  modes: ${capabilities.valid?.modes?.join(", ")}`);

package/bin/commands/grok.js

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { dirname, join, delimiter } from "node:path";
 import { fileURLToPath } from "node:url";
 import { color, die, out } from "../lib/output.js";
-import { resolveBin, isWin } from "../lib/platform.js";
+import { isWin } from "../lib/platform.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, "..", "..");
 const HELP = `
@@ -25,6 +25,27 @@ const HELP = `
 function localBinPath() {
     return join(ROOT, "node_modules", ".bin");
 }
+function spawnProgrok(argv, env) {
+    return new Promise((resolve, reject) => {
+        const progrokBin = join(localBinPath(), isWin ? "progrok.cmd" : "progrok");
+        const child = isWin
+            ? spawn(progrokBin, argv, {
+                cwd: ROOT,
+                env,
+                stdio: "inherit",
+                shell: true,
+                windowsHide: true,
+            })
+            : spawn(progrokBin, argv, {
+                cwd: ROOT,
+                env,
+                stdio: "inherit",
+                windowsHide: true,
+            });
+        child.on("error", (err) => reject(err));
+        child.on("close", resolve);
+    });
+}
 export default async function grokCmd(argv) {
     const sub = argv[0];
     if (!sub || sub === "--help" || sub === "-h") {
@@ -35,25 +56,24 @@ export default async function grokCmd(argv) {
         ...process.env,
         PATH: `${localBinPath()}${delimiter}${process.env.PATH || ""}`,
     };
-    const child = isWin
-        ? spawn("cmd.exe", ["/d", "/s", "/c", `progrok ${argv.map((arg) => JSON.stringify(arg)).join(" ")}`], {
-            cwd: ROOT,
-            env,
-            stdio: "inherit",
-            windowsHide: true,
-        })
-        : spawn(resolveBin("progrok"), argv, {
-            cwd: ROOT,
-            env,
-            stdio: "inherit",
-            windowsHide: true,
-        });
-    child.on("error", (err) => {
+    try {
+        const code = await spawnProgrok(argv, env);
+        if (code && code !== 0) {
+            // Auto-fallback: if login (without --device-code) failed, retry with device-code
+            if (sub === "login" && !argv.includes("--device-code")) {
+                out(color.yellow("⚠ ") + "Browser login failed. Retrying with device-code flow...\n");
+                const fallbackCode = await spawnProgrok(["login", "--device-code"], env);
+                if (fallbackCode && fallbackCode !== 0) {
+                    die(fallbackCode, "bundled progrok device-code login also failed");
+                }
+            }
+            else {
+                die(code, `bundled progrok exited with code ${code}`);
+            }
+        }
+    }
+    catch (err) {
         die(1, `bundled progrok failed to start: ${err.message}`);
-    });
-    const code = await new Promise((resolve) => child.on("close", resolve));
-    if (code && code !== 0) {
-        die(code, `bundled progrok exited with code ${code}`);
     }
     if (sub === "login") {
         out(color.green("✓ ") + "Grok OAuth is ready for ima2 serve");

package/bin/commands/grok.ts

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { dirname, join, delimiter } from "node:path";
 import { fileURLToPath } from "node:url";
 import { color, die, out } from "../lib/output.js";
-import { resolveBin, isWin } from "../lib/platform.js";
+import { isWin } from "../lib/platform.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, "..", "..");
@@ -28,6 +28,28 @@ function localBinPath() {
   return join(ROOT, "node_modules", ".bin");
 }
 
+function spawnProgrok(argv: string[], env: NodeJS.ProcessEnv): Promise<number | null> {
+  return new Promise((resolve, reject) => {
+    const progrokBin = join(localBinPath(), isWin ? "progrok.cmd" : "progrok");
+    const child = isWin
+      ? spawn(progrokBin, argv, {
+          cwd: ROOT,
+          env,
+          stdio: "inherit",
+          shell: true,
+          windowsHide: true,
+        })
+      : spawn(progrokBin, argv, {
+          cwd: ROOT,
+          env,
+          stdio: "inherit",
+          windowsHide: true,
+        });
+    child.on("error", (err) => reject(err));
+    child.on("close", resolve);
+  });
+}
+
 export default async function grokCmd(argv: string[]) {
   const sub = argv[0];
   if (!sub || sub === "--help" || sub === "-h") {
@@ -39,28 +61,25 @@ export default async function grokCmd(argv: string[]) {
     ...process.env,
     PATH: `${localBinPath()}${delimiter}${process.env.PATH || ""}`,
   };
-  const child = isWin
-    ? spawn("cmd.exe", ["/d", "/s", "/c", `progrok ${argv.map((arg) => JSON.stringify(arg)).join(" ")}`], {
-        cwd: ROOT,
-        env,
-        stdio: "inherit",
-        windowsHide: true,
-      })
-    : spawn(resolveBin("progrok"), argv, {
-        cwd: ROOT,
-        env,
-        stdio: "inherit",
-        windowsHide: true,
-      });
 
-  child.on("error", (err) => {
+  try {
+    const code = await spawnProgrok(argv, env);
+    if (code && code !== 0) {
+      // Auto-fallback: if login (without --device-code) failed, retry with device-code
+      if (sub === "login" && !argv.includes("--device-code")) {
+        out(color.yellow("⚠ ") + "Browser login failed. Retrying with device-code flow...\n");
+        const fallbackCode = await spawnProgrok(["login", "--device-code"], env);
+        if (fallbackCode && fallbackCode !== 0) {
+          die(fallbackCode, "bundled progrok device-code login also failed");
+        }
+      } else {
+        die(code, `bundled progrok exited with code ${code}`);
+      }
+    }
+  } catch (err: any) {
     die(1, `bundled progrok failed to start: ${err.message}`);
-  });
-
-  const code = await new Promise<number | null>((resolve) => child.on("close", resolve));
-  if (code && code !== 0) {
-    die(code, `bundled progrok exited with code ${code}`);
   }
+
   if (sub === "login") {
     out(color.green("✓ ") + "Grok OAuth is ready for ima2 serve");
   }

package/bin/commands/video.js

@@ -0,0 +1,211 @@
+import { parseArgs } from "../lib/args.js";
+import { resolveServer } from "../lib/client.js";
+import { streamSse } from "../lib/sse.js";
+import { out, die, color, json, exitCodeForError } from "../lib/output.js";
+import { config } from "../../config.js";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+const VALID_RESOLUTIONS = new Set(["480p", "720p"]);
+const VALID_ASPECT_RATIOS = new Set(["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "auto"]);
+const VALID_MODELS = new Set(["grok-imagine-video", "grok-imagine-video-1.5-preview"]);
+const SPEC = {
+    flags: {
+        duration: { type: "string", default: "5" },
+        resolution: { type: "string", default: "480p" },
+        "aspect-ratio": { type: "string", default: "auto" },
+        model: { type: "string" },
+        ref: { type: "string", repeatable: true },
+        out: { short: "o", type: "string" },
+        "out-dir": { short: "d", type: "string" },
+        json: { type: "boolean" },
+        timeout: { type: "string", default: "600" },
+        server: { type: "string" },
+        session: { type: "string" },
+        help: { short: "h", type: "boolean" },
+    },
+};
+const HELP = `
+  ima2 video <prompt...> [options]
+
+  Generate a video via the Grok video provider (SSE streaming).
+
+  Options:
+        --duration <1..15>              Duration in seconds. Default: 5
+        --resolution <480p|720p>        Default: 480p
+        --aspect-ratio <ratio|auto>     1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto. Default: auto
+        --model <name>                  grok-imagine-video, grok-imagine-video-1.5-preview
+        --ref <file>                    Attach source/reference image (repeatable, max 7)
+    -o, --out <file>                    Output file path
+    -d, --out-dir <dir>                 Output directory
+        --json                          Print JSON result to stdout
+        --timeout <sec>                 Default: 600
+        --server <url>                  Override server URL
+        --session <id>                  Session ID
+
+  Modes (auto-detected from --ref count):
+    0 refs  → text-to-video
+    1 ref   → image-to-video
+    2-7 refs → reference-to-video (max 10s duration)
+
+  Examples:
+    ima2 video "a cat playing piano"
+    ima2 video "animate this" --ref photo.png --duration 10
+    ima2 video "cinematic" --resolution 720p --aspect-ratio 16:9 -o out.mp4
+`;
+export default async function videoCmd(argv) {
+    const args = parseArgs(argv, SPEC);
+    if (args.help) {
+        out(HELP);
+        return;
+    }
+    const prompt = args.positional.join(" ");
+    if (!prompt)
+        die(2, "prompt is required");
+    const duration = parseInt(String(args.duration)) || 5;
+    if (duration < 1 || duration > 15)
+        die(2, "--duration must be between 1 and 15");
+    const resolution = String(args.resolution);
+    if (!VALID_RESOLUTIONS.has(resolution))
+        die(2, "--resolution must be one of: 480p, 720p");
+    const aspectRatio = String(args["aspect-ratio"]);
+    if (!VALID_ASPECT_RATIOS.has(aspectRatio))
+        die(2, "--aspect-ratio must be one of: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto");
+    if (args.model && !VALID_MODELS.has(String(args.model))) {
+        die(2, "--model must be one of: grok-imagine-video, grok-imagine-video-1.5-preview");
+    }
+    const refs = (Array.isArray(args.ref) ? args.ref : []);
+    if (refs.length > 7)
+        die(2, "max 7 --ref attachments for video");
+    let server;
+    try {
+        server = await resolveServer({ serverFlag: args.server });
+    }
+    catch (e) {
+        die(exitCodeForError(e), e.message);
+        throw e;
+    }
+    const referenceImages = await Promise.all(refs.map(async (p) => {
+        const buf = await readFile(p);
+        return buf.toString("base64");
+    }));
+    const timeoutMs = (parseInt(String(args.timeout)) || 600) * 1000;
+    const requestId = `req_cli_video_${Date.now().toString(36)}`;
+    const body = {
+        prompt,
+        provider: "grok",
+        duration,
+        resolution,
+        aspectRatio,
+        requestId,
+    };
+    if (args.model)
+        body.model = args.model;
+    if (args.session)
+        body.sessionId = args.session;
+    if (referenceImages.length === 1) {
+        body.sourceImage = referenceImages[0];
+    }
+    else if (referenceImages.length > 1) {
+        body.referenceImages = referenceImages;
+    }
+    const ac = new AbortController();
+    let timedOut = false;
+    const timeoutTimer = setTimeout(() => { timedOut = true; ac.abort(); }, timeoutMs);
+    const onSig = () => { ac.abort(); process.exit(130); };
+    process.once("SIGINT", onSig);
+    process.once("SIGTERM", onSig);
+    const url = `${server.base}/api/video/generate`;
+    let doneData = null;
+    let lastProgress = -1;
+    try {
+        for await (const ev of streamSse(url, { body, signal: ac.signal, headers: { "X-Request-Id": requestId } })) {
+            switch (ev.event) {
+                case "planning":
+                    if (!args.json)
+                        out(color.dim("[planning] preparing video generation..."));
+                    break;
+                case "submitted":
+                    if (!args.json)
+                        out(color.dim(`[submitted] xai request: ${ev.data.xaiVideoRequestId || "..."}`));
+                    break;
+                case "progress": {
+                    const pct = typeof ev.data.progress === "number" ? Math.round(ev.data.progress * 100) : null;
+                    if (pct !== null && pct !== lastProgress && !args.json) {
+                        const bar = renderBar(pct);
+                        process.stdout.write(`\r  ${bar} ${pct}%`);
+                        lastProgress = pct;
+                    }
+                    break;
+                }
+                case "done":
+                    if (!args.json && lastProgress >= 0)
+                        process.stdout.write("\n");
+                    doneData = ev.data;
+                    break;
+                case "error":
+                    if (!args.json && lastProgress >= 0)
+                        process.stdout.write("\n");
+                    die(1, `video error: ${ev.data.error || ev.data}${ev.data.code ? ` (${ev.data.code})` : ""}`);
+            }
+        }
+    }
+    catch (e) {
+        if (e.name === "AbortError" && !timedOut)
+            return;
+        if (!args.json && lastProgress >= 0)
+            process.stdout.write("\n");
+        die(exitCodeForError(e), e.message);
+    }
+    finally {
+        clearTimeout(timeoutTimer);
+        process.off("SIGINT", onSig);
+        process.off("SIGTERM", onSig);
+    }
+    if (!doneData?.filename)
+        die(1, "server did not return a video filename");
+    // Determine output path
+    const filename = String(doneData.filename);
+    const explicitOut = args.out ? String(args.out) : null;
+    const outDir = args["out-dir"] ? String(args["out-dir"]) : null;
+    let target;
+    if (explicitOut) {
+        target = explicitOut;
+    }
+    else if (outDir) {
+        target = join(outDir, filename);
+    }
+    else {
+        target = join(config.storage.generatedDir, filename);
+    }
+    // Download the video file from server
+    const videoUrl = `${server.base}${doneData.url || `/generated/${encodeURIComponent(filename)}`}`;
+    const dlRes = await fetch(videoUrl, { signal: AbortSignal.timeout(30_000) });
+    if (!dlRes.ok)
+        die(1, `failed to download video: HTTP ${dlRes.status}`);
+    const videoBuf = Buffer.from(await dlRes.arrayBuffer());
+    await mkdir(dirname(target), { recursive: true }).catch(() => { });
+    await writeFile(target, videoBuf);
+    if (args.json) {
+        json({
+            ok: true,
+            requestId: doneData.requestId,
+            path: target,
+            filename,
+            elapsed: doneData.elapsed,
+            video: doneData.video,
+            revisedPrompt: doneData.revisedPrompt,
+        });
+    }
+    else {
+        out(color.green("✓ ") + target);
+        if (doneData.elapsed)
+            out(color.dim(`elapsed ${doneData.elapsed}s`));
+        if (doneData.revisedPrompt)
+            out(color.dim(`revised: ${String(doneData.revisedPrompt).slice(0, 80)}`));
+    }
+}
+function renderBar(pct) {
+    const width = 20;
+    const filled = Math.round((pct / 100) * width);
+    return color.green("█".repeat(filled)) + color.dim("░".repeat(width - filled));
+}

package/bin/commands/video.ts

@@ -0,0 +1,202 @@
+import { parseArgs } from "../lib/args.js";
+import { resolveServer } from "../lib/client.js";
+import { streamSse } from "../lib/sse.js";
+import { out, die, color, json, exitCodeForError } from "../lib/output.js";
+import { config } from "../../config.js";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+const VALID_RESOLUTIONS = new Set(["480p", "720p"]);
+const VALID_ASPECT_RATIOS = new Set(["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "auto"]);
+const VALID_MODELS = new Set(["grok-imagine-video", "grok-imagine-video-1.5-preview"]);
+
+const SPEC = {
+  flags: {
+    duration:      { type: "string", default: "5" },
+    resolution:    { type: "string", default: "480p" },
+    "aspect-ratio": { type: "string", default: "auto" },
+    model:         { type: "string" },
+    ref:           { type: "string", repeatable: true },
+    out:           { short: "o", type: "string" },
+    "out-dir":     { short: "d", type: "string" },
+    json:          { type: "boolean" },
+    timeout:       { type: "string", default: "600" },
+    server:        { type: "string" },
+    session:       { type: "string" },
+    help:          { short: "h", type: "boolean" },
+  },
+};
+
+const HELP = `
+  ima2 video <prompt...> [options]
+
+  Generate a video via the Grok video provider (SSE streaming).
+
+  Options:
+        --duration <1..15>              Duration in seconds. Default: 5
+        --resolution <480p|720p>        Default: 480p
+        --aspect-ratio <ratio|auto>     1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto. Default: auto
+        --model <name>                  grok-imagine-video, grok-imagine-video-1.5-preview
+        --ref <file>                    Attach source/reference image (repeatable, max 7)
+    -o, --out <file>                    Output file path
+    -d, --out-dir <dir>                 Output directory
+        --json                          Print JSON result to stdout
+        --timeout <sec>                 Default: 600
+        --server <url>                  Override server URL
+        --session <id>                  Session ID
+
+  Modes (auto-detected from --ref count):
+    0 refs  → text-to-video
+    1 ref   → image-to-video
+    2-7 refs → reference-to-video (max 10s duration)
+
+  Examples:
+    ima2 video "a cat playing piano"
+    ima2 video "animate this" --ref photo.png --duration 10
+    ima2 video "cinematic" --resolution 720p --aspect-ratio 16:9 -o out.mp4
+`;
+
+export default async function videoCmd(argv: string[]) {
+  const args = parseArgs(argv, SPEC);
+  if (args.help) { out(HELP); return; }
+
+  const prompt = args.positional.join(" ");
+  if (!prompt) die(2, "prompt is required");
+
+  const duration = parseInt(String(args.duration)) || 5;
+  if (duration < 1 || duration > 15) die(2, "--duration must be between 1 and 15");
+
+  const resolution = String(args.resolution);
+  if (!VALID_RESOLUTIONS.has(resolution)) die(2, "--resolution must be one of: 480p, 720p");
+
+  const aspectRatio = String(args["aspect-ratio"]);
+  if (!VALID_ASPECT_RATIOS.has(aspectRatio)) die(2, "--aspect-ratio must be one of: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto");
+
+  if (args.model && !VALID_MODELS.has(String(args.model))) {
+    die(2, "--model must be one of: grok-imagine-video, grok-imagine-video-1.5-preview");
+  }
+
+  const refs = (Array.isArray(args.ref) ? args.ref : []) as string[];
+  if (refs.length > 7) die(2, "max 7 --ref attachments for video");
+
+  let server;
+  try { server = await resolveServer({ serverFlag: args.server }); }
+  catch (e: unknown) { die(exitCodeForError(e), (e as Error).message); throw e; }
+
+  const referenceImages = await Promise.all(refs.map(async (p: string) => {
+    const buf = await readFile(p);
+    return buf.toString("base64");
+  }));
+
+  const timeoutMs = (parseInt(String(args.timeout)) || 600) * 1000;
+  const requestId = `req_cli_video_${Date.now().toString(36)}`;
+
+  const body: Record<string, unknown> = {
+    prompt,
+    provider: "grok",
+    duration,
+    resolution,
+    aspectRatio,
+    requestId,
+  };
+  if (args.model) body.model = args.model;
+  if (args.session) body.sessionId = args.session;
+  if (referenceImages.length === 1) {
+    body.sourceImage = referenceImages[0];
+  } else if (referenceImages.length > 1) {
+    body.referenceImages = referenceImages;
+  }
+
+  const ac = new AbortController();
+  let timedOut = false;
+  const timeoutTimer = setTimeout(() => { timedOut = true; ac.abort(); }, timeoutMs);
+  const onSig = () => { ac.abort(); process.exit(130); };
+  process.once("SIGINT", onSig);
+  process.once("SIGTERM", onSig);
+
+  const url = `${server.base}/api/video/generate`;
+  let doneData: Record<string, unknown> | null = null;
+  let lastProgress = -1;
+
+  try {
+    for await (const ev of streamSse(url, { body, signal: ac.signal, headers: { "X-Request-Id": requestId } })) {
+      switch (ev.event) {
+        case "planning":
+          if (!args.json) out(color.dim("[planning] preparing video generation..."));
+          break;
+        case "submitted":
+          if (!args.json) out(color.dim(`[submitted] xai request: ${ev.data.xaiVideoRequestId || "..."}`));
+          break;
+        case "progress": {
+          const pct = typeof ev.data.progress === "number" ? Math.round(ev.data.progress * 100) : null;
+          if (pct !== null && pct !== lastProgress && !args.json) {
+            const bar = renderBar(pct);
+            process.stdout.write(`\r  ${bar} ${pct}%`);
+            lastProgress = pct;
+          }
+          break;
+        }
+        case "done":
+          if (!args.json && lastProgress >= 0) process.stdout.write("\n");
+          doneData = ev.data;
+          break;
+        case "error":
+          if (!args.json && lastProgress >= 0) process.stdout.write("\n");
+          die(1, `video error: ${ev.data.error || ev.data}${ev.data.code ? ` (${ev.data.code})` : ""}`);
+      }
+    }
+  } catch (e: unknown) {
+    if ((e as Error).name === "AbortError" && !timedOut) return;
+    if (!args.json && lastProgress >= 0) process.stdout.write("\n");
+    die(exitCodeForError(e), (e as Error).message);
+  } finally {
+    clearTimeout(timeoutTimer);
+    process.off("SIGINT", onSig);
+    process.off("SIGTERM", onSig);
+  }
+
+  if (!doneData?.filename) die(1, "server did not return a video filename");
+
+  // Determine output path
+  const filename = String(doneData.filename);
+  const explicitOut = args.out ? String(args.out) : null;
+  const outDir = args["out-dir"] ? String(args["out-dir"]) : null;
+  let target: string;
+  if (explicitOut) {
+    target = explicitOut;
+  } else if (outDir) {
+    target = join(outDir, filename);
+  } else {
+    target = join(config.storage.generatedDir, filename);
+  }
+
+  // Download the video file from server
+  const videoUrl = `${server.base}${doneData.url || `/generated/${encodeURIComponent(filename)}`}`;
+  const dlRes = await fetch(videoUrl, { signal: AbortSignal.timeout(30_000) });
+  if (!dlRes.ok) die(1, `failed to download video: HTTP ${dlRes.status}`);
+  const videoBuf = Buffer.from(await dlRes.arrayBuffer());
+  await mkdir(dirname(target), { recursive: true }).catch(() => {});
+  await writeFile(target, videoBuf);
+
+  if (args.json) {
+    json({
+      ok: true,
+      requestId: doneData.requestId,
+      path: target,
+      filename,
+      elapsed: doneData.elapsed,
+      video: doneData.video,
+      revisedPrompt: doneData.revisedPrompt,
+    });
+  } else {
+    out(color.green("✓ ") + target);
+    if (doneData.elapsed) out(color.dim(`elapsed ${doneData.elapsed}s`));
+    if (doneData.revisedPrompt) out(color.dim(`revised: ${String(doneData.revisedPrompt).slice(0, 80)}`));
+  }
+}
+
+function renderBar(pct: number): string {
+  const width = 20;
+  const filled = Math.round((pct / 100) * width);
+  return color.green("█".repeat(filled)) + color.dim("░".repeat(width - filled));
+}