@socialseal/cli 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.1.5 - 2026-03-19
+- Add first-class tracked-video workflows with `video queue-analysis` and `video extract`.
+- Make `--video-id` the primary ergonomic selector for tracked-video analysis and asset extraction, while keeping `--search-result-id` as a fallback selector.
+- Support batch queueing/extraction payloads plus optional asset downloads for thumbnails, source video, and extracted key frames.
+
 ## 0.1.4 - 2026-03-19
 - Add explicit `group_add_item` / `group_add_items` CLI aliases for tracking-group membership workflows.
 - Add `tracking resolve` / `get_by_value` so existing tracked searches can be resolved by value using the same duplicate-detection semantics as create.

package/README.md

@@ -49,6 +49,12 @@ Optional config file:
   - `socialseal tools call --function search-journey-run --body @payload.json --async --workspace-id <uuid>`
   - `socialseal tools call --function search-journey-run --body @payload.json --async --no-poll --workspace-id <uuid>`
 
+- Tracked video extraction:
+  - `socialseal video queue-analysis --video-id 734829384 --workspace-id <uuid>`
+  - `socialseal video extract --video-id 734829384 --workspace-id <uuid>`
+  - `socialseal video extract --video-uid <video_uid> --wait --workspace-id <uuid>`
+  - `socialseal video extract --body @payload.json --out-dir ./video-assets`
+
 - Data exports (provisional):
   - `socialseal data export-tracking --group-id 123 --time-period 30d --out out.csv`
   - `socialseal data export-report --report-type keyword_universe --format csv --payload @payload.json --out out.csv`
@@ -58,6 +64,9 @@ Optional config file:
 - `tools list` ships a stable built-in registry of supported direct-call function targets. It is not live backend enumeration.
 - `--timeout <ms>` controls HTTP request timeouts. Agent runs default to a 5-minute WebSocket inactivity timeout unless you set `--idle-timeout <ms>` (or the matching env/config value).
 - `search-journey-run` supports CLI-managed async polling: `--async` starts backend async mode, polling is on by default, `--no-poll` returns the initial `runId`, and `--poll-interval <ms>` controls the status polling cadence.
+- `video queue-analysis` wraps the tracked-video extraction backend in queue-only mode so you can queue one or many tracked videos without downloading assets first.
+- `video extract` wraps the same backend in extraction mode and returns a normalized JSON payload with resolved tracking context, structured analysis, thumbnail/frame assets, and optional local downloads under `--out-dir`.
+- `--video-id` is the primary ergonomic selector for video workflows. The backend tries it as `video_uid` first, then as platform video id. `--search-result-id` remains available when you are starting from a specific tracked rank row.
 - `socialseal agent run` now defaults to a fresh conversation. The CLI prints a continuation token to `stderr`; pass it back with `--continue <token>` to resume the same agent conversation explicitly.
 - Effective workspace precedence is: `--workspace-id` → `SOCIALSEAL_WORKSPACE_ID` → config `workspaceId` → backend personal-workspace fallback.
 - `socialseal workspace use ...` writes a local default workspace into `~/.config/socialseal/config.json`, which the CLI reuses for `agent`, `tools`, and `data` commands.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socialseal/cli",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "private": false,
   "type": "module",
   "description": "SocialSeal CLI (non-interactive)",

package/src/index.js

@@ -13,6 +13,7 @@ const WORKSPACE_HEADER = 'X-Workspace-Id';
 const DEFAULT_TIMEOUT_MS = 30000;
 const DEFAULT_AGENT_IDLE_TIMEOUT_MS = 300000;
 const DEFAULT_POLL_INTERVAL_MS = 2000;
+const DEFAULT_FRAME_COUNT = 3;
 const MAX_TIMEOUT_MS = 900000;
 const LEGACY_ENABLED = process.env.SOCIALSEAL_ENABLE_LEGACY === '1';
 const STATIC_TOOL_REGISTRY_NOTE = 'This registry is shipped with the CLI for stable discovery. It is not live backend enumeration, so environment-specific availability can drift.';
@@ -62,6 +63,16 @@ const KNOWN_TOOLS = [
     knownLocalDevState: 'disabled_by_default',
     notes: 'group_id expects a numeric tracking_group id, not a brand_group UUID.',
   },
+  {
+    name: 'tracked-video-extract',
+    category: 'video',
+    description: 'Resolve tracked videos/results into structured analysis plus reference assets.',
+    objectType: 'tracked_video_extract',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    notes: 'Accepts videoId/videoUid/platformVideoId/searchResultId items; can queue analysis and return/download asset URLs.',
+  },
   { name: 'douyin-geo-api', category: 'search', description: 'Query Douyin search and geo data.' },
   { name: 'google-ai-search', category: 'search', description: 'Run Google AI search queries and fetch result snapshots.' },
   { name: 'instagram-geo-api', category: 'search', description: 'Query Instagram search and geo data.' },
@@ -339,6 +350,273 @@ function mergeWorkspaceIdIntoPayload(payload, workspaceId) {
   return { ...payload, workspaceId };
 }
 
+function sanitizeFileComponent(value, fallback = 'item') {
+  const normalized = String(value || '')
+    .trim()
+    .replace(/[^a-z0-9._-]+/gi, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+  return normalized || fallback;
+}
+
+function inferExtension(urlValue, contentType, fallback = '.bin') {
+  const normalizedType = String(contentType || '').toLowerCase();
+  if (normalizedType.includes('jpeg')) return '.jpg';
+  if (normalizedType.includes('png')) return '.png';
+  if (normalizedType.includes('webp')) return '.webp';
+  if (normalizedType.includes('gif')) return '.gif';
+  if (normalizedType.includes('mp4')) return '.mp4';
+  if (normalizedType.includes('quicktime')) return '.mov';
+
+  try {
+    const pathname = new URL(urlValue).pathname || '';
+    const ext = path.extname(pathname);
+    if (ext) return ext;
+  } catch {
+    // ignore parse failures
+  }
+  return fallback;
+}
+
+function normalizeVideoExtractBody(body) {
+  const normalized = { ...body };
+  const hasInlineIdentifier =
+    normalized.videoId !== undefined ||
+    normalized.searchResultId !== undefined ||
+    normalized.videoUid !== undefined ||
+    normalized.platformVideoId !== undefined;
+
+  if (!Array.isArray(normalized.items) && hasInlineIdentifier) {
+    normalized.items = [{
+      videoId: normalized.videoId,
+      searchResultId: normalized.searchResultId,
+      videoUid: normalized.videoUid,
+      platformVideoId: normalized.platformVideoId,
+      platformId: normalized.platformId,
+    }];
+    delete normalized.videoId;
+    delete normalized.searchResultId;
+    delete normalized.videoUid;
+    delete normalized.platformVideoId;
+    delete normalized.platformId;
+  }
+
+  return normalized;
+}
+
+function buildVideoExtractBody(opts, workspaceId) {
+  const parsed = opts.body
+    ? ensureJsonObject(parseJsonInput(opts.body, { label: 'body' }), 'body')
+    : {};
+  const normalized = normalizeVideoExtractBody(parsed);
+
+  if (!Array.isArray(normalized.items) || normalized.items.length === 0) {
+    const inlineItem = stripUndefinedEntries({
+      videoId: trimString(opts.videoId) || undefined,
+      searchResultId: opts.searchResultId !== undefined
+        ? coercePositiveInteger(opts.searchResultId, 'searchResultId')
+        : undefined,
+      videoUid: trimString(opts.videoUid) || undefined,
+      platformVideoId: trimString(opts.platformVideoId) || undefined,
+    });
+
+    if (Object.keys(inlineItem).length === 0) {
+      throw new CliError('Provide --body or one of --video-id, --video-uid, --platform-video-id, or --search-result-id.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+
+    normalized.items = [inlineItem];
+  }
+
+  const bodyWithWorkspace = mergeWorkspaceIdIntoPayload(normalized, workspaceId);
+  if (!bodyWithWorkspace.workspaceId) {
+    throw new CliError('tracked-video extraction requires a workspace id.', {
+      code: 'WORKSPACE_REQUIRED',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Pass --workspace-id, set SOCIALSEAL_WORKSPACE_ID, or configure a default workspace.',
+    });
+  }
+
+  const nextBody = { ...bodyWithWorkspace };
+  if (opts.wait) {
+    nextBody.ensureAnalysis = true;
+  } else if (opts.ensureAnalysis === true) {
+    nextBody.ensureAnalysis = true;
+  } else if (nextBody.ensureAnalysis === undefined) {
+    nextBody.ensureAnalysis = false;
+  }
+
+  if (opts.skipAssets === true) {
+    nextBody.includeAssets = false;
+  } else if (nextBody.includeAssets === undefined) {
+    nextBody.includeAssets = true;
+  }
+
+  if (opts.includeSourceVideo === true) {
+    nextBody.includeSourceVideo = true;
+  } else if (nextBody.includeSourceVideo === undefined) {
+    nextBody.includeSourceVideo = false;
+  }
+
+  if (opts.frameStrategy && nextBody.frameStrategy === undefined) {
+    nextBody.frameStrategy = opts.frameStrategy;
+  }
+  if (nextBody.frameStrategy === undefined) {
+    nextBody.frameStrategy = 'brief_shots';
+  }
+
+  if (nextBody.frameCount === undefined) {
+    nextBody.frameCount = opts.frameCount !== undefined
+      ? Number(opts.frameCount)
+      : DEFAULT_FRAME_COUNT;
+  }
+
+  if (nextBody.signedUrlSeconds === undefined) {
+    nextBody.signedUrlSeconds = opts.signedUrlSeconds !== undefined
+      ? Number(opts.signedUrlSeconds)
+      : 3600;
+  }
+
+  return nextBody;
+}
+
+function buildVideoQueueBody(opts, workspaceId) {
+  const body = buildVideoExtractBody(opts, workspaceId);
+  return {
+    ...body,
+    ensureAnalysis: true,
+    queueOnly: true,
+    includeAssets: false,
+    includeRawAnalysis: false,
+    includeSourceVideo: false,
+  };
+}
+
+function hasPendingVideoExtractResults(payload) {
+  const results = Array.isArray(payload?.results) ? payload.results : [];
+  return results.some((result) => {
+    const status = String(result?.analysis?.status || '').trim().toLowerCase();
+    return status === 'pending' || status === 'processing';
+  });
+}
+
+async function downloadAssetToFile({ url, outDir, stem, timeoutMs }) {
+  const response = await fetchWithTimeout(url, {
+    method: 'GET',
+    headers: { Accept: '*/*' },
+  }, timeoutMs);
+
+  if (!response.ok) {
+    throw new CliError(`Asset download failed: ${response.status}`, {
+      code: 'ASSET_DOWNLOAD_FAILED',
+      exitCode: EXIT_CODES.SERVER,
+      details: await response.text().catch(() => null),
+    });
+  }
+
+  const extension = inferExtension(url, response.headers.get('content-type'));
+  const absolutePath = path.resolve(outDir, `${stem}${extension}`);
+  fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+  const buffer = Buffer.from(await response.arrayBuffer());
+  fs.writeFileSync(absolutePath, buffer);
+  return {
+    path: absolutePath,
+    bytes: buffer.length,
+  };
+}
+
+async function downloadVideoExtractAssets(payload, outDir, timeoutMs) {
+  const results = Array.isArray(payload?.results) ? payload.results : [];
+  const absoluteBaseDir = path.resolve(outDir);
+  fs.mkdirSync(absoluteBaseDir, { recursive: true });
+
+  for (let index = 0; index < results.length; index += 1) {
+    const result = results[index];
+    const resolved = result?.resolved || {};
+    const videoKey = sanitizeFileComponent(
+      resolved.videoUid || resolved.platformVideoId || resolved.searchResultId || `item-${index + 1}`,
+      `item-${index + 1}`,
+    );
+    const itemDir = path.join(absoluteBaseDir, `${String(index + 1).padStart(2, '0')}-${videoKey}`);
+    const downloads = {
+      directory: itemDir,
+      thumbnail: null,
+      sourceVideo: null,
+      frames: [],
+    };
+
+    const thumbnailUrl = result?.assets?.thumbnail?.url;
+    if (typeof thumbnailUrl === 'string' && thumbnailUrl.length > 0) {
+      try {
+        downloads.thumbnail = await downloadAssetToFile({
+          url: thumbnailUrl,
+          outDir: itemDir,
+          stem: 'thumbnail',
+          timeoutMs,
+        });
+      } catch (error) {
+        downloads.thumbnail = {
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    }
+
+    const sourceVideoUrl = result?.assets?.sourceVideo?.signedUrl;
+    if (typeof sourceVideoUrl === 'string' && sourceVideoUrl.length > 0) {
+      try {
+        downloads.sourceVideo = await downloadAssetToFile({
+          url: sourceVideoUrl,
+          outDir: itemDir,
+          stem: 'source-video',
+          timeoutMs,
+        });
+      } catch (error) {
+        downloads.sourceVideo = {
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    }
+
+    const frames = Array.isArray(result?.assets?.frames) ? result.assets.frames : [];
+    for (let frameIndex = 0; frameIndex < frames.length; frameIndex += 1) {
+      const frame = frames[frameIndex];
+      const frameUrl = frame?.signedUrl;
+      if (typeof frameUrl !== 'string' || frameUrl.length === 0) continue;
+      const timestampToken = sanitizeFileComponent(frame?.timestamp || `frame-${frameIndex + 1}`, `frame-${frameIndex + 1}`);
+      try {
+        const download = await downloadAssetToFile({
+          url: frameUrl,
+          outDir: itemDir,
+          stem: `${frame?.kind || 'frame'}-${String(frameIndex + 1).padStart(2, '0')}-${timestampToken}`,
+          timeoutMs,
+        });
+        downloads.frames.push({
+          kind: frame?.kind || null,
+          timestamp: frame?.timestamp || null,
+          path: download.path,
+          bytes: download.bytes,
+        });
+      } catch (error) {
+        downloads.frames.push({
+          kind: frame?.kind || null,
+          timestamp: frame?.timestamp || null,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+
+    result.downloads = downloads;
+  }
+
+  return {
+    ...payload,
+    downloadsRoot: absoluteBaseDir,
+    results,
+  };
+}
+
 function hasOwn(value, key) {
   return Boolean(value) && Object.prototype.hasOwnProperty.call(value, key);
 }
@@ -2156,6 +2434,160 @@ async function handleDataExportReport(opts) {
   process.stdout.write(JSON.stringify(json, null, opts.pretty ? 2 : 0) + '\n');
 }
 
+async function handleVideoExtract(opts) {
+  const config = loadConfig();
+  const apiKey = requireApiKey(opts, config);
+  const apiBase = resolveApiBase(opts, config);
+  const supabaseUrl = resolveLegacyUrl(resolveSupabaseUrl(opts, config), 'SOCIALSEAL_SUPABASE_URL');
+  const { resolvedApiBase, legacyUrl, useGateway } = resolveApiTarget({ apiBase, legacyUrl: supabaseUrl });
+  const timeoutMs = resolveTimeoutMs(opts, config);
+  const { workspaceId: resolvedWorkspaceId, source: workspaceSource } = resolveWorkspaceSelection(opts, config);
+
+  const body = buildVideoExtractBody(opts, resolvedWorkspaceId);
+  const path = useGateway ? '/cli/tools/tracked-video-extract' : '/functions/v1/tracked-video-extract';
+
+  emitWorkspaceContext(opts, {
+    workspaceId: body.workspaceId || resolvedWorkspaceId,
+    source: body.workspaceId === resolvedWorkspaceId ? workspaceSource : 'body',
+    functionName: 'tracked-video-extract',
+    method: 'POST',
+  });
+
+  const requestOnce = async (remainingTimeoutMs) => {
+    const res = await callApi({
+      apiBase: useGateway ? resolvedApiBase : legacyUrl,
+      apiKey,
+      path,
+      method: 'POST',
+      body,
+      workspaceId: body.workspaceId || resolvedWorkspaceId,
+      timeoutMs: remainingTimeoutMs,
+    });
+
+    if (!res.ok) {
+      throw await buildHttpError(res, {
+        label: 'Tracked video extract',
+        functionName: 'tracked-video-extract',
+        method: 'POST',
+      });
+    }
+
+    const contentType = res.headers.get('content-type') || '';
+    if (!contentType.includes('application/json')) {
+      throw new CliError('tracked-video-extract returned a non-JSON response.', {
+        code: 'INVALID_RESPONSE',
+        exitCode: EXIT_CODES.SERVER,
+      });
+    }
+
+    return await res.json();
+  };
+
+  let payload = await requestOnce(timeoutMs);
+
+  if (opts.wait) {
+    const pollIntervalMs = resolvePollIntervalMs(opts);
+    const deadline = Date.now() + timeoutMs;
+
+    while (hasPendingVideoExtractResults(payload)) {
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) {
+        throw new CliError('Timed out waiting for tracked video analysis completion.', {
+          code: 'ASYNC_WAIT_TIMEOUT',
+          exitCode: EXIT_CODES.SERVER,
+          hint: 'Increase --timeout <ms> or omit --wait to return the current status immediately.',
+          details: truncateDetails(payload),
+        });
+      }
+
+      emitInfo(opts, 'tracked-video-extract pending; polling for completion.');
+      await sleep(Math.min(pollIntervalMs, remainingMs));
+      payload = await requestOnce(Math.max(1000, deadline - Date.now()));
+    }
+  }
+
+  if (opts.outDir) {
+    payload = await downloadVideoExtractAssets(payload, opts.outDir, timeoutMs);
+  }
+
+  emitJsonOutput(payload, opts.pretty);
+}
+
+async function handleVideoQueueAnalysis(opts) {
+  const config = loadConfig();
+  const apiKey = requireApiKey(opts, config);
+  const apiBase = resolveApiBase(opts, config);
+  const supabaseUrl = resolveLegacyUrl(resolveSupabaseUrl(opts, config), 'SOCIALSEAL_SUPABASE_URL');
+  const { resolvedApiBase, legacyUrl, useGateway } = resolveApiTarget({ apiBase, legacyUrl: supabaseUrl });
+  const timeoutMs = resolveTimeoutMs(opts, config);
+  const { workspaceId: resolvedWorkspaceId, source: workspaceSource } = resolveWorkspaceSelection(opts, config);
+
+  const body = buildVideoQueueBody(opts, resolvedWorkspaceId);
+  const path = useGateway ? '/cli/tools/tracked-video-extract' : '/functions/v1/tracked-video-extract';
+
+  emitWorkspaceContext(opts, {
+    workspaceId: body.workspaceId || resolvedWorkspaceId,
+    source: body.workspaceId === resolvedWorkspaceId ? workspaceSource : 'body',
+    functionName: 'tracked-video-extract',
+    method: 'POST',
+  });
+
+  const requestOnce = async (remainingTimeoutMs) => {
+    const res = await callApi({
+      apiBase: useGateway ? resolvedApiBase : legacyUrl,
+      apiKey,
+      path,
+      method: 'POST',
+      body,
+      workspaceId: body.workspaceId || resolvedWorkspaceId,
+      timeoutMs: remainingTimeoutMs,
+    });
+
+    if (!res.ok) {
+      throw await buildHttpError(res, {
+        label: 'Tracked video queue-analysis',
+        functionName: 'tracked-video-extract',
+        method: 'POST',
+      });
+    }
+
+    const contentType = res.headers.get('content-type') || '';
+    if (!contentType.includes('application/json')) {
+      throw new CliError('tracked-video-extract returned a non-JSON response.', {
+        code: 'INVALID_RESPONSE',
+        exitCode: EXIT_CODES.SERVER,
+      });
+    }
+
+    return await res.json();
+  };
+
+  let payload = await requestOnce(timeoutMs);
+
+  if (opts.wait) {
+    const pollIntervalMs = resolvePollIntervalMs(opts);
+    const deadline = Date.now() + timeoutMs;
+
+    while (hasPendingVideoExtractResults(payload)) {
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) {
+        throw new CliError('Timed out waiting for queued video analysis completion.', {
+          code: 'ASYNC_WAIT_TIMEOUT',
+          exitCode: EXIT_CODES.SERVER,
+          hint: 'Increase --timeout <ms> or omit --wait to return queue status immediately.',
+          details: truncateDetails(payload),
+        });
+      }
+
+      emitInfo(opts, 'tracked-video queue-analysis pending; polling for completion.');
+      await sleep(Math.min(pollIntervalMs, remainingMs));
+      payload = await requestOnce(Math.max(1000, deadline - Date.now()));
+    }
+  }
+
+  emitJsonOutput(payload, opts.pretty);
+}
+
 async function handleWorkspaceList(opts) {
   const config = loadConfig();
   const apiKey = requireApiKey(opts, config);
@@ -2312,7 +2744,7 @@ if (typeof program.showHelpAfterError === 'function') {
 if (typeof program.showSuggestionAfterError === 'function') {
   program.showSuggestionAfterError(true);
 }
-program.addHelpText('after', `\nExamples:\n  socialseal workspace list\n  socialseal workspace use <workspace-id>\n  socialseal agent run --message \"ping\"\n  socialseal tools list\n  socialseal tools call --function <tool> --body @payload.json\n  socialseal tools call --function search-journey-run --body @payload.json --async --workspace-id <uuid>\n  socialseal data export-tracking --group-id 123 --time-period 30d\n`);
+program.addHelpText('after', `\nExamples:\n  socialseal workspace list\n  socialseal workspace use <workspace-id>\n  socialseal agent run --message \"ping\"\n  socialseal tools list\n  socialseal tools call --function <tool> --body @payload.json\n  socialseal tools call --function search-journey-run --body @payload.json --async --workspace-id <uuid>\n  socialseal video queue-analysis --video-id 734829384 --workspace-id <uuid>\n  socialseal video extract --video-id 734829384 --wait --out-dir ./video-assets\n  socialseal data export-tracking --group-id 123 --time-period 30d\n`);
 
 program
   .command('agent')
@@ -2437,4 +2869,51 @@ data
   .option('--verbose', 'Show error details')
   .action((opts) => runCommand(handleDataExportReport, opts));
 
+const video = program.command('video').description('Tracked video extraction workflows');
+
+video
+  .command('queue-analysis')
+  .description('Queue video analysis for tracked videos or tracked search results')
+  .option('--video-id <id>', 'Tracked video id (tries video_uid first, then platform video id)')
+  .option('--search-result-id <id>', 'Tracked search result id')
+  .option('--video-uid <id>', 'Tracked video_uid')
+  .option('--platform-video-id <id>', 'Tracked platform video id')
+  .option('--body <jsonOrFile>', 'JSON body or @payload.json for batch queueing')
+  .option('--wait', 'Poll until queued/completing analyses settle')
+  .option('--poll-interval <ms>', 'Polling interval in milliseconds when --wait is enabled')
+  .option('--api-base <url>', 'API base URL (default https://api.socialseal.co)')
+  .option('--api-key <key>', 'CLI API key')
+  .option('--workspace-id <id>', 'Workspace id (for scoped keys)')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--json', 'Emit machine-readable errors')
+  .option('--timeout <ms>', 'Request timeout in milliseconds')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleVideoQueueAnalysis, opts));
+
+video
+  .command('extract')
+  .description('Resolve tracked videos/results into structured analysis plus reference assets')
+  .option('--video-id <id>', 'Tracked video id (tries video_uid first, then platform video id)')
+  .option('--search-result-id <id>', 'Tracked search result id')
+  .option('--video-uid <id>', 'Tracked video_uid')
+  .option('--platform-video-id <id>', 'Tracked platform video id')
+  .option('--body <jsonOrFile>', 'JSON body or @payload.json for batch extraction')
+  .option('--ensure-analysis', 'Queue analysis when it is missing')
+  .option('--wait', 'Poll until queued/completing analyses settle')
+  .option('--poll-interval <ms>', 'Polling interval in milliseconds when --wait is enabled')
+  .option('--skip-assets', 'Skip asset URL generation')
+  .option('--include-source-video', 'Include a signed source MP4 URL when available')
+  .option('--frame-strategy <strategy>', 'brief_shots|quartiles')
+  .option('--frame-count <n>', 'Number of still frames to return (1-5)')
+  .option('--signed-url-seconds <n>', 'Signed URL TTL in seconds')
+  .option('--out-dir <path>', 'Download returned assets into this local directory')
+  .option('--api-base <url>', 'API base URL (default https://api.socialseal.co)')
+  .option('--api-key <key>', 'CLI API key')
+  .option('--workspace-id <id>', 'Workspace id (for scoped keys)')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--json', 'Emit machine-readable errors')
+  .option('--timeout <ms>', 'Request timeout in milliseconds')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleVideoExtract, opts));
+
 program.parseAsync(process.argv);