@socialseal/cli 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.1.7 - 2026-03-20
+- Add `socialseal data export-search-results` for CLI-first enriched ranked-search exports, including direct CSV download handling.
+- Add `search_results_enriched` as an alias on `socialseal data export-report` to map to the ranked-search export template.
+- Add `socialseal data export-options` to make available export workflows discoverable from the CLI.
+- Improve export ergonomics with local report-type validation and instructive failure guidance for processing, failed, and expired-download states.
+
+## 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.

package/README.md

@@ -56,21 +56,31 @@ Optional config file:
   - `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-options`
+  - `socialseal data export-tracking --group-id 123 --time-period 30d --workspace-id <uuid> --out out.csv`
+  - `socialseal data export-search-results --group-ids 123,124 --workspace-id <uuid> --out ranked.csv`
+  - `socialseal data export-report --report-type search_results_enriched --format csv --payload @payload.json --workspace-id <uuid> --out ranked.csv`
   - `socialseal data export-report --report-type keyword_universe --format csv --payload @payload.json --out out.csv`
 
 ## Notes
-- `export-report` and `export_tracking_data` are provisional until CLI export specs are finalized.
+- `export-report`, `export_tracking_data`, and `export-data`-backed exports are provisional until CLI export specs are finalized.
 - `tools list` ships a stable built-in registry of supported direct-call function targets. It is not live backend enumeration.
+- `data export-search-results` maps to `export-data` template `tracking_ranked_videos_raw` and returns enriched ranked-search rows (search fields + video metadata + latest metrics + analysis). It downloads the signed CSV artifact when available.
+- `data export-report --report-type search_results_enriched` is a compatibility alias to the same `export-data` template flow.
+- `data export-report` now validates report types locally and shows the allowed list immediately; run `socialseal data export-options` when choosing between export flows.
+- If an export returns metadata without a file URL (for example status `processing`), the CLI prints an explicit retry hint and returns the metadata JSON so automation can branch on status.
 - `--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.
+- `--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.5",
+  "version": "0.1.7",
   "private": false,
   "type": "module",
   "description": "SocialSeal CLI (non-interactive)",

package/src/index.js

@@ -16,6 +16,7 @@ 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,
@@ -26,6 +27,44 @@ const EXIT_CODES = {
   SERVER: 5,
 };
 const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']);
+const REPORT_TYPE_SEARCH_RESULTS_ENRICHED = 'search_results_enriched';
+const EXPORT_DATA_TEMPLATE_TRACKING_RANKED_VIDEOS_RAW = 'tracking_ranked_videos_raw';
+const SUPPORTED_EXPORT_REPORT_TYPES = [
+  'keyword_universe',
+  'cluster_insights',
+  'creator_signatures',
+  'post_publish',
+  'quick_audit',
+  REPORT_TYPE_SEARCH_RESULTS_ENRICHED,
+];
+const EXPORT_OPTIONS = [
+  {
+    id: 'tracking_csv',
+    command: 'socialseal data export-tracking --group-id <id> --time-period <window>',
+    summary: 'Legacy tracking CSV export for a group or tracking item.',
+    formats: ['csv'],
+    required: ['workspace id', '--group-id or --item-id', '--time-period'],
+    bestFor: 'Quick tracking-table exports and backwards-compatible pipelines.',
+  },
+  {
+    id: 'search_results_enriched',
+    command: 'socialseal data export-search-results --group-ids <id,id,...>',
+    summary: 'Enriched ranked search rows (search results + video + latest metrics + analysis).',
+    formats: ['csv'],
+    required: ['workspace id', '--group-ids'],
+    bestFor: 'SQL-like ranked-search datasets without using psql.',
+    alias: 'socialseal data export-report --report-type search_results_enriched --format csv --payload @payload.json',
+  },
+  {
+    id: 'report_templates',
+    command: 'socialseal data export-report --report-type <type> --format <format> --payload @payload.json',
+    summary: 'Report-template exports via export-report.',
+    formats: ['csv', 'json', 'markdown', 'html', 'excel_data'],
+    required: ['payload JSON'],
+    bestFor: 'Keyword universe, clusters, creators, post-publish timeline, and quick-audit exports.',
+    reportTypes: SUPPORTED_EXPORT_REPORT_TYPES,
+  },
+];
 const KNOWN_TOOLS = [
   { name: 'agent-tool-jobs', category: 'agent', description: 'Poll queued agent-backed tool jobs and fetch their results.' },
   { name: 'deep-exploration-runs', category: 'agent', description: 'Read or persist deep exploration render runs.' },
@@ -53,6 +92,16 @@ const KNOWN_TOOLS = [
     notes: 'Refreshes brand metrics for brands/workspaces. It does not refresh a tracking group by UUID.',
   },
   { name: 'export-report', category: 'export', description: 'Generate report exports (csv/json/markdown/html/excel_data).' },
+  {
+    name: 'export-data',
+    category: 'export',
+    description: 'Run raw workspace-scoped export templates with signed-URL artifacts.',
+    objectType: 'workspace_export',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'disabled_by_default',
+    notes: 'Includes template `tracking_ranked_videos_raw` for ranked search results with video + metrics + analysis enrichment.',
+  },
   {
     name: 'export_tracking_data',
     category: 'export',
@@ -61,7 +110,7 @@ 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',
@@ -71,7 +120,7 @@ const KNOWN_TOOLS = [
     transport: 'post_edge_function',
     workspaceScoped: true,
     knownLocalDevState: 'enabled',
-    notes: 'Accepts videoId/videoUid/platformVideoId/searchResultId items; can queue analysis and return/download asset URLs.',
+    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.' },
@@ -88,7 +137,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',
@@ -123,6 +172,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 {
@@ -424,6 +493,7 @@ function buildVideoExtractBody(opts, workspaceId) {
       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.',
       });
     }
 
@@ -669,6 +739,88 @@ function coercePositiveInteger(value, label) {
   });
 }
 
+function normalizePositiveIntegerList(value, label, { max } = {}) {
+  if (value === undefined || value === null || value === '') return [];
+  const entries = Array.isArray(value)
+    ? value
+    : String(value)
+      .split(',')
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+  const parsed = entries.map((entry, index) => {
+    const normalized = coercePositiveInteger(entry, `${label}[${index}]`);
+    if (!normalized) {
+      throw new CliError(`Invalid ${label}[${index}] value.`, {
+        code: 'INVALID_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return normalized;
+  });
+  const deduped = Array.from(new Set(parsed));
+  if (max && deduped.length > max) {
+    throw new CliError(`Too many ${label} values: received ${deduped.length}, max is ${max}.`, {
+      code: 'INVALID_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+  return deduped;
+}
+
+function normalizeIsoDateTime(value, label) {
+  if (value === undefined || value === null || value === '') return undefined;
+  if (typeof value !== 'string') {
+    throw new CliError(`Invalid ${label}: expected an ISO datetime string.`, {
+      code: 'INVALID_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+  const trimmed = value.trim();
+  const epoch = Date.parse(trimmed);
+  if (Number.isNaN(epoch)) {
+    throw new CliError(`Invalid ${label}: expected an ISO datetime string.`, {
+      code: 'INVALID_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+      details: value,
+    });
+  }
+  return new Date(epoch).toISOString();
+}
+
+function buildSearchResultsEnrichedExportPayload(rawPayload, workspaceId) {
+  const payload = isJsonObject(rawPayload) ? rawPayload : {};
+  const groupIds = normalizePositiveIntegerList(
+    firstDefined(payload, ['groupIds', 'group_ids']),
+    'groupIds',
+    { max: 100 },
+  );
+  if (groupIds.length === 0) {
+    throw new CliError('search_results_enriched export requires at least one group id.', {
+      code: 'MISSING_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Provide --group-ids for `data export-search-results`, or include groupIds in --payload for `data export-report`.',
+    });
+  }
+
+  const trackingItemIds = normalizePositiveIntegerList(
+    firstDefined(payload, ['trackingItemIds', 'tracking_item_ids']),
+    'trackingItemIds',
+    { max: 1000 },
+  );
+  const dateFrom = normalizeIsoDateTime(firstDefined(payload, ['dateFrom', 'date_from']), 'dateFrom');
+  const dateTo = normalizeIsoDateTime(firstDefined(payload, ['dateTo', 'date_to']), 'dateTo');
+  const filename = trimString(firstDefined(payload, ['filename'])) || undefined;
+
+  return stripUndefinedEntries({
+    workspaceId,
+    groupIds,
+    trackingItemIds: trackingItemIds.length > 0 ? trackingItemIds : undefined,
+    dateFrom,
+    dateTo,
+    filename,
+  });
+}
+
 function buildPathWithQuery(basePath, query) {
   const params = new URLSearchParams();
   for (const [key, rawValue] of Object.entries(query || {})) {
@@ -933,7 +1085,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,
@@ -1013,7 +1165,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,
@@ -1480,6 +1632,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));
 }
@@ -1618,7 +1825,9 @@ function mapStatusToExitCode(status) {
 }
 
 function isLocallyDisabledByDefaultFunction(functionName) {
-  return functionName === 'group-management' || functionName === 'export_tracking_data';
+  return functionName === 'group-management'
+    || functionName === 'export_tracking_data'
+    || functionName === 'export-data';
 }
 
 function buildStatusHint(status, context = {}) {
@@ -1629,7 +1838,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.`;
       }
@@ -1735,6 +1944,18 @@ function requireApiKey(opts, config) {
   return apiKey;
 }
 
+function assertSupportedReportType(reportType) {
+  const normalized = trimString(reportType);
+  if (SUPPORTED_EXPORT_REPORT_TYPES.includes(normalized)) {
+    return normalized;
+  }
+  throw new CliError(`Unsupported report type: ${reportType}`, {
+    code: 'INVALID_ARGUMENT',
+    exitCode: EXIT_CODES.USAGE,
+    hint: `Use one of: ${SUPPORTED_EXPORT_REPORT_TYPES.join(', ')}. Run \`socialseal data export-options\` to choose the right export flow.`,
+  });
+}
+
 function resolveApiTarget({ apiBase, legacyUrl }) {
   const resolvedApiBase = apiBase || (!legacyUrl ? DEFAULT_API_BASE : null);
   if (!resolvedApiBase && !legacyUrl) {
@@ -2197,14 +2418,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,
   });
@@ -2319,7 +2590,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.', {
@@ -2341,6 +2612,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,
@@ -2372,6 +2653,24 @@ async function handleDataExportTracking(opts) {
 }
 
 async function handleDataExportReport(opts) {
+  const reportType = assertSupportedReportType(opts.reportType);
+
+  if (reportType === REPORT_TYPE_SEARCH_RESULTS_ENRICHED) {
+    if (opts.format !== 'csv') {
+      throw new CliError('search_results_enriched supports only csv format.', {
+        code: 'INVALID_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+        hint: 'Use --format csv.',
+      });
+    }
+    const payload = ensureJsonObject(parseJsonInput(opts.payload, { label: 'payload' }), 'payload');
+    await handleDataExportSearchResults({
+      ...opts,
+      __rawPayload: payload,
+    });
+    return;
+  }
+
   const config = loadConfig();
   const apiKey = requireApiKey(opts, config);
   const apiBase = resolveApiBase(opts, config);
@@ -2388,7 +2687,7 @@ async function handleDataExportReport(opts) {
     path: useGateway ? '/cli/tools/export-report' : '/functions/v1/export-report',
     method: 'POST',
     body: {
-      reportType: opts.reportType,
+      reportType,
       format: opts.format,
       payload,
     },
@@ -2434,6 +2733,142 @@ async function handleDataExportReport(opts) {
   process.stdout.write(JSON.stringify(json, null, opts.pretty ? 2 : 0) + '\n');
 }
 
+async function handleDataExportSearchResults(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 rawPayload = opts.__rawPayload ?? stripUndefinedEntries({
+    groupIds: normalizePositiveIntegerList(opts.groupIds, 'groupIds', { max: 100 }),
+    trackingItemIds: normalizePositiveIntegerList(opts.trackingItemIds, 'trackingItemIds', { max: 1000 }),
+    dateFrom: opts.dateFrom,
+    dateTo: opts.dateTo,
+    filename: opts.filename,
+  });
+
+  const payloadWorkspaceId = resolvePayloadWorkspaceId(rawPayload, null);
+  const effectiveWorkspaceId = requireWorkspaceSelection(payloadWorkspaceId || resolvedWorkspaceId, {
+    label: 'Search results enriched export',
+    hint: 'Pass --workspace-id, set SOCIALSEAL_WORKSPACE_ID, or configure a default workspace before exporting.',
+  });
+  const effectiveWorkspaceSource = payloadWorkspaceId ? 'body' : workspaceSource;
+  emitWorkspaceSelectionNotice(opts, {
+    workspaceId: effectiveWorkspaceId,
+    source: effectiveWorkspaceSource,
+    label: 'search_results_enriched export',
+  });
+
+  const normalizedPayload = buildSearchResultsEnrichedExportPayload(rawPayload, effectiveWorkspaceId);
+  const requestedFilename = trimString(normalizedPayload.filename) || undefined;
+  delete normalizedPayload.filename;
+
+  const exportResponse = await callApi({
+    apiBase: useGateway ? resolvedApiBase : legacyUrl,
+    apiKey,
+    path: useGateway ? '/cli/tools/export-data' : '/functions/v1/export-data',
+    method: 'POST',
+    body: {
+      template: EXPORT_DATA_TEMPLATE_TRACKING_RANKED_VIDEOS_RAW,
+      format: 'csv',
+      payload: normalizedPayload,
+      filename: requestedFilename,
+    },
+    workspaceId: effectiveWorkspaceId,
+    timeoutMs,
+  });
+
+  if (!exportResponse.ok) {
+    throw await buildHttpError(exportResponse, {
+      label: 'Search results enriched export',
+      functionName: 'export-data',
+      method: 'POST',
+    });
+  }
+
+  const responseJson = await exportResponse.json();
+  const metadata = isJsonObject(responseJson) && isJsonObject(responseJson.metadata)
+    ? responseJson.metadata
+    : null;
+  const fileUrl = trimString(metadata?.file_url || '');
+  const status = trimString(metadata?.status || '').toLowerCase();
+
+  if (!fileUrl) {
+    if (status === 'processing') {
+      process.stderr.write('[socialseal] Export is still processing. Re-run the same command shortly; the backend dedupes and returns the finished artifact when ready.\n');
+    } else if (status === 'failed') {
+      process.stderr.write('[socialseal] Export status is failed. Inspect the JSON metadata for details, then retry with corrected filters.\n');
+    } else {
+      process.stderr.write('[socialseal] Export did not include a file URL yet. Inspect the JSON metadata and retry if needed.\n');
+    }
+    emitJsonOutput(responseJson, opts.pretty);
+    return;
+  }
+
+  const artifactResponse = await fetchWithTimeout(fileUrl, {
+    method: 'GET',
+    headers: { Accept: '*/*' },
+  }, timeoutMs);
+
+  if (!artifactResponse.ok) {
+    throw await buildHttpError(artifactResponse, {
+      label: 'Search results enriched artifact download',
+      method: 'GET',
+      hint: 'The signed file URL may be expired or inaccessible. Re-run the export command to mint a fresh URL.',
+    });
+  }
+
+  if (!artifactResponse.body) {
+    throw new CliError('Export artifact response contained no body.', {
+      code: 'EMPTY_RESPONSE',
+      exitCode: EXIT_CODES.SERVER,
+    });
+  }
+
+  const outPath = opts.stdout
+    ? null
+    : (opts.out || trimString(metadata?.filename || '') || 'tracking-ranked-videos.csv');
+  if (outPath) {
+    await pipeline(artifactResponse.body, fs.createWriteStream(outPath));
+    process.stderr.write(`[socialseal] Export written to ${outPath}\n`);
+  } else {
+    await pipeline(artifactResponse.body, process.stdout);
+  }
+}
+
+function handleDataExportOptions(opts) {
+  const payload = {
+    exports: EXPORT_OPTIONS,
+    supportedReportTypes: SUPPORTED_EXPORT_REPORT_TYPES,
+    note: 'Use this list to choose the right export surface before running data export commands.',
+  };
+
+  if (opts.json) {
+    emitJsonOutput(payload, opts.pretty);
+    return;
+  }
+
+  process.stdout.write('[socialseal] Available export options\n');
+  process.stdout.write('[socialseal] Choose a flow based on dataset shape, not endpoint name.\n\n');
+  for (const option of EXPORT_OPTIONS) {
+    process.stdout.write(`- ${option.id}: ${option.summary}\n`);
+    process.stdout.write(`  command: ${option.command}\n`);
+    process.stdout.write(`  formats: ${option.formats.join(', ')}\n`);
+    process.stdout.write(`  required: ${option.required.join(', ')}\n`);
+    process.stdout.write(`  best for: ${option.bestFor}\n`);
+    if (option.alias) {
+      process.stdout.write(`  alias: ${option.alias}\n`);
+    }
+    if (Array.isArray(option.reportTypes)) {
+      process.stdout.write(`  report types: ${option.reportTypes.join(', ')}\n`);
+    }
+    process.stdout.write('\n');
+  }
+}
+
 async function handleVideoExtract(opts) {
   const config = loadConfig();
   const apiKey = requireApiKey(opts, config);
@@ -2445,10 +2880,19 @@ async function handleVideoExtract(opts) {
 
   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: body.workspaceId || resolvedWorkspaceId,
-    source: body.workspaceId === resolvedWorkspaceId ? workspaceSource : 'body',
+    workspaceId: effectiveWorkspaceId,
+    source: effectiveWorkspaceSource,
     functionName: 'tracked-video-extract',
     method: 'POST',
   });
@@ -2460,7 +2904,7 @@ async function handleVideoExtract(opts) {
       path,
       method: 'POST',
       body,
-      workspaceId: body.workspaceId || resolvedWorkspaceId,
+      workspaceId: effectiveWorkspaceId,
       timeoutMs: remainingTimeoutMs,
     });
 
@@ -2523,11 +2967,20 @@ async function handleVideoQueueAnalysis(opts) {
   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: body.workspaceId || resolvedWorkspaceId,
-    source: body.workspaceId === resolvedWorkspaceId ? workspaceSource : 'body',
+    workspaceId: effectiveWorkspaceId,
+    source: effectiveWorkspaceSource,
     functionName: 'tracked-video-extract',
     method: 'POST',
   });
@@ -2539,7 +2992,7 @@ async function handleVideoQueueAnalysis(opts) {
       path,
       method: 'POST',
       body,
-      workspaceId: body.workspaceId || resolvedWorkspaceId,
+      workspaceId: effectiveWorkspaceId,
       timeoutMs: remainingTimeoutMs,
     });
 
@@ -2624,6 +3077,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');
   }
@@ -2668,6 +3123,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;
   }
 
@@ -2736,7 +3192,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);
@@ -2744,7 +3200,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 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.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-options\n  socialseal data export-tracking --group-id 123 --time-period 30d\n  socialseal data export-search-results --group-ids 123,124 --workspace-id <uuid> --out ranked.csv\n`);
 
 program
   .command('agent')
@@ -2836,6 +3292,14 @@ tools
 
 const data = program.command('data').description('Data exports (provisional)');
 
+data
+  .command('export-options')
+  .description('List export flows, when to use each, and required inputs')
+  .option('--json', 'Emit machine-readable output')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleDataExportOptions, opts));
+
 data
   .command('export-tracking')
   .description('Export tracking data as CSV')
@@ -2852,10 +3316,29 @@ data
   .option('--verbose', 'Show error details')
   .action((opts) => runCommand(handleDataExportTracking, opts));
 
+data
+  .command('export-search-results')
+  .description('Export enriched ranked search results (search_results + videos + latest metrics + analysis) as CSV')
+  .requiredOption('--group-ids <ids>', 'Comma-separated tracking group ids (for example: 123,124,125)')
+  .option('--tracking-item-ids <ids>', 'Optional comma-separated tracking item ids')
+  .option('--date-from <iso>', 'Optional ISO datetime lower bound (inclusive)')
+  .option('--date-to <iso>', 'Optional ISO datetime upper bound (inclusive)')
+  .option('--filename <name>', 'Optional export filename stem (without extension)')
+  .option('--out <path>', 'Output file path')
+  .option('--stdout', 'Write to stdout')
+  .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 metadata when no file is ready')
+  .option('--json', 'Emit machine-readable errors')
+  .option('--timeout <ms>', 'Request timeout in milliseconds')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleDataExportSearchResults, opts));
+
 data
   .command('export-report')
   .description('Export report data via export-report (provisional)')
-  .requiredOption('--report-type <type>', 'keyword_universe|cluster_insights|creator_signatures|post_publish|quick_audit')
+  .requiredOption('--report-type <type>', 'keyword_universe|cluster_insights|creator_signatures|post_publish|quick_audit|search_results_enriched')
   .option('--format <format>', 'csv|json|markdown|html|excel_data', 'csv')
   .requiredOption('--payload <jsonOrFile>', 'Payload JSON or @file.json')
   .option('--out <path>', 'Output file path')
@@ -2874,10 +3357,10 @@ const video = program.command('video').description('Tracked video extraction wor
 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('--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')
@@ -2893,10 +3376,10 @@ video
 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('--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')