@mevdragon/vidfarm-devcli 0.18.0 → 0.18.1

package/dist/src/cli.js

@@ -12,6 +12,7 @@ import { computeCompositionGaps, insertMediaLayer, inspectComposition, replaceLa
 import { runCaptionsCommand } from "./devcli/captions.js";
 import { runClipsCommand } from "./devcli/clips.js";
 import { runTransitionsCommand } from "./devcli/transitions.js";
+import { runKeyframesCommand, runMoveCommand, runRestackCommand, runRippleCommand, runTrimCommand } from "./devcli/timeline-edit.js";
 import { MAX_LOCAL_TRANSCRIBE_AUDIO_BYTES, loadSpeechAudioLocally, localGenerateSpeech, localTranscribeSpeech, resolveLocalSpeechAuth } from "./devcli/speech.js";
 import { buildSrtFromSegments, inferSpeechProviderForVoice } from "./services/speech.js";
 import { formatCompositionLintIssues, lintCompositionHtml } from "./services/composition-lint.js";
@@ -236,6 +237,20 @@ Scene transitions (between clips on a pulled/served composition — local file w
   transitions list <dir>    Show transitions on every scene clip [--json]
   transitions clear <dir>   Remove all transitions
                             (run 'vidfarm transitions' for presets & all flags)
+
+Fine timeline control (trackpad-level verbs on a pulled/served composition — local file write):
+  keyframes <dir> --layer <key> --preset <name>|--keyframes '<json>'   Script-free CSS
+                            @keyframes animation on ONE layer (opacity/translate/
+                            scale/rotate); previews AND renders. --easing --duration
+  move <dir> --layer <key> [--layer …]   Shift layers by --delta-start (sec) and/or
+                            --delta-track (lanes); group-aware. (alias: nudge)
+  ripple <dir> --at <sec> --delta <sec>   Insert (+) or close (-) time at --at and
+                            shift every downstream clip so the rest stays in sync
+  trim <dir> --layer <key> --edge start|end --to <sec>   Move one edge to a time
+                            (left trim couples the media in-point on video/audio)
+  restack <dir> --layer <key> --order front|back|forward|backward|--track <n>   Change
+                            stacking (== track index; higher = on top). (alias: zindex)
+                            (run 'vidfarm keyframes|move|ripple|trim|restack help' for all flags)
   versions <forkId>         List immutable version snapshots             → GET  .../compositions/:forkId/versions
   snapshot <forkId>         Save the working state as a new version      → POST .../compositions/:forkId/versions
   render <forkId>           Render the fork to MP4 (--wait to poll)      → POST .../compositions/:forkId/render
@@ -319,10 +334,19 @@ Files (multi-step flows the devcli handles for you):
     --folder <path>         Only files under this folder (e.g. a product/offer)
     --search <query>        Find files by MEANING (keyword + vector over  → POST /api/v1/user/me/attachments/search
                             name/folder/notes) instead of listing everything
+    --content-type <a,b>    With --search: filter the /raws branch by shot-KIND tag
+                            (talking_head,b_roll,product_shot,screen_recording,demo,
+                            reaction,interview,establishing,lifestyle,text_graphic)
   get-file <id> [dest]      Resolve a My Files id to its URL and download it
     --print                 Print text contents (md/txt/csv/json) instead of saving
   annotate-file <id|name>   Set metadata notes on one My Files entry     → PATCH /api/v1/user/me/attachments/:id
     --notes <text>          The notes to attach (empty string clears); embedded for vector search
+  directory ls [path]       Browse the unified file tree (/files·/temp·/raws) → GET /api/v1/user/me/directory
+    --limit <n> --offset <n>  Paginate (folders + files under a path; default "/")
+  directory search <query>  Ranked search across the whole tree           → POST /api/v1/user/me/directory/search
+    --path <scope>          Scope to a subtree · --mode auto|semantic|substring|path · --limit <n>
+    --content-type <a,b>    Filter the /raws branch by shot-KIND tag (talking_head, b_roll, …)
+    (alias: dir)
   put-file / get-file / files / annotate-file are the My Files (persistent) set;
   upload is the throwaway temp store for dropping media into a composition.
   Annotate assets you'll want back — esp. character refs (character_sprite_card.png
@@ -528,6 +552,10 @@ async function main() {
         case "annotate-file":
             await runAnnotateFileCommand(rest);
             return;
+        case "directory":
+        case "dir":
+            await runDirectoryCommand(rest);
+            return;
         case "raws":
         case "clips":
             await runClipsCommand(rest);
@@ -538,6 +566,24 @@ async function main() {
         case "transitions":
             await runTransitionsCommand(rest);
             return;
+        // Fine timeline control — local-file twins of the editor's trackpad verbs.
+        case "keyframes":
+            await runKeyframesCommand(rest);
+            return;
+        case "move":
+        case "nudge":
+            await runMoveCommand(rest);
+            return;
+        case "ripple":
+            await runRippleCommand(rest);
+            return;
+        case "trim":
+            await runTrimCommand(rest);
+            return;
+        case "restack":
+        case "zindex":
+            await runRestackCommand(rest);
+            return;
         // Local media engines + toolchain (bundled HyperFrames local commands —
         // free, no account — plus vidfarm-native lint/stills/doctor/skills).
         case "remove-background":
@@ -654,7 +700,7 @@ function emitResult(result, json, frontend) {
 // Frontend URL builders — these are the pages a director opens in a browser.
 function editorFrontendUrl(host, templateId, forkId) {
     const base = `${host}/editor/${encodeURIComponent(templateId)}`;
-    return forkId ? `${base}?fork=${encodeURIComponent(forkId)}` : base;
+    return forkId ? `${base}/fork/${encodeURIComponent(forkId)}` : base;
 }
 function discoverFrontendUrl(host) {
     return `${host}/discover`;
@@ -779,7 +825,7 @@ async function runServeCommand(argv) {
     }
     const base = `http://localhost:${port}`;
     const editorPath = openTemplateId
-        ? `/editor/${encodeURIComponent(openTemplateId)}${openForkId ? `?fork=${encodeURIComponent(openForkId)}` : ""}`
+        ? `/editor/${encodeURIComponent(openTemplateId)}${openForkId ? `/fork/${encodeURIComponent(openForkId)}` : ""}`
         : "/discover";
     const openUrl = `${base}/auto-login?api_key=${encodeURIComponent(apiKey)}&redirect=${encodeURIComponent(editorPath)}`;
     printServeBanner({ base, dataDir, openUrl, editorPath, cloud: cloudEnabled ? { host, hasKey: Boolean(cloudApiKey) } : null });
@@ -982,9 +1028,9 @@ function printPublishBanner(input) {
     console.log("");
 }
 async function resolveForkId(input) {
-    // /editor/<template_id> issues a 302 → /editor/<template_id>?fork=<id>
+    // /editor/<template_id> issues a 302 → /editor/<template_id>/fork/<id>
     // whenever the caller (or the template's default fork) has one. Follow the
-    // redirect once by hand so we can read the fork id off the query string.
+    // redirect once by hand so we can read the fork id off the path.
     const url = `${input.host}/editor/${encodeURIComponent(input.templateId)}`;
     const res = await fetch(url, {
         method: "GET",
@@ -996,7 +1042,7 @@ async function resolveForkId(input) {
         if (location) {
             try {
                 const target = new URL(location, input.host);
-                const fork = target.searchParams.get("fork");
+                const fork = parseForkFromEditorPath(target.pathname);
                 if (fork)
                     return fork;
             }
@@ -1007,6 +1053,12 @@ async function resolveForkId(input) {
     }
     return null;
 }
+// Parse the fork id out of a canonical editor path
+// /editor/<template_id>/fork/<fork_id> → "<fork_id>" (else null).
+function parseForkFromEditorPath(pathname) {
+    const match = pathname.match(/^\/editor\/[^/]+\/fork\/([^/]+)\/?$/);
+    return match ? decodeURIComponent(match[1]) : null;
+}
 async function fetchCompositionFiles(input) {
     // video-context.json carries the source video's audio transcript and
     // per-scene visual descriptions so desktop agents (Claude Code, Codex)
@@ -2002,6 +2054,13 @@ async function resolveReferenceUrls(ctx, refs) {
 function inferMediaKindFromUrl(url) {
     return /\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(url) ? "video" : "image";
 }
+// Comma-separated shot-KIND filter (talking_head, b_roll, product_shot, …) →
+// the content_type array the /raws branch of the search endpoints honors.
+function parseContentTypeFlag(value) {
+    if (typeof value !== "string" || !value.trim())
+        return [];
+    return value.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+}
 // Resolve a composition.html on disk from a file path or a directory holding one.
 function resolveCompositionHtmlPath(target) {
     const abs = path.resolve(process.cwd(), target);
@@ -3214,18 +3273,20 @@ async function runDownloadCommand(argv) {
 // This is the same filesystem the /editor AI agent browses via the browse_files
 // tool, so an agent CLI (Claude Code / Codex) can find assets the same way.
 async function runFilesCommand(argv) {
-    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), folder: { type: "string" }, search: { type: "string" } } });
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), folder: { type: "string" }, search: { type: "string" }, "content-type": { type: "string" } } });
     const ctx = commonContext(parsed.values);
     const folderFilter = parsed.values.folder ? String(parsed.values.folder).replace(/^\/+|\/+$/g, "") : undefined;
+    const contentTypes = parseContentTypeFlag(parsed.values["content-type"]);
     if (parsed.values.search) {
         // Meaning-first lookup: keyword + vector search over every file's
         // name/folder/notes (BYOK embeddings; keyword-only without a saved key).
+        // content_type filters the /raws branch by shot-KIND tag (server-honored).
         const result = await apiRequest({
             method: "POST",
             host: ctx.host,
             path: "/api/v1/user/me/attachments/search",
             auth: ctx.auth,
-            body: { query: String(parsed.values.search), ...(folderFilter ? { folder_path: folderFilter } : {}) }
+            body: { query: String(parsed.values.search), ...(folderFilter ? { folder_path: folderFilter } : {}), ...(contentTypes.length ? { content_type: contentTypes } : {}) }
         });
         assertApiOk(result, "files --search");
         emitResult(result, ctx.json);
@@ -3241,6 +3302,165 @@ async function runFilesCommand(argv) {
     }
     emitResult(result, ctx.json);
 }
+// ── directory (unified virtual file tree) ────────────────────────────────────
+// Browse + search the three file roots (/files, /temp, /raws) as one tree via
+// the cloud REST directory endpoints. Same cloud auth (--api-key/VIDFARM_API_KEY,
+// --host, --json) as the rest of the wrapper commands.
+const DIRECTORY_HELP = `vidfarm directory — browse the unified file tree (/files · /temp · /raws)
+
+  directory ls [path]              List folders + files under a path (default "/")   → GET /api/v1/user/me/directory
+    --limit <n> --offset <n>       Paginate (server returns next_offset when more)
+    --json                         Raw JSON response
+
+  directory search <query>         Ranked search across the tree                     → POST /api/v1/user/me/directory/search
+    --path <scope>                 Scope the search to a subtree (e.g. /raws/demos)
+    --mode auto|semantic|substring|path   Signal(s) to use (default: auto)
+    --content-type <a,b>           Filter the /raws branch by shot-KIND tag (comma-separated:
+                                   talking_head, b_roll, product_shot, screen_recording, demo,
+                                   reaction, interview, establishing, lifestyle, text_graphic)
+    --limit <n> --json
+
+  Aliases: directory | dir   ·   Auth: --api-key <key> or VIDFARM_API_KEY, --host <url>
+  Move a raw between folders with: vidfarm api PATCH /raws/<clipId> --data '{"folder_path":"…"}'`;
+async function runDirectoryCommand(argv) {
+    const sub = argv[0];
+    const rest = argv.slice(1);
+    switch (sub) {
+        case "ls":
+        case "list":
+            return runDirectoryLs(rest);
+        case "search":
+        case "find":
+            return runDirectorySearch(rest);
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            console.log(DIRECTORY_HELP);
+            return;
+        default:
+            console.error(`Unknown directory subcommand: ${sub}\n`);
+            console.log(DIRECTORY_HELP);
+            process.exitCode = 1;
+    }
+}
+async function runDirectoryLs(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), limit: { type: "string" }, offset: { type: "string" } }
+    });
+    const ctx = commonContext(parsed.values);
+    const dirPath = parsed.positionals[0] ?? "/";
+    const result = await apiRequest({
+        method: "GET",
+        host: ctx.host,
+        path: "/api/v1/user/me/directory",
+        auth: ctx.auth,
+        query: {
+            path: dirPath,
+            limit: parsed.values.limit,
+            offset: parsed.values.offset
+        }
+    });
+    assertApiOk(result, "directory ls");
+    if (ctx.json) {
+        printJson(result.json ?? result.text);
+        return;
+    }
+    printDirectoryListing(result.json, dirPath);
+}
+async function runDirectorySearch(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), path: { type: "string" }, mode: { type: "string" }, "content-type": { type: "string" }, limit: { type: "string" } }
+    });
+    const ctx = commonContext(parsed.values);
+    const query = parsed.positionals.join(" ").trim();
+    if (!query) {
+        throw new Error('directory search requires a query: vidfarm directory search "<query>" [--path /raws] [--mode auto|semantic|substring|path] [--content-type talking_head,b_roll] [--limit N]');
+    }
+    const mode = parsed.values.mode;
+    if (mode && !["auto", "semantic", "substring", "path"].includes(mode)) {
+        throw new Error(`--mode must be auto | semantic | substring | path (got "${mode}")`);
+    }
+    const contentTypes = parseContentTypeFlag(parsed.values["content-type"]);
+    const limit = parsed.values.limit != null ? Number(parsed.values.limit) : undefined;
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: "/api/v1/user/me/directory/search",
+        auth: ctx.auth,
+        body: {
+            query,
+            ...(parsed.values.path ? { path: String(parsed.values.path) } : {}),
+            ...(mode ? { mode } : {}),
+            ...(contentTypes.length ? { content_type: contentTypes } : {}),
+            ...(limit != null && Number.isFinite(limit) ? { limit } : {})
+        }
+    });
+    assertApiOk(result, "directory search");
+    if (ctx.json) {
+        printJson(result.json ?? result.text);
+        return;
+    }
+    printDirectorySearch(result.json, query);
+}
+// Compact "12.3s · 4.2 MB · video/mp4" line for a directory file item.
+function directoryFileMeta(item) {
+    const parts = [];
+    if (typeof item?.durationSec === "number" && item.durationSec > 0)
+        parts.push(`${item.durationSec.toFixed(1)}s`);
+    if (typeof item?.sizeBytes === "number" && item.sizeBytes > 0)
+        parts.push(formatBytes(item.sizeBytes));
+    if (typeof item?.contentType === "string" && item.contentType)
+        parts.push(item.contentType);
+    return parts.join(" · ");
+}
+function printDirectoryListing(data, requestedPath) {
+    const listedPath = data && typeof data.path === "string" ? data.path : requestedPath;
+    const root = data?.root ? ` ${DIM}[${data.root}]${RESET}` : "";
+    console.log(`${BOLD}${listedPath}${RESET}${root}`);
+    const folders = Array.isArray(data?.folders) ? data.folders : [];
+    const files = Array.isArray(data?.files) ? data.files : [];
+    if (folders.length === 0 && files.length === 0) {
+        console.log(`  ${DIM}(empty)${RESET}`);
+    }
+    for (const f of folders) {
+        console.log(`  ${DIM}dir ${RESET}  ${f?.name ?? ""}/    ${DIM}${f?.path ?? ""}${RESET}`);
+    }
+    for (const f of files) {
+        const meta = directoryFileMeta(f);
+        console.log(`  file  ${f?.name ?? ""}${meta ? `    ${DIM}${meta}${RESET}` : ""}    ${DIM}${f?.path ?? ""}${RESET}`);
+        if (f?.viewUrl)
+            console.log(`        ${FRONTEND}${f.viewUrl}${RESET}`);
+    }
+    const total = folders.length + files.length;
+    const more = data?.next_offset != null ? `  (more: --offset ${data.next_offset})` : "";
+    console.log(`\n  ${total} item${total === 1 ? "" : "s"} (${folders.length} folder${folders.length === 1 ? "" : "s"}, ${files.length} file${files.length === 1 ? "" : "s"})${more}`);
+}
+function printDirectorySearch(data, query) {
+    const results = Array.isArray(data?.results) ? data.results : [];
+    const scope = data?.scope ? ` in ${data.scope}` : "";
+    const modeLabel = data?.mode ? ` · mode=${data.mode}` : "";
+    const semantic = data?.semantic === true ? " · semantic" : data?.semantic === false ? " · keyword-only" : "";
+    console.log(`${BOLD}"${query}"${RESET}${scope}${modeLabel}${semantic}  →  ${results.length} result${results.length === 1 ? "" : "s"}\n`);
+    if (results.length === 0) {
+        console.log(`  ${DIM}(no matches)${RESET}`);
+        return;
+    }
+    results.forEach((r, i) => {
+        const score = typeof r?.score === "number" ? ` ${DIM}score=${r.score.toFixed(3)}${RESET}` : "";
+        const kind = r?.kind === "folder" ? "dir " : "file";
+        console.log(`  ${String(i + 1).padStart(2)}. ${kind}  ${r?.path ?? r?.name ?? ""}${score}`);
+        const meta = directoryFileMeta(r);
+        if (meta)
+            console.log(`      ${DIM}${meta}${RESET}`);
+        if (r?.viewUrl)
+            console.log(`      ${FRONTEND}${r.viewUrl}${RESET}`);
+    });
+}
 // Attach metadata notes to one My Files entry (by id, or file name as a
 // fallback). Notes describe what the file IS and when to use it; the server
 // vector-embeds them so `files --search` finds the asset by meaning later —

package/dist/src/devcli/clip-store.js

@@ -130,7 +130,12 @@ export class ClipStore {
             this.attachEmbeddings([clip]);
         return clip;
     }
-    /** All clips (metadata only), newest first, optionally scoped to a source video. */
+    /**
+     * All clips (metadata only), newest first, optionally scoped to a source
+     * video. `contentTypes` filters by the shot-KIND tag (tags.content_type,
+     * exact match, case-insensitive); when present the limit/offset are applied
+     * AFTER the JS filter (the tag lives in tags_json, not a column).
+     */
     listClips(opts = {}) {
         let sql = "SELECT * FROM clips";
         const args = [];
@@ -139,9 +144,30 @@ export class ClipStore {
             args.push(opts.sourceVideoId);
         }
         sql += " ORDER BY created_at DESC";
-        if (opts.limit) {
+        const wanted = (opts.contentTypes ?? []).map((s) => s.trim().toLowerCase()).filter(Boolean);
+        if (wanted.length) {
+            // Content-type filter can't ride SQL (tag is in JSON), so filter every
+            // matching row in JS, then window with offset/limit.
+            let clips = this.db.prepare(sql).all(...args)
+                .map(rowToClip)
+                .filter((c) => (c.tags.content_type ?? []).some((t) => wanted.includes(String(t).toLowerCase())));
+            if (opts.offset)
+                clips = clips.slice(Math.max(0, Math.floor(opts.offset)));
+            if (opts.limit)
+                clips = clips.slice(0, opts.limit);
+            return clips;
+        }
+        if (opts.limit != null) {
             sql += " LIMIT ?";
             args.push(opts.limit);
+            if (opts.offset) {
+                sql += " OFFSET ?";
+                args.push(Math.max(0, Math.floor(opts.offset)));
+            }
+        }
+        else if (opts.offset) {
+            sql += " LIMIT -1 OFFSET ?";
+            args.push(Math.max(0, Math.floor(opts.offset)));
         }
         return this.db.prepare(sql).all(...args).map(rowToClip);
     }
@@ -313,6 +339,7 @@ function rowToClip(row) {
 }
 function emptyTags() {
     return {
+        content_type: [],
         subject: [],
         action: [],
         emotion: [],

package/dist/src/devcli/clips.js

@@ -12,7 +12,7 @@ import { homedir } from "node:os";
 import { parseArgs } from "node:util";
 import { createInterface } from "node:readline/promises";
 import { createIdV7 } from "../lib/ids.js";
-import { buildEffectiveGuidance, ClipModelClient, detectLocalAgent, detectScenes, estimateScanCostFromScenes, fitScenesToDurationBand, formatCostEstimate, hasFfmpeg, LocalAgentClipClient, normalizeAspect, normalizeCropFocus, normalizeWindows, parseClipHuntPrompt, parseTimeRanges, probeVideo, resolveDurationBand, scanVideo, searchClips } from "../services/clip-curation/index.js";
+import { buildEffectiveGuidance, ClipModelClient, DEFAULT_CLIP_ASPECT, DEFAULT_CLIP_DURATION_BAND, detectLocalAgent, detectScenes, effectiveHuntDurationSec, estimateScanCostFromScenes, fitScenesToDurationBand, formatCostEstimate, hasFfmpeg, LocalAgentClipClient, normalizeAspect, normalizeCropFocus, normalizeWindows, parseClipHuntPrompt, parseTimeRanges, probeVideo, resolveDurationBand, resolveTargetClipCount, scanVideo, searchClips } from "../services/clip-curation/index.js";
 import { ClipStore } from "./clip-store.js";
 export const CLIPS_HELP = `vidfarm raws — build & search a local raws library (local ffmpeg + local agent by default)
 
@@ -54,9 +54,14 @@ export const CLIPS_HELP = `vidfarm raws — build & search a local raws library
 
   raws list                        List raws in the library
     --source <id>                  Only raws from one source video
+    --content-type <a,b>           Only raws whose shot-KIND tag matches (comma-separated,
+                                   exact): talking_head, b_roll, product_shot, screen_recording,
+                                   demo, reaction, interview, establishing, lifestyle, text_graphic
+    --offset <n>                   Skip the first N (paginate with --limit)
     --limit <n> | --json
 
   raws search "<natural language>"   Hybrid structured + semantic search
+    --content-type <a,b>           Post-filter hits by shot-KIND tag (see \`raws list\`)
     --limit <n> | --json | --gemini-key <key>
 
   raws match "<text>"              Top library raws to REPLACE a scene (vector search)
@@ -125,6 +130,8 @@ async function runScan(argv) {
             aspect: { type: "string" },
             "crop-focus": { type: "string" },
             "no-text": { type: "boolean" },
+            "allow-text": { type: "boolean" },
+            "max-clips": { type: "string" },
             "no-refine": { type: "boolean" },
             cloud: { type: "boolean" },
             url: { type: "string" },
@@ -153,16 +160,22 @@ async function runScan(argv) {
     const rawWindows = values.range?.length
         ? parseTimeRanges(values.range)
         : parsedPrompt.windows;
-    const durationBand = values.duration
+    // Explicit flags / prompt hints win; otherwise fall back to the same
+    // unspecified-prompt product defaults (5–15s clips, vertical 9:16, avoid text,
+    // ~10 clips / 10 min). Opt out with `--aspect original` / `--allow-text`.
+    const explicitBand = values.duration
         ? resolveDurationBand(Number(values.duration))
         : parsedPrompt.target_duration_sec != null
             ? resolveDurationBand(parsedPrompt.target_duration_sec)
             : null;
-    const aspect = values.aspect
-        ? (normalizeAspect(values.aspect) ?? (() => { throw new Error(`--aspect must be 9:16 | 16:9 | 4:3 | 1:1 (or vertical/horizontal/square), got "${values.aspect}"`); })())
+    const durationBand = explicitBand ?? { ...DEFAULT_CLIP_DURATION_BAND };
+    const explicitAspect = values.aspect
+        ? (normalizeAspect(values.aspect) ?? (() => { throw new Error(`--aspect must be 9:16 | 16:9 | 4:3 | 1:1 | original (or vertical/horizontal/square), got "${values.aspect}"`); })())
         : parsedPrompt.aspect;
+    const aspect = explicitAspect ?? DEFAULT_CLIP_ASPECT;
     const cropFocus = normalizeCropFocus(values["crop-focus"]);
-    const avoidText = Boolean(values["no-text"]) || parsedPrompt.avoid_text;
+    const avoidText = values["allow-text"] ? false : (Boolean(values["no-text"]) || parsedPrompt.avoid_text || true);
+    const maxClips = values["max-clips"] ? Math.max(1, Math.round(Number(values["max-clips"]))) : parsedPrompt.max_clips ?? undefined;
     const guidance = buildEffectiveGuidance({ contentPrompt: guidancePromptRaw, avoidText }) || undefined;
     // ── BACKUP path: run the hunt on the deployed pipeline (--cloud) ──────────
     if (values.cloud) {
@@ -181,7 +194,8 @@ async function runScan(argv) {
             durationBand,
             aspect,
             cropFocus,
-            avoidText
+            avoidText,
+            maxClips
         });
     }
     const videoArg = positionals[0];
@@ -224,6 +238,8 @@ async function runScan(argv) {
     if (rawWindows.length && !windows.length) {
         throw new Error("--range produced no usable window inside the video's duration.");
     }
+    // Density/uniqueness target: ~10 clips / 10 min unless --max-clips / "N clips".
+    const targetClipCount = resolveTargetClipCount(effectiveHuntDurationSec(probe.duration_sec, windows), { max_clips: maxClips });
     if (windows.length) {
         console.log(`[raws] hunting only ${windows.map((w) => `${fmtClock(w.start_sec)}–${fmtClock(w.end_sec)}`).join(", ")} (${fmtDuration(windows.reduce((a, w) => a + w.end_sec - w.start_sec, 0))} of ${fmtDuration(probe.duration_sec)}).`);
     }
@@ -234,6 +250,7 @@ async function runScan(argv) {
         console.log(`[raws] cropping clips to ${aspect} (${cropFocus}).`);
     if (avoidText)
         console.log(`[raws] preferring scenes without on-screen text/captions (selection only — GhostCut is never run on the source).`);
+    console.log(`[raws] aiming for ~${targetClipCount} distinct raw${targetClipCount === 1 ? "" : "s"}${maxClips ? " (--max-clips)" : " (~10 / 10 min)"}.`);
     console.log(`[raws] detecting scenes …`);
     const detected = await detectScenes(videoPath, { durationSec: probe.duration_sec, windows, ...sceneOptions });
     const scenes = fitScenesToDurationBand(detected, durationBand);
@@ -329,6 +346,7 @@ async function runScan(argv) {
         probe,
         windows,
         durationBand,
+        targetClipCount,
         sourceFilename: path.basename(videoPath),
         concurrency,
         onRefine: (r) => {
@@ -442,7 +460,10 @@ async function runScanCloud(input) {
                 ...(input.durationBand ? { duration_band: input.durationBand } : {}),
                 ...(input.aspect ? { aspect: input.aspect } : {}),
                 crop_focus: input.cropFocus,
-                ...(input.avoidText ? { avoid_text: true } : {})
+                // Send explicitly (incl. false) so --allow-text can override the
+                // server-side avoid-text default.
+                avoid_text: input.avoidText,
+                ...(input.maxClips ? { max_clips: input.maxClips } : {})
             }
         })
     });
@@ -510,13 +531,20 @@ async function runList(argv) {
         args: argv,
         options: {
             source: { type: "string" },
+            "content-type": { type: "string" },
+            offset: { type: "string" },
             limit: { type: "string" },
             json: { type: "boolean" },
             home: { type: "string" }
         }
     });
     const store = new ClipStore(values.home);
-    const clips = store.listClips({ sourceVideoId: values.source, limit: clampInt(values.limit, 50, 1, 5000) });
+    const clips = store.listClips({
+        sourceVideoId: values.source,
+        contentTypes: parseContentTypes(values["content-type"]),
+        offset: values.offset ? clampInt(values.offset, 0, 0, 1_000_000) : undefined,
+        limit: clampInt(values.limit, 50, 1, 5000)
+    });
     store.close();
     if (values.json) {
         console.log(JSON.stringify(clips, null, 2));
@@ -538,6 +566,7 @@ async function runSearch(argv) {
         allowPositionals: true,
         options: {
             provider: { type: "string" },
+            "content-type": { type: "string" },
             limit: { type: "string" },
             json: { type: "boolean" },
             "gemini-key": { type: "string" },
@@ -549,6 +578,7 @@ async function runSearch(argv) {
     const query = positionals.join(" ").trim();
     if (!query)
         throw new Error('Usage: vidfarm raws search "<natural language>"');
+    const contentTypes = parseContentTypes(values["content-type"]);
     const limit = clampInt(values.limit, 10, 1, 200);
     const store = new ClipStore(values.home);
     if (store.stats().clips === 0) {
@@ -582,7 +612,13 @@ async function runSearch(argv) {
         console.warn(`[raws] no ${provider} key or local agent CLI — structured/keyword search only.`);
     }
     const t0 = timestamp();
-    const hits = store.search({ criteria, queryEmbedding, limit });
+    // Over-fetch when a content-type filter is on so the post-filter still fills
+    // the requested limit (the tag lives in tags_json, not the search index).
+    const searchLimit = contentTypes.length ? Math.min(1000, limit * 5) : limit;
+    let hits = store.search({ criteria, queryEmbedding, limit: searchLimit });
+    if (contentTypes.length) {
+        hits = hits.filter((h) => (h.clip.tags.content_type ?? []).some((t) => contentTypes.includes(String(t).toLowerCase()))).slice(0, limit);
+    }
     const ms = elapsedMs(t0);
     store.close();
     if (values.json) {
@@ -895,6 +931,13 @@ function normalizeProvider(value) {
         return value;
     throw new Error(`--provider must be gemini | openai | openrouter (got "${value}")`);
 }
+// Parse a comma-separated --content-type flag into lowercase shot-KIND tags for
+// the tags.content_type filter (talking_head, b_roll, product_shot, …).
+function parseContentTypes(value) {
+    if (!value)
+        return [];
+    return value.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+}
 function normalizeTier(value) {
     if (value === "flash")
         return "flash";