@gobi-ai/cli 0.9.8 → 0.9.10

package/.claude-plugin/marketplace.json

@@ -4,12 +4,12 @@
     "name": "gobi-ai"
   },
   "description": "Claude Code plugin for the Gobi collaborative knowledge platform CLI",
-  "version": "0.9.8",
+  "version": "0.9.10",
   "plugins": [
     {
       "name": "gobi",
       "description": "Manage the Gobi collaborative knowledge platform from the command line. Search and ask brains, publish brain documents, create threads, manage sessions, generate images and videos.",
-      "version": "0.9.8",
+      "version": "0.9.10",
       "author": {
         "name": "gobi-ai"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gobi",
   "description": "Manage the Gobi collaborative knowledge platform from the command line",
-  "version": "0.9.8",
+  "version": "0.9.10",
   "author": {
     "name": "gobi-ai"
   },

package/dist/commands/media.js

@@ -19,6 +19,89 @@ async function pollStatus(path, terminalStates, intervalMs = 3000) {
     }
     throw new Error(`Polling timed out after ${POLL_MAX_DURATION_MS / 1000}s`);
 }
+/**
+ * Download a video binary from the media-gen download endpoint.
+ * Handles three cases:
+ *   1. Direct binary response (redirect: "follow" returns the file)
+ *   2. JSON response with downloadUrl (need to fetch that URL)
+ *   3. Redirect (302) with Location header
+ */
+async function downloadVideoToFile(videoId, outputPath) {
+    const { writeFile, mkdir } = await import("fs/promises");
+    const { dirname } = await import("path");
+    const token = await getValidToken();
+    const dlUrl = `${BASE_URL}/media-gen/videos/${videoId}/download`;
+    // Try following redirects first
+    const res = await fetch(dlUrl, {
+        headers: { Authorization: `Bearer ${token}` },
+        redirect: "follow",
+    });
+    if (!res.ok) {
+        throw new ApiError(res.status, `/media-gen/videos/${videoId}/download`, await res.text());
+    }
+    const ct = res.headers.get("content-type") || "";
+    // If the response is JSON, extract downloadUrl and fetch the actual binary
+    if (ct.includes("application/json")) {
+        const json = (await res.json());
+        const inner = (json.data || json);
+        const url = (inner.downloadUrl || inner.download_url || inner.url);
+        if (!url)
+            throw new Error("Download endpoint returned JSON without a downloadUrl");
+        const videoRes = await fetch(url);
+        if (!videoRes.ok)
+            throw new Error(`Failed to fetch video from ${url}: ${videoRes.status}`);
+        const buffer = Buffer.from(await videoRes.arrayBuffer());
+        await mkdir(dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, buffer);
+        return { contentType: videoRes.headers.get("content-type") || "video/mp4", size: buffer.length };
+    }
+    // Direct binary response
+    const buffer = Buffer.from(await res.arrayBuffer());
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, buffer);
+    return { contentType: ct || "video/mp4", size: buffer.length };
+}
+const MIME_MAP = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".mp4": "video/mp4",
+    ".mov": "video/quicktime",
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+};
+/**
+ * Upload a local file and return its media ID.
+ * Handles init → PUT → finalize in one call.
+ */
+async function uploadFile(filePath) {
+    const { readFile, stat } = await import("fs/promises");
+    const { basename, extname } = await import("path");
+    const buffer = await readFile(filePath);
+    const fileName = basename(filePath);
+    const fileSize = (await stat(filePath)).size;
+    const ext = extname(filePath).toLowerCase();
+    const contentType = MIME_MAP[ext] || "application/octet-stream";
+    const initResp = (await apiPost("/media-gen/media/initialize", {
+        fileName, contentType, fileSize,
+    }));
+    const initData = unwrapResp(initResp);
+    const mediaId = initData.mediaId;
+    const uploadUrl = initData.uploadUrl;
+    if (!mediaId || !uploadUrl)
+        throw new Error("Upload init failed: missing mediaId or uploadUrl");
+    const putRes = await fetch(uploadUrl, {
+        method: "PUT",
+        headers: { "Content-Type": contentType },
+        body: buffer,
+    });
+    if (!putRes.ok)
+        throw new Error(`Upload PUT failed: ${putRes.status}`);
+    await apiPost("/media-gen/media/finalize", { mediaId });
+    return mediaId;
+}
 function extractImageUrl(data) {
     return (data.downloadUrl || data.download_url || data.url);
 }
@@ -30,44 +113,15 @@ export function registerMediaCommand(program) {
     //  Upload
     // ════════════════════════════════════════════════════════════════════
     media
-        .command("upload-init")
-        .description("Get a presigned upload URL for a media file.")
-        .requiredOption("--file-name <fileName>", "Name of the file to upload")
-        .requiredOption("--content-type <contentType>", "MIME type (e.g. image/png, video/mp4)")
-        .option("--file-size <fileSize>", "File size in bytes")
-        .action(async (opts) => {
-        const body = {
-            fileName: opts.fileName,
-            contentType: opts.contentType,
-        };
-        if (opts.fileSize)
-            body.fileSize = parseInt(opts.fileSize, 10);
-        const resp = (await apiPost("/media-gen/media/initialize", body));
-        const data = unwrapResp(resp);
+        .command("upload <file>")
+        .description("Upload a local file and return its media ID.")
+        .action(async (file) => {
+        const mediaId = await uploadFile(file);
         if (isJsonMode(media)) {
-            jsonOut(data);
+            jsonOut({ mediaId });
             return;
         }
-        console.log(`Upload initialized!\n` +
-            `  Media ID:   ${data.mediaId}\n` +
-            `  Upload URL: ${data.uploadUrl}\n\n` +
-            `PUT your file to the upload URL, then run:\n` +
-            `  gobi media upload-finalize --media-id ${data.mediaId}`);
-    });
-    media
-        .command("upload-finalize")
-        .description("Confirm that a media upload is complete.")
-        .requiredOption("--media-id <mediaId>", "Media ID from upload-init")
-        .action(async (opts) => {
-        const resp = (await apiPost("/media-gen/media/finalize", {
-            mediaId: opts.mediaId,
-        }));
-        const data = unwrapResp(resp);
-        if (isJsonMode(media)) {
-            jsonOut(data);
-            return;
-        }
-        console.log(`Upload finalized for media ${opts.mediaId}.`);
+        console.log(`Uploaded → Media ID: ${mediaId}`);
     });
     // ════════════════════════════════════════════════════════════════════
     //  Avatars & Voices
@@ -120,7 +174,7 @@ export function registerMediaCommand(program) {
         .requiredOption("--avatar-id <avatarId>", "Avatar to use")
         .requiredOption("--voice-id <voiceId>", "Voice to use")
         .requiredOption("--script <script>", "Script for the avatar to read")
-        .option("--background-media-id <backgroundMediaId>", "Background media ID (from upload)")
+        .option("--background <file>", "Background image file (auto-uploaded)")
         .option("--wait", "Poll until generation completes")
         .option("-o, --output <path>", "Download video to this path when done (implies --wait)")
         .action(async (opts) => {
@@ -132,60 +186,26 @@ export function registerMediaCommand(program) {
             voiceId: opts.voiceId,
             script: opts.script,
         };
-        if (opts.backgroundMediaId)
-            body.backgroundMediaId = opts.backgroundMediaId;
+        if (opts.background)
+            body.backgroundMediaId = await uploadFile(opts.background);
         const resp = (await apiPost("/media-gen/videos", body));
         let data = unwrapResp(resp);
-        const videoId = data.id || data.videoId;
+        const videoId = data.id || data.videoId || data.jobId;
         if (shouldWait && videoId) {
             console.log(`Video ${videoId} queued — polling for completion…`);
             data = await pollStatus(`/media-gen/videos/${videoId}/status`, ["inference_complete", "inference_failed"]);
         }
+        // After polling, the status response may contain the real videoId for download
+        const downloadId = data.videoId || data.id || videoId;
         // Download video to file if -o specified
-        if (opts.output && videoId && data.status === "inference_complete") {
-            const token = await getValidToken();
-            const dlUrl = `${BASE_URL}/media-gen/videos/${videoId}/download`;
-            const dlRes = await fetch(dlUrl, {
-                headers: { Authorization: `Bearer ${token}` },
-                redirect: "follow",
-            });
-            if (dlRes.ok) {
-                const { writeFile, mkdir } = await import("fs/promises");
-                const { dirname } = await import("path");
-                const buffer = Buffer.from(await dlRes.arrayBuffer());
-                await mkdir(dirname(opts.output), { recursive: true });
-                await writeFile(opts.output, buffer);
-                const contentType = dlRes.headers.get("content-type") || "video/mp4";
-                if (isJsonMode(media)) {
-                    jsonOut({ ...data, filename: opts.output, contentType, size: buffer.length });
-                    return;
-                }
-                console.log(`Video saved to ${opts.output} (${buffer.length} bytes)`);
+        if (opts.output && downloadId && data.status === "inference_complete") {
+            const { contentType, size } = await downloadVideoToFile(downloadId, opts.output);
+            if (isJsonMode(media)) {
+                jsonOut({ ...data, filename: opts.output, contentType, size });
                 return;
             }
-            // If direct download fails, try getting the URL and fetching that
-            const dlRes2 = await fetch(dlUrl, {
-                headers: { Authorization: `Bearer ${token}` },
-                redirect: "manual",
-            });
-            const location = dlRes2.headers.get("location");
-            if (location) {
-                const videoRes = await fetch(location);
-                if (videoRes.ok) {
-                    const { writeFile, mkdir } = await import("fs/promises");
-                    const { dirname } = await import("path");
-                    const buffer = Buffer.from(await videoRes.arrayBuffer());
-                    await mkdir(dirname(opts.output), { recursive: true });
-                    await writeFile(opts.output, buffer);
-                    const contentType = videoRes.headers.get("content-type") || "video/mp4";
-                    if (isJsonMode(media)) {
-                        jsonOut({ ...data, filename: opts.output, contentType, size: buffer.length });
-                        return;
-                    }
-                    console.log(`Video saved to ${opts.output} (${buffer.length} bytes)`);
-                    return;
-                }
-            }
+            console.log(`Video saved to ${opts.output} (${size} bytes)`);
+            return;
         }
         if (isJsonMode(media)) {
             jsonOut(data);
@@ -193,10 +213,10 @@ export function registerMediaCommand(program) {
         }
         const status = data.status || "queued";
         console.log(`Video created!\n` +
-            `  ID:     ${videoId}\n` +
+            `  ID:     ${downloadId}\n` +
             `  Status: ${status}`);
         if (status === "inference_complete") {
-            console.log(`  Download: gobi media video-download ${videoId}`);
+            console.log(`  Download: gobi media video-download ${downloadId}`);
         }
     });
     media
@@ -244,49 +264,14 @@ export function registerMediaCommand(program) {
             const data = await pollStatus(`/media-gen/videos/${id}/status`, ["inference_complete", "inference_failed"]);
             // Download if -o specified and completed
             if (opts.output && data.status === "inference_complete") {
-                const token = await getValidToken();
-                const dlUrl = `${BASE_URL}/media-gen/videos/${id}/download`;
-                const dlRes = await fetch(dlUrl, {
-                    headers: { Authorization: `Bearer ${token}` },
-                    redirect: "follow",
-                });
-                if (dlRes.ok) {
-                    const { writeFile, mkdir } = await import("fs/promises");
-                    const { dirname } = await import("path");
-                    const buffer = Buffer.from(await dlRes.arrayBuffer());
-                    await mkdir(dirname(opts.output), { recursive: true });
-                    await writeFile(opts.output, buffer);
-                    const contentType = dlRes.headers.get("content-type") || "video/mp4";
-                    if (isJsonMode(media)) {
-                        jsonOut({ ...data, filename: opts.output, contentType, size: buffer.length });
-                        return;
-                    }
-                    console.log(`Video ${id} — ${data.status}\nSaved to ${opts.output} (${buffer.length} bytes)`);
+                const dlId = (data.videoId || data.id || id);
+                const { contentType, size } = await downloadVideoToFile(dlId, opts.output);
+                if (isJsonMode(media)) {
+                    jsonOut({ ...data, filename: opts.output, contentType, size });
                     return;
                 }
-                // Try manual redirect
-                const dlRes2 = await fetch(dlUrl, {
-                    headers: { Authorization: `Bearer ${token}` },
-                    redirect: "manual",
-                });
-                const location = dlRes2.headers.get("location");
-                if (location) {
-                    const videoRes = await fetch(location);
-                    if (videoRes.ok) {
-                        const { writeFile, mkdir } = await import("fs/promises");
-                        const { dirname } = await import("path");
-                        const buffer = Buffer.from(await videoRes.arrayBuffer());
-                        await mkdir(dirname(opts.output), { recursive: true });
-                        await writeFile(opts.output, buffer);
-                        const contentType = videoRes.headers.get("content-type") || "video/mp4";
-                        if (isJsonMode(media)) {
-                            jsonOut({ ...data, filename: opts.output, contentType, size: buffer.length });
-                            return;
-                        }
-                        console.log(`Video ${id} — ${data.status}\nSaved to ${opts.output} (${buffer.length} bytes)`);
-                        return;
-                    }
-                }
+                console.log(`Video ${id} — ${data.status}\nSaved to ${opts.output} (${size} bytes)`);
+                return;
             }
             if (isJsonMode(media)) {
                 jsonOut(data);
@@ -312,48 +297,13 @@ export function registerMediaCommand(program) {
         const url = `${BASE_URL}/media-gen/videos/${id}/download`;
         // If -o specified, download directly to file
         if (opts.output) {
-            const res = await fetch(url, {
-                headers: { Authorization: `Bearer ${token}` },
-                redirect: "follow",
-            });
-            if (res.ok) {
-                const { writeFile, mkdir } = await import("fs/promises");
-                const { dirname } = await import("path");
-                const buffer = Buffer.from(await res.arrayBuffer());
-                await mkdir(dirname(opts.output), { recursive: true });
-                await writeFile(opts.output, buffer);
-                const contentType = res.headers.get("content-type") || "video/mp4";
-                if (isJsonMode(media)) {
-                    jsonOut({ filename: opts.output, contentType, size: buffer.length });
-                    return;
-                }
-                console.log(`Video saved to ${opts.output} (${buffer.length} bytes)`);
+            const { contentType, size } = await downloadVideoToFile(id, opts.output);
+            if (isJsonMode(media)) {
+                jsonOut({ filename: opts.output, contentType, size });
                 return;
             }
-            // If direct follow didn't work, try manual redirect
-            const res2 = await fetch(url, {
-                headers: { Authorization: `Bearer ${token}` },
-                redirect: "manual",
-            });
-            const location = res2.headers.get("location");
-            if (location) {
-                const videoRes = await fetch(location);
-                if (videoRes.ok) {
-                    const { writeFile, mkdir } = await import("fs/promises");
-                    const { dirname } = await import("path");
-                    const buffer = Buffer.from(await videoRes.arrayBuffer());
-                    await mkdir(dirname(opts.output), { recursive: true });
-                    await writeFile(opts.output, buffer);
-                    const contentType = videoRes.headers.get("content-type") || "video/mp4";
-                    if (isJsonMode(media)) {
-                        jsonOut({ filename: opts.output, contentType, size: buffer.length });
-                        return;
-                    }
-                    console.log(`Video saved to ${opts.output} (${buffer.length} bytes)`);
-                    return;
-                }
-            }
-            throw new ApiError(res.status, `/media-gen/videos/${id}/download`, "Failed to download video");
+            console.log(`Video saved to ${opts.output} (${size} bytes)`);
+            return;
         }
         // No -o: just return the URL (existing behavior)
         const res = await fetch(url, {
@@ -384,6 +334,223 @@ export function registerMediaCommand(program) {
         console.log(`Download URL for video ${id}:\n  ${data.url || data.downloadUrl || JSON.stringify(data)}`);
     });
     // ════════════════════════════════════════════════════════════════════
+    //  Cinematic Video
+    // ════════════════════════════════════════════════════════════════════
+    media
+        .command("cinematic-create")
+        .description("Create a cinematic video from a text prompt.")
+        .requiredOption("--prompt <prompt>", "Text prompt describing the video")
+        .option("--name <name>", "Name for the video (auto-generated if omitted)")
+        .option("--aspect-ratio <aspectRatio>", "Aspect ratio: 16:9, 9:16, 1:1")
+        .option("--duration <seconds>", "Duration in seconds (4-8)")
+        .option("--resolution <resolution>", "Resolution: 720p, 1080p")
+        .option("--enhance-prompt", "Enhance the prompt with AI")
+        .option("--generate-audio", "Generate audio for the video")
+        .option("--negative-prompt <negativePrompt>", "Negative prompt")
+        .option("--sample-count <count>", "Number of samples (1-4)")
+        .option("--first-frame <file>", "First frame image file (auto-uploaded)")
+        .option("--last-frame <file>", "Last frame image file (auto-uploaded)")
+        .option("--reference-images <files>", "Comma-separated reference image files (auto-uploaded, max 3)")
+        .option("--wait", "Poll until generation completes")
+        .option("-o, --output <path>", "Download video to this path when done (implies --wait)")
+        .action(async (opts) => {
+        const shouldWait = opts.wait || !!opts.output;
+        const autoName = opts.name || `cinematic-${new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19)}`;
+        const body = {
+            name: autoName,
+            prompt: opts.prompt,
+        };
+        if (opts.aspectRatio)
+            body.aspectRatio = opts.aspectRatio;
+        if (opts.duration) {
+            const v = parseInt(opts.duration, 10);
+            if (Number.isNaN(v))
+                throw new Error("--duration must be a number");
+            body.durationSeconds = v;
+        }
+        if (opts.resolution)
+            body.resolution = opts.resolution;
+        if (opts.enhancePrompt)
+            body.enhancePrompt = true;
+        if (opts.generateAudio)
+            body.generateAudio = true;
+        if (opts.negativePrompt)
+            body.negativePrompt = opts.negativePrompt;
+        if (opts.sampleCount) {
+            const v = parseInt(opts.sampleCount, 10);
+            if (Number.isNaN(v))
+                throw new Error("--sample-count must be a number");
+            body.sampleCount = v;
+        }
+        if (opts.firstFrame)
+            body.firstFrameImageMediaId = await uploadFile(opts.firstFrame);
+        if (opts.lastFrame)
+            body.lastFrameImageMediaId = await uploadFile(opts.lastFrame);
+        if (opts.referenceImages) {
+            const files = opts.referenceImages.split(",").map((s) => s.trim());
+            body.referenceImageMediaIds = await Promise.all(files.map((f) => uploadFile(f)));
+        }
+        const resp = (await apiPost("/media-gen/videos/cinematic", body));
+        let data = unwrapResp(resp);
+        const videoId = data.id || data.videoId || data.jobId;
+        if (shouldWait && videoId) {
+            console.log(`Cinematic video ${videoId} queued — polling for completion…`);
+            data = await pollStatus(`/media-gen/videos/${videoId}/status`, ["inference_complete", "inference_failed"]);
+        }
+        // After polling, the status response may contain the real videoId for download
+        const downloadId = data.videoId || data.id || videoId;
+        // Download video to file if -o specified
+        if (opts.output && downloadId && data.status === "inference_complete") {
+            const { contentType, size } = await downloadVideoToFile(downloadId, opts.output);
+            if (isJsonMode(media)) {
+                jsonOut({ ...data, filename: opts.output, contentType, size });
+                return;
+            }
+            console.log(`Cinematic video saved to ${opts.output} (${size} bytes)`);
+            return;
+        }
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        const status = data.status || "queued";
+        console.log(`Cinematic video created!\n` +
+            `  ID:     ${downloadId}\n` +
+            `  Status: ${status}`);
+        if (status === "inference_complete") {
+            console.log(`  Download: gobi media video-download ${downloadId}`);
+        }
+    });
+    // ════════════════════════════════════════════════════════════════════
+    //  Custom Avatars
+    // ════════════════════════════════════════════════════════════════════
+    media
+        .command("avatar-design")
+        .description("Start a design-your-avatar job.")
+        .option("--name <name>", "Name for the avatar (auto-generated if omitted)")
+        .requiredOption("--gender <gender>", "Gender for the avatar design")
+        .requiredOption("--age <age>", "Age range for the avatar")
+        .requiredOption("--ethnicity <ethnicity>", "Ethnicity for the avatar")
+        .requiredOption("--outfit <outfit>", "Outfit description")
+        .requiredOption("--background <background>", "Background description")
+        .option("--no-portrait", "Generate full-body instead of portrait")
+        .option("--audio <file>", "Custom voice audio file (auto-uploaded)")
+        .option("--wait", "Poll until variants are ready")
+        .action(async (opts) => {
+        const body = {
+            name: opts.name || `avatar-${new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19)}`,
+            gender: opts.gender,
+            age: opts.age,
+            ethnicity: opts.ethnicity,
+            outfit: opts.outfit,
+            background: opts.background,
+            isPortrait: opts.portrait,
+        };
+        if (opts.audio)
+            body.audioMediaId = await uploadFile(opts.audio);
+        const resp = (await apiPost("/media-gen/avatars/design", body));
+        let data = unwrapResp(resp);
+        const jobId = data.jobId || data.id;
+        if (opts.wait && jobId) {
+            console.log(`Avatar design job ${jobId} — polling for completion…`);
+            data = await pollStatus(`/media-gen/avatars/jobs/${jobId}/status`, ["variants_ready", "complete", "failed"]);
+        }
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        const status = data.status || "queued";
+        console.log(`Avatar design started!\n` +
+            `  Job ID: ${jobId}\n` +
+            `  Status: ${status}`);
+        if (status === "variants_ready") {
+            console.log(`  Confirm: gobi media avatar-confirm --job-id ${jobId}`);
+        }
+    });
+    media
+        .command("avatar-confirm")
+        .description("Confirm avatar variant(s) after design.")
+        .requiredOption("--job-id <jobId>", "Job ID from avatar-design")
+        .option("--variant <variant>", "Variant to confirm (1 or 2); omit to confirm both")
+        .action(async (opts) => {
+        const body = { jobId: opts.jobId };
+        if (opts.variant) {
+            const v = parseInt(opts.variant, 10);
+            if (Number.isNaN(v))
+                throw new Error("--variant must be a number (1 or 2)");
+            body.variant = v;
+        }
+        const resp = (await apiPost("/media-gen/avatars/confirm", body));
+        const data = unwrapResp(resp);
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        const avatarId = data.avatarId || data.id;
+        console.log(`Avatar confirmed!\n` +
+            `  Avatar ID: ${avatarId || JSON.stringify(data)}`);
+    });
+    media
+        .command("avatar-from-selfie")
+        .description("Create an avatar from a selfie (instant or enhanced with prompt).")
+        .option("--name <name>", "Name for the avatar (auto-generated if omitted)")
+        .requiredOption("--photo <file>", "Selfie photo file (auto-uploaded)")
+        .option("--prompt <prompt>", "Enhancement prompt (triggers async enhance flow)")
+        .option("--audio <file>", "Custom voice audio file (auto-uploaded)")
+        .option("--wait", "Poll until job completes (only for enhance flow)")
+        .action(async (opts) => {
+        const body = {
+            name: opts.name || `avatar-${new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19)}`,
+            photoMediaId: await uploadFile(opts.photo),
+        };
+        if (opts.prompt)
+            body.prompt = opts.prompt;
+        if (opts.audio)
+            body.audioMediaId = await uploadFile(opts.audio);
+        const resp = (await apiPost("/media-gen/avatars/from-selfie", body));
+        let data = unwrapResp(resp);
+        const jobId = data.jobId || data.id;
+        // Enhance flow is async — poll if --wait
+        if (opts.wait && opts.prompt && jobId) {
+            console.log(`Avatar enhance job ${jobId} — polling for completion…`);
+            data = await pollStatus(`/media-gen/avatars/jobs/${jobId}/status`, ["variants_ready", "complete", "failed"]);
+        }
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        if (opts.prompt) {
+            const status = data.status || "queued";
+            console.log(`Avatar enhance started!\n` +
+                `  Job ID: ${jobId}\n` +
+                `  Status: ${status}`);
+        }
+        else {
+            const avatarId = data.avatarId || data.id;
+            console.log(`Avatar created from selfie!\n` +
+                `  Avatar ID: ${avatarId || JSON.stringify(data)}`);
+        }
+    });
+    media
+        .command("avatar-job-status <jobId>")
+        .description("Check avatar job status.")
+        .option("--wait", "Poll until a terminal state is reached")
+        .action(async (jobId, opts) => {
+        let data;
+        if (opts.wait) {
+            data = await pollStatus(`/media-gen/avatars/jobs/${jobId}/status`, ["variants_ready", "complete", "failed"]);
+        }
+        else {
+            const resp = (await apiGet(`/media-gen/avatars/jobs/${jobId}/status`));
+            data = unwrapResp(resp);
+        }
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        console.log(`Avatar job ${jobId} — status: ${data.status || "unknown"}`);
+    });
+    // ════════════════════════════════════════════════════════════════════
     //  Images
     // ════════════════════════════════════════════════════════════════════
     media
@@ -395,7 +562,7 @@ export function registerMediaCommand(program) {
         .option("--aspect-ratio <aspectRatio>", "Aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4)")
         .option("--negative-prompt <negativePrompt>", "Negative prompt")
         .option("--seed <seed>", "Random seed for reproducibility")
-        .option("--reference-media-id <referenceMediaId>", "Reference image media ID")
+        .option("--reference-image <file>", "Reference image file (auto-uploaded)")
         .option("--wait", "Poll until generation completes")
         .option("-o, --output <path>", "Download image to this path when done (implies --wait)")
         .action(async (opts) => {
@@ -413,8 +580,8 @@ export function registerMediaCommand(program) {
             body.negativePrompt = opts.negativePrompt;
         if (opts.seed)
             body.seed = parseInt(opts.seed, 10);
-        if (opts.referenceMediaId)
-            body.referenceMediaId = opts.referenceMediaId;
+        if (opts.referenceImage)
+            body.referenceMediaId = await uploadFile(opts.referenceImage);
         const resp = (await apiPost("/media-gen/images/generate", body));
         let data = unwrapResp(resp);
         const jobId = data.jobId || data.id;
@@ -471,19 +638,23 @@ export function registerMediaCommand(program) {
     media
         .command("image-edit")
         .description("Edit an existing image with a prompt (image-to-image).")
-        .requiredOption("--media-id <mediaId>", "Source image media ID")
+        .requiredOption("--image <file>", "Source image file (auto-uploaded)")
         .requiredOption("--prompt <prompt>", "Edit instruction")
-        .requiredOption("--name <name>", "Name for the edited image")
+        .option("--name <name>", "Name for the edited image (auto-generated if omitted)")
         .option("--wait", "Poll until generation completes")
+        .option("-o, --output <path>", "Download image to this path when done (implies --wait)")
         .action(async (opts) => {
+        const shouldWait = opts.wait || !!opts.output;
+        const mediaId = await uploadFile(opts.image);
+        const autoName = opts.name || opts.prompt.slice(0, 50).replace(/[^a-zA-Z0-9-_ ]/g, "").trim().replace(/\s+/g, "-");
         const resp = (await apiPost("/media-gen/images/edit", {
-            mediaId: opts.mediaId,
+            mediaId,
             prompt: opts.prompt,
-            name: opts.name,
+            name: autoName,
         }));
         let data = unwrapResp(resp);
         const jobId = data.jobId || data.id;
-        if (opts.wait && jobId) {
+        if (shouldWait && jobId) {
             console.log(`Image edit job ${jobId} — polling for completion…`);
             data = await pollStatus(`/media-gen/images/${jobId}`, [
                 "completed",
@@ -492,6 +663,29 @@ export function registerMediaCommand(program) {
                 "inference_failed",
             ]);
         }
+        // Download image to file if -o specified
+        if (opts.output && jobId) {
+            const token = await getValidToken();
+            const query = "";
+            const url = `${BASE_URL}/media-gen/images/${jobId}/download${query}`;
+            const res = await fetch(url, {
+                headers: { Authorization: `Bearer ${token}` },
+            });
+            if (res.ok) {
+                const { writeFile, mkdir } = await import("fs/promises");
+                const { dirname } = await import("path");
+                const buffer = Buffer.from(await res.arrayBuffer());
+                await mkdir(dirname(opts.output), { recursive: true });
+                await writeFile(opts.output, buffer);
+                const contentType = res.headers.get("content-type") || "image/png";
+                if (isJsonMode(media)) {
+                    jsonOut({ ...data, filename: opts.output, contentType, size: buffer.length });
+                    return;
+                }
+                console.log(`Image saved to ${opts.output} (${buffer.length} bytes)`);
+                return;
+            }
+        }
         if (isJsonMode(media)) {
             jsonOut(data);
             return;
@@ -507,21 +701,28 @@ export function registerMediaCommand(program) {
     media
         .command("image-inpaint")
         .description("Inpaint an image region using a mask.")
-        .requiredOption("--media-id <mediaId>", "Source image media ID")
-        .requiredOption("--mask-media-id <maskMediaId>", "Mask image media ID")
+        .requiredOption("--image <file>", "Source image file (auto-uploaded)")
+        .requiredOption("--mask <file>", "Mask image file (auto-uploaded)")
         .requiredOption("--prompt <prompt>", "Inpainting prompt")
-        .requiredOption("--name <name>", "Name for the inpainted image")
+        .option("--name <name>", "Name for the inpainted image (auto-generated if omitted)")
         .option("--wait", "Poll until generation completes")
+        .option("-o, --output <path>", "Download image to this path when done (implies --wait)")
         .action(async (opts) => {
+        const shouldWait = opts.wait || !!opts.output;
+        const [mediaId, maskMediaId] = await Promise.all([
+            uploadFile(opts.image),
+            uploadFile(opts.mask),
+        ]);
+        const autoName = opts.name || opts.prompt.slice(0, 50).replace(/[^a-zA-Z0-9-_ ]/g, "").trim().replace(/\s+/g, "-");
         const resp = (await apiPost("/media-gen/images/inpaint", {
-            mediaId: opts.mediaId,
-            maskMediaId: opts.maskMediaId,
+            mediaId,
+            maskMediaId,
             prompt: opts.prompt,
-            name: opts.name,
+            name: autoName,
         }));
         let data = unwrapResp(resp);
         const jobId = data.jobId || data.id;
-        if (opts.wait && jobId) {
+        if (shouldWait && jobId) {
             console.log(`Inpaint job ${jobId} — polling for completion…`);
             data = await pollStatus(`/media-gen/images/${jobId}`, [
                 "completed",
@@ -530,6 +731,28 @@ export function registerMediaCommand(program) {
                 "inference_failed",
             ]);
         }
+        // Download image to file if -o specified
+        if (opts.output && jobId) {
+            const token = await getValidToken();
+            const url = `${BASE_URL}/media-gen/images/${jobId}/download`;
+            const res = await fetch(url, {
+                headers: { Authorization: `Bearer ${token}` },
+            });
+            if (res.ok) {
+                const { writeFile, mkdir } = await import("fs/promises");
+                const { dirname } = await import("path");
+                const buffer = Buffer.from(await res.arrayBuffer());
+                await mkdir(dirname(opts.output), { recursive: true });
+                await writeFile(opts.output, buffer);
+                const contentType = res.headers.get("content-type") || "image/png";
+                if (isJsonMode(media)) {
+                    jsonOut({ ...data, filename: opts.output, contentType, size: buffer.length });
+                    return;
+                }
+                console.log(`Image saved to ${opts.output} (${buffer.length} bytes)`);
+                return;
+            }
+        }
         if (isJsonMode(media)) {
             jsonOut(data);
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gobi-ai/cli",
-  "version": "0.9.8",
+  "version": "0.9.10",
   "description": "CLI client for the Gobi collaborative knowledge platform",
   "license": "MIT",
   "type": "module",

package/skills/gobi-media/SKILL.md

@@ -3,8 +3,10 @@ name: gobi-media
 description: >-
   Gobi media generation: generate images from text prompts (thumbnails,
   assets, logos), edit and inpaint images, create avatar videos with voice
-  narration, list available avatars and voices, upload media files. Use when
-  the user wants to generate images, create videos, or manage media.
+  narration, create cinematic videos from prompts, design custom avatars or
+  create avatars from selfies, list available avatars and voices, upload
+  media files. Use when the user wants to generate images, create videos,
+  or manage media.
 allowed-tools: Bash(gobi:*)
 metadata:
   author: gobi-ai
@@ -65,18 +67,64 @@ gobi --json media video-create --avatar-id "<AVATAR_ID>" --voice-id "<VOICE_ID>"
 
 The `-o` flag implies `--wait` and downloads the video when done.
 
-**IMPORTANT: Avatars are pre-built system avatars ONLY.** You CANNOT create custom avatars from uploaded images. The `gobi media avatars` list is the complete set of available avatars. Do NOT attempt to upload an image and use its mediaId as an avatarId — it will fail.
+To use a custom image as the **background** of a video, pass it directly as `--background <file>` (auto-uploaded):
 
-To use a custom image (e.g. a generated image) as the **background** of a video, upload it first via `upload-init` / `upload-finalize`, then pass the mediaId as `--background-media-id`:
+```bash
+gobi --json media video-create --avatar-id "<AVATAR_ID>" --voice-id "<VOICE_ID>" --script "<SCRIPT>" --background media/bg.png -o media/<NAME>.mp4
+```
+
+## Typical Workflow (Cinematic Video)
+
+Generate a cinematic video from a text prompt (no avatar needed):
+
+```bash
+gobi --json media cinematic-create --prompt "<PROMPT>" --aspect-ratio "<RATIO>" -o media/<NAME>.mp4
+```
+
+Options: `--duration <4-8>`, `--resolution <720p|1080p>`, `--enhance-prompt`, `--generate-audio`, `--negative-prompt`, `--sample-count <1-4>`, `--first-frame <file>`, `--last-frame <file>`, `--reference-images <files>`.
+
+## Typical Workflow (Image Editing)
+
+Edit an existing image with a prompt — single command:
 
 ```bash
-# 1. Upload custom image as background
-gobi --json media upload-init --file-name "bg.png" --content-type "image/png" --file-size <SIZE>
-curl -T "media/bg.png" -H "Content-Type: image/png" "<UPLOAD_URL>"
-gobi --json media upload-finalize --media-id "<MEDIA_ID>"
+gobi --json media image-edit --image media/source.png --prompt "<EDIT_INSTRUCTION>" -o media/<NAME>.png
+```
+
+All file arguments (`--image`, `--mask`, `--background`, `--photo`, `--audio`, `--reference-image`, `--first-frame`, `--last-frame`) accept local file paths and auto-upload them. No need to manually upload first.
+
+## Custom Avatars
+
+Three ways to create custom avatars:
 
-# 2. Create video with pre-built avatar + custom background
-gobi --json media video-create --avatar-id "<AVATAR_ID>" --voice-id "<VOICE_ID>" --script "<SCRIPT>" --background-media-id "<MEDIA_ID>" -o media/<NAME>.mp4
+### 1. Design from scratch
+
+```bash
+gobi --json media avatar-design --gender "<GENDER>" --age "<AGE>" --ethnicity "<ETHNICITY>" --outfit "<OUTFIT>" --background "<BACKGROUND>" --wait
+```
+
+When `variants_ready`, confirm with:
+
+```bash
+gobi --json media avatar-confirm --job-id "<JOB_ID>"
+```
+
+### 2. From a selfie (instant)
+
+```bash
+gobi --json media avatar-from-selfie --photo media/selfie.png
+```
+
+### 3. From a selfie (enhanced with prompt)
+
+```bash
+gobi --json media avatar-from-selfie --photo media/selfie.png --prompt "<ENHANCEMENT>" --wait
+```
+
+Check any avatar job status with:
+
+```bash
+gobi --json media avatar-job-status <jobId> --wait
 ```
 
 **IMPORTANT: After downloading, show the video using Obsidian wiki-link syntax EXACTLY like this:**
@@ -91,8 +139,7 @@ Do NOT use markdown image/link syntax `![](...)` or `gobi://` URLs. Always use `
 
 ### Upload
 
-- `gobi media upload-init` — Get a presigned upload URL for a media file.
-- `gobi media upload-finalize` — Confirm that a media upload is complete.
+- `gobi media upload <file>` — Upload a local file and return its media ID. Content type is auto-detected.
 
 ### Avatars & Voices
 
@@ -102,17 +149,27 @@ Do NOT use markdown image/link syntax `![](...)` or `gobi://` URLs. Always use `
 ### Videos
 
 - `gobi media video-create` — Create an avatar video generation job.
+- `gobi media cinematic-create` — Create a cinematic video from a text prompt.
 - `gobi media video-list` — List all videos.
 - `gobi media video-get` — Get video metadata.
 - `gobi media video-status` — Poll video generation status.
 - `gobi media video-download` — Download a completed video (`-o` to save to file).
 
+### Custom Avatars
+
+- `gobi media avatar-design` — Start a design-your-avatar job.
+- `gobi media avatar-confirm` — Confirm avatar variant(s) after design.
+- `gobi media avatar-from-selfie` — Create an avatar from a selfie (instant or enhanced).
+- `gobi media avatar-job-status` — Check avatar job status.
+
 ### Images
 
 - `gobi media image-generate` — Generate an image from a text prompt. Types: image (default), thumbnail (YouTube-optimized), asset (logo/product). Aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4
 - `gobi media image-edit` — Edit an existing image with a prompt (image-to-image).
 - `gobi media image-inpaint` — Inpaint an image region using a mask.
 - `gobi media image-status` — Check image generation job status.
+- `gobi media image-download` — Download a generated image.
+- `gobi media image-status` — Check image generation job status.
 
 ## Reference Documentation
 

package/skills/gobi-media/references/media.md

@@ -6,50 +6,39 @@ Usage: gobi media [options] [command]
 Media generation commands (videos, images).
 
 Options:
-  -h, --help                        display help for command
+  -h, --help                           display help for command
 
 Commands:
-  upload-init [options]             Get a presigned upload URL for a media file.
-  upload-finalize [options]         Confirm that a media upload is complete.
-  avatars                           List available avatars.
-  voices                            List available voices.
-  video-create [options]            Create an avatar video generation job.
-  video-list                        List all videos.
-  video-get <id>                    Get video metadata.
-  video-status [options] <id>       Poll video generation status.
-  video-download [options] <id>     Download a completed video (or get its URL).
-  image-generate [options]          Generate an image from a text prompt. Types: image (default), thumbnail (YouTube-optimized), asset (logo/product). Aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4
-  image-edit [options]              Edit an existing image with a prompt (image-to-image).
-  image-inpaint [options]           Inpaint an image region using a mask.
-  image-status [options] <jobId>    Check image generation job status.
-  image-download [options] <jobId>  Download a generated image.
-  help [command]                    display help for command
+  upload <file>                        Upload a local file and return its media ID.
+  avatars                              List available avatars.
+  voices                               List available voices.
+  video-create [options]               Create an avatar video generation job.
+  video-list                           List all videos.
+  video-get <id>                       Get video metadata.
+  video-status [options] <id>          Poll video generation status.
+  video-download [options] <id>        Download a completed video (or get its URL).
+  cinematic-create [options]           Create a cinematic video from a text prompt.
+  avatar-design [options]              Start a design-your-avatar job.
+  avatar-confirm [options]             Confirm avatar variant(s) after design.
+  avatar-from-selfie [options]         Create an avatar from a selfie (instant or enhanced with prompt).
+  avatar-job-status [options] <jobId>  Check avatar job status.
+  image-generate [options]             Generate an image from a text prompt. Types: image (default), thumbnail (YouTube-optimized), asset (logo/product). Aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4
+  image-edit [options]                 Edit an existing image with a prompt (image-to-image).
+  image-inpaint [options]              Inpaint an image region using a mask.
+  image-status [options] <jobId>       Check image generation job status.
+  image-download [options] <jobId>     Download a generated image.
+  help [command]                       display help for command
 ```
 
-## upload-init
+## upload
 
 ```
-Usage: gobi media upload-init [options]
+Usage: gobi media upload [options] <file>
 
-Get a presigned upload URL for a media file.
+Upload a local file and return its media ID.
 
 Options:
-  --file-name <fileName>        Name of the file to upload
-  --content-type <contentType>  MIME type (e.g. image/png, video/mp4)
-  --file-size <fileSize>        File size in bytes
-  -h, --help                    display help for command
-```
-
-## upload-finalize
-
-```
-Usage: gobi media upload-finalize [options]
-
-Confirm that a media upload is complete.
-
-Options:
-  --media-id <mediaId>  Media ID from upload-init
-  -h, --help            display help for command
+  -h, --help  display help for command
 ```
 
 ## avatars
@@ -82,14 +71,14 @@ Usage: gobi media video-create [options]
 Create an avatar video generation job.
 
 Options:
-  --name <name>                              Name for the video (auto-generated if omitted)
-  --avatar-id <avatarId>                     Avatar to use
-  --voice-id <voiceId>                       Voice to use
-  --script <script>                          Script for the avatar to read
-  --background-media-id <backgroundMediaId>  Background media ID (from upload)
-  --wait                                     Poll until generation completes
-  -o, --output <path>                        Download video to this path when done (implies --wait)
-  -h, --help                                 display help for command
+  --name <name>           Name for the video (auto-generated if omitted)
+  --avatar-id <avatarId>  Avatar to use
+  --voice-id <voiceId>    Voice to use
+  --script <script>       Script for the avatar to read
+  --background <file>     Background image file (auto-uploaded)
+  --wait                  Poll until generation completes
+  -o, --output <path>     Download video to this path when done (implies --wait)
+  -h, --help              display help for command
 ```
 
 ## video-list
@@ -139,6 +128,92 @@ Options:
   -h, --help           display help for command
 ```
 
+## cinematic-create
+
+```
+Usage: gobi media cinematic-create [options]
+
+Create a cinematic video from a text prompt.
+
+Options:
+  --prompt <prompt>                   Text prompt describing the video
+  --name <name>                       Name for the video (auto-generated if omitted)
+  --aspect-ratio <aspectRatio>        Aspect ratio: 16:9, 9:16, 1:1
+  --duration <seconds>                Duration in seconds (4-8)
+  --resolution <resolution>           Resolution: 720p, 1080p
+  --enhance-prompt                    Enhance the prompt with AI
+  --generate-audio                    Generate audio for the video
+  --negative-prompt <negativePrompt>  Negative prompt
+  --sample-count <count>              Number of samples (1-4)
+  --first-frame <file>                First frame image file (auto-uploaded)
+  --last-frame <file>                 Last frame image file (auto-uploaded)
+  --reference-images <files>          Comma-separated reference image files (auto-uploaded, max 3)
+  --wait                              Poll until generation completes
+  -o, --output <path>                 Download video to this path when done (implies --wait)
+  -h, --help                          display help for command
+```
+
+## avatar-design
+
+```
+Usage: gobi media avatar-design [options]
+
+Start a design-your-avatar job.
+
+Options:
+  --name <name>              Name for the avatar (auto-generated if omitted)
+  --gender <gender>          Gender for the avatar design
+  --age <age>                Age range for the avatar
+  --ethnicity <ethnicity>    Ethnicity for the avatar
+  --outfit <outfit>          Outfit description
+  --background <background>  Background description
+  --no-portrait              Generate full-body instead of portrait
+  --audio <file>             Custom voice audio file (auto-uploaded)
+  --wait                     Poll until variants are ready
+  -h, --help                 display help for command
+```
+
+## avatar-confirm
+
+```
+Usage: gobi media avatar-confirm [options]
+
+Confirm avatar variant(s) after design.
+
+Options:
+  --job-id <jobId>     Job ID from avatar-design
+  --variant <variant>  Variant to confirm (1 or 2); omit to confirm both
+  -h, --help           display help for command
+```
+
+## avatar-from-selfie
+
+```
+Usage: gobi media avatar-from-selfie [options]
+
+Create an avatar from a selfie (instant or enhanced with prompt).
+
+Options:
+  --name <name>      Name for the avatar (auto-generated if omitted)
+  --photo <file>     Selfie photo file (auto-uploaded)
+  --prompt <prompt>  Enhancement prompt (triggers async enhance flow)
+  --audio <file>     Custom voice audio file (auto-uploaded)
+  --wait             Poll until job completes (only for enhance flow)
+  -h, --help         display help for command
+```
+
+## avatar-job-status
+
+```
+Usage: gobi media avatar-job-status [options] <jobId>
+
+Check avatar job status.
+
+Options:
+  --wait      Poll until a terminal state is reached
+  -h, --help  display help for command
+```
+
 ## image-generate
 
 ```
@@ -147,16 +222,16 @@ Usage: gobi media image-generate [options]
 Generate an image from a text prompt. Types: image (default), thumbnail (YouTube-optimized), asset (logo/product). Aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4
 
 Options:
-  --prompt <prompt>                        Text prompt for image generation
-  --name <name>                            Name for the generated image (auto-generated from prompt if omitted)
-  --type <type>                            Generation type: image (default), thumbnail (YouTube-optimized), asset (logo/product)
-  --aspect-ratio <aspectRatio>             Aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4)
-  --negative-prompt <negativePrompt>       Negative prompt
-  --seed <seed>                            Random seed for reproducibility
-  --reference-media-id <referenceMediaId>  Reference image media ID
-  --wait                                   Poll until generation completes
-  -o, --output <path>                      Download image to this path when done (implies --wait)
-  -h, --help                               display help for command
+  --prompt <prompt>                   Text prompt for image generation
+  --name <name>                       Name for the generated image (auto-generated from prompt if omitted)
+  --type <type>                       Generation type: image (default), thumbnail (YouTube-optimized), asset (logo/product)
+  --aspect-ratio <aspectRatio>        Aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4)
+  --negative-prompt <negativePrompt>  Negative prompt
+  --seed <seed>                       Random seed for reproducibility
+  --reference-image <file>            Reference image file (auto-uploaded)
+  --wait                              Poll until generation completes
+  -o, --output <path>                 Download image to this path when done (implies --wait)
+  -h, --help                          display help for command
 ```
 
 ## image-edit
@@ -167,11 +242,12 @@ Usage: gobi media image-edit [options]
 Edit an existing image with a prompt (image-to-image).
 
 Options:
-  --media-id <mediaId>  Source image media ID
-  --prompt <prompt>     Edit instruction
-  --name <name>         Name for the edited image
-  --wait                Poll until generation completes
-  -h, --help            display help for command
+  --image <file>       Source image file (auto-uploaded)
+  --prompt <prompt>    Edit instruction
+  --name <name>        Name for the edited image (auto-generated if omitted)
+  --wait               Poll until generation completes
+  -o, --output <path>  Download image to this path when done (implies --wait)
+  -h, --help           display help for command
 ```
 
 ## image-inpaint
@@ -182,12 +258,13 @@ Usage: gobi media image-inpaint [options]
 Inpaint an image region using a mask.
 
 Options:
-  --media-id <mediaId>           Source image media ID
-  --mask-media-id <maskMediaId>  Mask image media ID
-  --prompt <prompt>              Inpainting prompt
-  --name <name>                  Name for the inpainted image
-  --wait                         Poll until generation completes
-  -h, --help                     display help for command
+  --image <file>       Source image file (auto-uploaded)
+  --mask <file>        Mask image file (auto-uploaded)
+  --prompt <prompt>    Inpainting prompt
+  --name <name>        Name for the inpainted image (auto-generated if omitted)
+  --wait               Poll until generation completes
+  -o, --output <path>  Download image to this path when done (implies --wait)
+  -h, --help           display help for command
 ```
 
 ## image-status