@socialseal/cli 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 0.1.6 - 2026-03-19
+- Fix runtime version reporting so `socialseal --version` reads from package metadata instead of a hardcoded source string.
+- Fix `tracking` create request translation so `--workspace-id` is sent on the REST query path the backend uses for workspace binding.
+- Improve tracked-video extraction failure messages by avoiding `[object Object]` item errors and returning explicit guidance when `videoId` is actually a search-result id or tracking item id.
+- Fail fast for `group-management` and `export_tracking_data` when no workspace is selected, instead of silently relying on backend personal-workspace fallback.
+- Warn when `tracking create` runs without a workspace and when short numeric `--video-id` values look like internal row ids.
+- Clarify in workspace discovery output and docs that `workspace_id` and `brand_id` are different identifiers.
+
+## 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,8 +49,14 @@ 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-tracking --group-id 123 --time-period 30d --workspace-id <uuid> --out out.csv`
   - `socialseal data export-report --report-type keyword_universe --format csv --payload @payload.json --out out.csv`
 
 ## Notes
@@ -58,10 +64,16 @@ 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. It does not accept tracking item ids. `--search-result-id` remains available when you are starting from a specific tracked rank row.
+- `group-management` and `export_tracking_data` now fail fast when no workspace is selected, instead of letting the backend silently fall back to the personal workspace.
+- `tracking create` without a workspace now prints a warning that the backend may create a personal/null-scope item.
+- Short numeric `--video-id` inputs now print a warning that they may be internal row ids and that `--search-result-id` is often the intended selector.
 - `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.
+- Effective workspace precedence is: `--workspace-id` → `SOCIALSEAL_WORKSPACE_ID` → config `workspaceId`. For commands that are easy to misuse (`group-management`, `export_tracking_data`, tracked-video workflows), the CLI now requires an explicit or preconfigured workspace instead of relying on backend fallback.
 - `socialseal workspace use ...` writes a local default workspace into `~/.config/socialseal/config.json`, which the CLI reuses for `agent`, `tools`, and `data` commands.
-- `socialseal workspace list` discovers the workspaces accessible to the current CLI key and marks the active/suggested default.
+- `socialseal workspace list` discovers the workspaces accessible to the current CLI key, marks the active/suggested default, and reminds you that `workspace_id` and `brand_id` are different identifiers.
 - If a scoped CLI key cannot safely infer a workspace, `agent run` now fails closed and tells you to set `--workspace-id` or configure a local default first.
 
 ## Errors and exit codes

package/package.json

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

package/src/index.js

@@ -13,8 +13,10 @@ 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 CLI_VERSION = loadRuntimeVersion();
 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.';
 const EXIT_CODES = {
   OK: 0,
@@ -60,7 +62,17 @@ const KNOWN_TOOLS = [
     transport: 'post_edge_function',
     workspaceScoped: true,
     knownLocalDevState: 'disabled_by_default',
-    notes: 'group_id expects a numeric tracking_group id, not a brand_group UUID.',
+    notes: 'group_id expects a numeric tracking_group id, not a brand_group UUID. Always pass a workspace id or configure a default workspace so the export does not silently target the personal workspace.',
+  },
+  {
+    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; videoId means video_uid or platform-native video id, not a tracking item id.',
   },
   { 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.' },
@@ -77,7 +89,7 @@ const KNOWN_TOOLS = [
     workspaceScoped: true,
     knownLocalDevState: 'disabled_by_default',
     actionAliases: ['list', 'get', 'create', 'update', 'delete', 'refresh', 'list_items', 'add_item', 'group_add_item', 'add_items', 'group_add_items', 'remove_item', 'group_remove_item'],
-    notes: 'REST-style surface under /groups. `add_item`/`group_add_item` accepts an existing `item_id`; `add_items`/`group_add_items` accepts `item_ids` or item payloads for bulk membership adds.',
+    notes: 'REST-style surface under /groups. `add_item`/`group_add_item` accepts an existing `item_id`; `add_items`/`group_add_items` accepts `item_ids` or item payloads for bulk membership adds. Always pass a workspace id or configure a default workspace so the backend does not fall back to the personal workspace.',
   },
   {
     name: 'tracking',
@@ -112,6 +124,26 @@ function getConfigPath() {
   return process.env.SOCIALSEAL_CONFIG || DEFAULT_CONFIG_PATH;
 }
 
+function loadRuntimeVersion() {
+  const envVersion = typeof process.env.npm_package_version === 'string'
+    ? process.env.npm_package_version.trim()
+    : '';
+  if (envVersion) return envVersion;
+
+  try {
+    const packageJsonPath = new URL('../package.json', import.meta.url);
+    const raw = fs.readFileSync(packageJsonPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed?.version === 'string' && parsed.version.trim().length > 0) {
+      return parsed.version.trim();
+    }
+  } catch {
+    // fall through to the safe fallback below
+  }
+
+  return '0.0.0';
+}
+
 function loadConfig() {
   const configPath = getConfigPath();
   try {
@@ -339,6 +371,274 @@ 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,
+        hint: '--video-id accepts a video_uid or platform video id. It does not accept tracking item ids.',
+      });
+    }
+
+    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);
 }
@@ -655,7 +955,7 @@ function translateTrackingAction(payload, workspaceId) {
   if (!action) {
     return {
       method: 'POST',
-      pathSuffix: '',
+      pathSuffix: buildPathWithQuery('', { workspace_id: workspaceId || undefined }),
       body: stripUndefinedEntries({
         name: payload.name,
         track_type: payload.track_type,
@@ -735,7 +1035,7 @@ function translateTrackingAction(payload, workspaceId) {
   if (action === 'create' || action === 'item_create') {
     return {
       method: 'POST',
-      pathSuffix: '',
+      pathSuffix: buildPathWithQuery('', { workspace_id: workspaceId || undefined }),
       body: stripUndefinedEntries({
         name: payload.name,
         track_type: payload.track_type,
@@ -1202,6 +1502,61 @@ function emitWorkspaceContext(opts, { workspaceId, source, functionName, method
   );
 }
 
+function describeWorkspaceSource(source) {
+  switch (source) {
+    case 'flag':
+      return '--workspace-id';
+    case 'env':
+      return 'SOCIALSEAL_WORKSPACE_ID';
+    case 'config':
+      return 'the saved default workspace';
+    case 'body':
+      return 'the request body';
+    default:
+      return 'implicit selection';
+  }
+}
+
+function emitWorkspaceSelectionNotice(opts, { workspaceId, source, label }) {
+  if (!workspaceId || !source || source === 'flag' || source === 'body') return;
+  process.stderr.write(
+    `[socialseal] Using workspace ${workspaceId} from ${describeWorkspaceSource(source)} for ${label}. Pass --workspace-id to override.\n`,
+  );
+}
+
+function requireWorkspaceSelection(workspaceId, { label, hint }) {
+  if (workspaceId) return workspaceId;
+  throw new CliError(`${label} requires a workspace id.`, {
+    code: 'WORKSPACE_REQUIRED',
+    exitCode: EXIT_CODES.USAGE,
+    hint,
+  });
+}
+
+function emitTrackingCreateScopeWarning(action, workspaceId) {
+  if (action !== 'create' || workspaceId) return;
+  process.stderr.write(
+    '[socialseal] tracking create is running without a workspace id. The backend may create a personal/null-scope item that is not attached to a workspace or group.\n',
+  );
+}
+
+function looksLikeShortNumericVideoId(value) {
+  return typeof value === 'string' && /^\d{1,7}$/.test(value.trim());
+}
+
+function emitAmbiguousVideoIdWarnings(items) {
+  const references = Array.isArray(items) ? items : [];
+  for (const item of references) {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) continue;
+    if (looksLikeShortNumericVideoId(item.videoId)) {
+      process.stderr.write(
+        `[socialseal] videoId "${item.videoId}" looks like a short internal row id. If you meant a ranked result row, use --search-result-id. If you meant a tracking item id, resolve it first and retry with --video-uid or --platform-video-id.\n`,
+      );
+      return;
+    }
+  }
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1351,7 +1706,7 @@ function buildStatusHint(status, context = {}) {
     case 404:
       if (context.functionName) {
         if (isLocallyDisabledByDefaultFunction(context.functionName)) {
-          return `Unknown function "${context.functionName}". This tool is listed in the static registry, but it is disabled by default in some local Supabase environments. Check the deployment or enable it in supabase/config.toml.`;
+          return `Unknown function "${context.functionName}". The CLI ships a static registry, but availability depends on the backend you are calling. Verify the tool is deployed on the current API base; for local direct Supabase calls, enable it in supabase/config.toml.`;
         }
         return `Unknown function "${context.functionName}". Double-check the name and API base.`;
       }
@@ -1919,14 +2274,64 @@ async function handleToolsCall(opts) {
     resolvedWorkspaceId,
   });
   const method = normalizeMethod(translated.method);
-  const effectiveWorkspaceId = translated.workspaceId ?? resolvedWorkspaceId ?? null;
+  const payloadWorkspaceId = isJsonObject(translated.normalizedPayload)
+    ? resolvePayloadWorkspaceId(translated.normalizedPayload, resolvedWorkspaceId)
+    : (isJsonObject(translated.body)
+        ? resolvePayloadWorkspaceId(translated.body, resolvedWorkspaceId)
+        : (resolvedWorkspaceId ?? null));
+  const effectiveWorkspaceId = translated.workspaceId ?? payloadWorkspaceId ?? null;
+  const effectiveWorkspaceSource =
+    translated.workspaceId && translated.workspaceId !== resolvedWorkspaceId
+      ? 'body'
+      : (payloadWorkspaceId && payloadWorkspaceId !== resolvedWorkspaceId ? 'body' : workspaceSource);
   const path = useGateway
     ? `/cli/tools/${opts.function}${translated.pathSuffix || ''}`
     : `/functions/v1/${opts.function}${translated.pathSuffix || ''}`;
 
+  if (opts.function === 'group-management') {
+    requireWorkspaceSelection(effectiveWorkspaceId, {
+      label: 'group-management',
+      hint: 'Pass --workspace-id, set SOCIALSEAL_WORKSPACE_ID, or configure a default workspace. Omitting workspace lets the backend fall back to the personal workspace.',
+    });
+    emitWorkspaceSelectionNotice(opts, {
+      workspaceId: effectiveWorkspaceId,
+      source: effectiveWorkspaceSource,
+      label: 'group-management',
+    });
+  }
+
+  if (opts.function === 'export_tracking_data') {
+    requireWorkspaceSelection(effectiveWorkspaceId, {
+      label: 'export_tracking_data',
+      hint: 'Pass --workspace-id, set SOCIALSEAL_WORKSPACE_ID, or configure a default workspace before exporting tracking data.',
+    });
+    emitWorkspaceSelectionNotice(opts, {
+      workspaceId: effectiveWorkspaceId,
+      source: effectiveWorkspaceSource,
+      label: 'export_tracking_data',
+    });
+  }
+
+  if (opts.function === 'tracked-video-extract') {
+    requireWorkspaceSelection(effectiveWorkspaceId, {
+      label: 'tracked-video-extract',
+      hint: 'Pass --workspace-id, set SOCIALSEAL_WORKSPACE_ID, or configure a default workspace.',
+    });
+    emitWorkspaceSelectionNotice(opts, {
+      workspaceId: effectiveWorkspaceId,
+      source: effectiveWorkspaceSource,
+      label: 'tracked-video-extract',
+    });
+  }
+
+  emitTrackingCreateScopeWarning(
+    isJsonObject(translated.normalizedPayload) ? trimString(translated.normalizedPayload.action).toLowerCase() : '',
+    effectiveWorkspaceId,
+  );
+
   emitWorkspaceContext(opts, {
     workspaceId: effectiveWorkspaceId,
-    source: effectiveWorkspaceId === resolvedWorkspaceId ? workspaceSource : 'body',
+    source: effectiveWorkspaceSource,
     functionName: opts.function,
     method,
   });
@@ -2041,7 +2446,7 @@ async function handleDataExportTracking(opts) {
   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 } = resolveWorkspaceSelection(opts, config);
+  const { workspaceId: resolvedWorkspaceId, source: workspaceSource } = resolveWorkspaceSelection(opts, config);
 
   if (!opts.groupId && !opts.itemId) {
     throw new CliError('Provide --group-id or --item-id.', {
@@ -2063,6 +2468,16 @@ async function handleDataExportTracking(opts) {
     time_period: opts.timePeriod,
   };
 
+  requireWorkspaceSelection(resolvedWorkspaceId, {
+    label: 'Tracking export',
+    hint: 'Pass --workspace-id, set SOCIALSEAL_WORKSPACE_ID, or configure a default workspace before exporting tracking data.',
+  });
+  emitWorkspaceSelectionNotice(opts, {
+    workspaceId: resolvedWorkspaceId,
+    source: workspaceSource,
+    label: 'tracking export',
+  });
+
   const res = await callApi({
     apiBase: useGateway ? resolvedApiBase : legacyUrl,
     apiKey,
@@ -2156,6 +2571,178 @@ 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';
+  const effectiveWorkspaceId = body.workspaceId || resolvedWorkspaceId;
+  const effectiveWorkspaceSource = body.workspaceId && body.workspaceId !== resolvedWorkspaceId ? 'body' : workspaceSource;
+
+  emitWorkspaceSelectionNotice(opts, {
+    workspaceId: effectiveWorkspaceId,
+    source: effectiveWorkspaceSource,
+    label: 'tracked-video extract',
+  });
+  emitAmbiguousVideoIdWarnings(body.items);
+
+  emitWorkspaceContext(opts, {
+    workspaceId: effectiveWorkspaceId,
+    source: effectiveWorkspaceSource,
+    functionName: 'tracked-video-extract',
+    method: 'POST',
+  });
+
+  const requestOnce = async (remainingTimeoutMs) => {
+    const res = await callApi({
+      apiBase: useGateway ? resolvedApiBase : legacyUrl,
+      apiKey,
+      path,
+      method: 'POST',
+      body,
+      workspaceId: effectiveWorkspaceId,
+      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 effectiveWorkspaceId = body.workspaceId || resolvedWorkspaceId;
+  const effectiveWorkspaceSource = body.workspaceId && body.workspaceId !== resolvedWorkspaceId ? 'body' : workspaceSource;
+
+  emitWorkspaceSelectionNotice(opts, {
+    workspaceId: effectiveWorkspaceId,
+    source: effectiveWorkspaceSource,
+    label: 'tracked-video queue-analysis',
+  });
+  emitAmbiguousVideoIdWarnings(body.items);
+  const path = useGateway ? '/cli/tools/tracked-video-extract' : '/functions/v1/tracked-video-extract';
+
+  emitWorkspaceContext(opts, {
+    workspaceId: effectiveWorkspaceId,
+    source: effectiveWorkspaceSource,
+    functionName: 'tracked-video-extract',
+    method: 'POST',
+  });
+
+  const requestOnce = async (remainingTimeoutMs) => {
+    const res = await callApi({
+      apiBase: useGateway ? resolvedApiBase : legacyUrl,
+      apiKey,
+      path,
+      method: 'POST',
+      body,
+      workspaceId: effectiveWorkspaceId,
+      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);
@@ -2192,6 +2779,8 @@ async function handleWorkspaceList(opts) {
     process.stdout.write(`${formatWorkspaceLine(workspace, { isEffective, source: selection.source, isSuggested })}\n`);
   }
 
+  process.stdout.write('\n[socialseal] Note: workspace ids are not brand ids. When a payload includes both workspace_id and brand_id, pass the workspace id to --workspace-id.\n');
+
   if (!selection.workspaceId && directory.defaultWorkspaceId) {
     process.stdout.write('\n[socialseal] No local default is configured. Set one with: socialseal workspace use <id>\n');
   }
@@ -2236,6 +2825,7 @@ async function handleWorkspaceCurrent(opts) {
 
   if (effectiveWorkspace) {
     process.stdout.write(`[socialseal] Effective workspace: ${effectiveWorkspace.name} (${effectiveWorkspace.id}) via ${selection.source}\n`);
+    process.stdout.write('[socialseal] Note: workspace ids are not brand ids. Use the workspace id, not brand_id, with --workspace-id.\n');
     return;
   }
 
@@ -2304,7 +2894,7 @@ const program = new Command();
 program
   .name('socialseal')
   .description('SocialSeal CLI (non-interactive)')
-  .version('0.1.1');
+  .version(CLI_VERSION);
 
 if (typeof program.showHelpAfterError === 'function') {
   program.showHelpAfterError(true);
@@ -2312,7 +2902,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 +3027,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 identifier (video_uid first, then platform video id; not a tracking item id)')
+  .option('--search-result-id <id>', 'Tracked search result id for a ranked result row')
+  .option('--video-uid <id>', 'Canonical tracked video_uid')
+  .option('--platform-video-id <id>', 'Platform-native 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 identifier (video_uid first, then platform video id; not a tracking item id)')
+  .option('--search-result-id <id>', 'Tracked search result id for a ranked result row')
+  .option('--video-uid <id>', 'Canonical tracked video_uid')
+  .option('--platform-video-id <id>', 'Platform-native 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);