@socialseal/cli 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -2,24 +2,37 @@
 
 ## Unreleased
 
+## 0.1.11 - 2026-06-12
+
+- Add ad hoc public video URL analysis parity for queue and extract workflows, including `--url` and `--allow-untracked` support.
+
+## 0.1.10 - 2026-06-10
+
+- Clarify ranked search exports now include publish/observed dates and scoped tracked-search resurfacing history fields when the backend export template is deployed.
+- Update `data export-options` metadata to distinguish search capture, metrics capture, platform publish, and SocialSeal observed-history timestamps.
+
 ## 0.1.9 - 2026-05-13
+
 - Fail `group-management add_items` on backend partial failures, expected-count mismatches, and failed backend verification.
 - Add `data export-group-evidence` to route social ranked evidence and Google AI evidence to the right raw export template with metadata.
 - Add `data group-completeness` with backend-first completeness checks, manifest fallback, and refresh status visibility.
 - Harden `tools status --wait` terminal failure handling and empty group refresh guardrails.
 
 ## 0.1.8 - 2026-04-13
+
 - Increase default CLI timeout from 30s to 5m to reduce false timeout failures on heavy tool/export workflows.
 - Harden async `search-journey-run` polling to accept additional active/terminal status labels (`queued`, `in_progress`, `running`, `succeeded`, `error`) instead of failing on unexpected variants.
 - Fix async `search-journey-run` polling workspace propagation to always reuse the resolved effective workspace scope.
 
 ## 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.
@@ -28,28 +41,34 @@
 - 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.
 - Return operational duplicate metadata for tracking conflicts, including `existing_item_id`, `member_of_group_ids`, platform, region, workspace, and active state.
 
 ## 0.1.3 - 2026-03-19
+
 - Republish the current CLI release line after the successful `0.1.2` npm publish, keeping the internal and OSS package versions aligned.
 
 ## 0.1.2 - 2026-03-18
+
 - Add `search-journey-run` async CLI ergonomics: `--async` starts the backend async mode, polling is on by default, and `--no-poll` returns the initial `runId` immediately.
 - Add `--poll-interval <ms>` for async `search-journey-run` status polling.
 - Treat terminal async `search-journey-run` failures as non-zero CLI exits instead of silent `200` JSON output.
 
 ## 0.1.1 - 2026-03-13
+
 - Document public base URL and CLI error output.
 - Add request timeouts, verbose error output, and OSS-safe tool discovery behavior.
 - Ship a stable built-in tool registry for `tools list` instead of the hard-disabled discovery message.
 - Fail fast on agent WebSocket `error` events and surface session/tool progress diagnostics in `--verbose` mode.
 
 ## 0.1.0
+
 - Initial CLI with agent streaming, tools calls, and provisional data exports.

package/README.md

@@ -1,12 +1,15 @@
 # SocialSeal CLI
 
 ## Setup
+
 - Requires Node 18+
 - Global install: `npm install -g @socialseal/cli`
 - Dev install: `npm install`
 
 ## Configuration
+
 Environment variables:
+
 - `SOCIALSEAL_API_KEY`
 - `SOCIALSEAL_API_BASE` (default `https://api.socialseal.co`)
 - `SOCIALSEAL_WORKSPACE_ID` (optional workspace override; takes precedence over config)
@@ -14,6 +17,7 @@ Environment variables:
 - `SOCIALSEAL_AGENT_IDLE_TIMEOUT_MS` (optional agent WebSocket inactivity timeout override; default 300000)
 
 Optional config file:
+
 - `~/.config/socialseal/config.json`
 
 ```json
@@ -27,6 +31,7 @@ Optional config file:
 ```
 
 ## Commands
+
 - Workspace discovery/defaults:
   - `socialseal workspace list`
   - `socialseal workspace current`
@@ -68,10 +73,17 @@ Optional config file:
   - `socialseal data export-report --report-type keyword_universe --format csv --payload @payload.json --out out.csv`
 
 ## Notes
+
 - `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.
 - `tools schema --function <name>` prints static required/optional payload fields and example bodies for high-friction tools.
-- `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-search-results` maps to `export-data` template `tracking_ranked_videos_raw` and returns enriched ranked-search rows (search fields + video metadata + publish/observed dates + latest metrics + scoped tracked-search history + analysis). It downloads the signed CSV artifact when available.
+- Timestamp meanings in ranked search exports:
+  - `search_timestamp`: when SocialSeal captured that ranked search row.
+  - `latest_metrics_ts`: when the latest exported engagement metrics snapshot was captured.
+  - `published_at`: platform publish/upload time when available from the video record; blank if unavailable.
+  - `observed_at`: when SocialSeal first observed/ingested the video record when available; blank if unavailable.
+  - `first_seen_at` / `last_seen_at`: earliest/latest `search_timestamp` for the video within the exported tracking-group/search-row scope. Use these for “resurfacing in tracked search” language, not platform-age claims when `published_at` is absent.
 - `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.
@@ -91,11 +103,13 @@ Optional config file:
 - 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
+
 - Exit codes: `2` (usage), `3` (auth), `4` (not found), `5` (server), `1` (unknown)
 - Add `--json` to `tools call` or `data` commands to emit machine-readable errors.
 - Add `--verbose` to print error details plus agent session/tool progress diagnostics.
 
 ## Troubleshooting
+
 - `SUPABASE_ANON_KEY not configured`
   - This comes from the CLI gateway, not the local CLI install.
   - The deployed gateway is missing its `SUPABASE_ANON_KEY` secret, so `/cli/tools/*` cannot proxy to Supabase Edge Functions.
@@ -106,8 +120,10 @@ Optional config file:
   - If this reproduces from a supported Google AI region, treat it as an infrastructure/runtime issue. Practical workarounds are to run the agent from a worker placement/egress region that Google accepts, or switch the agent runtime to Vertex AI for server-side calls.
 
 ## Smoke Test (manual)
+
 1. `SOCIALSEAL_API_KEY=... socialseal agent run --message "ping"`
 2. `SOCIALSEAL_API_KEY=... socialseal tools call --function <tool> --body @payload.json`
 
 ## Maintainers
+
 - The public CLI base (`api.socialseal.co`) must route to the CLI gateway service.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socialseal/cli",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "private": false,
   "type": "module",
   "description": "SocialSeal CLI (non-interactive)",
@@ -13,7 +13,7 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/OpenSealAI/socialseal-cli.git"
+    "url": "git+https://github.com/OpenSealAI/socialseal-cli.git"
   },
   "bugs": {
     "url": "https://github.com/OpenSealAI/socialseal-cli/issues"

package/src/index.js

@@ -55,10 +55,10 @@ const EXPORT_OPTIONS = [
   {
     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).',
+    summary: 'Enriched ranked search rows (search capture + video publish/observed dates + latest metrics + scoped resurfacing history + analysis).',
     formats: ['csv'],
     required: ['workspace id', '--group-ids'],
-    bestFor: 'SQL-like ranked-search datasets without using psql.',
+    bestFor: 'SQL-like ranked-search datasets and deck evidence that must distinguish capture, metrics, publish, and tracked-search resurfacing timestamps.',
     alias: 'socialseal data export-report --report-type search_results_enriched --format csv --payload @payload.json',
   },
   {
@@ -124,7 +124,7 @@ const KNOWN_TOOLS = [
     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.',
+    notes: 'Includes template `tracking_ranked_videos_raw` for ranked search results with video publish/observed dates, latest metrics, scoped first/last seen, and analysis enrichment.',
   },
   {
     name: 'export_tracking_data',
@@ -144,7 +144,7 @@ const KNOWN_TOOLS = [
     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.',
+    notes: 'Accepts videoId/videoUid/platformVideoId/searchResultId items and public URL items with allowUntracked=true; 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.' },
   {
@@ -258,6 +258,23 @@ const TOOL_SCHEMA_HINTS = {
           jobId: '11111111-1111-4111-8111-111111111111',
         },
       },
+      {
+        action: 'status',
+        required: ['action=status', 'workspaceId or --workspace-id', 'items[] with videoUid or platformVideoId'],
+        optional: ['includeRawAnalysis'],
+        notes: 'Status polling is read-only and does not accept URL items; use videoUid or platformVideoId returned by the initial URL extraction response.',
+        example: {
+          action: 'status',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          items: [
+            {
+              videoUid: '11111111-1111-4111-8111-111111111111',
+            },
+          ],
+          includeAssets: false,
+          includeSourceVideo: false,
+        },
+      },
     ],
     cliExamples: [
       'socialseal tools call --function agent-tool-jobs --body \'{"action":"start","toolName":"search_videos","payload":{"query":"best africa safari itinerary","platform":"tiktok","region":"IN"}}\'',
@@ -376,6 +393,64 @@ const TOOL_SCHEMA_HINTS = {
       'socialseal tools call --function get-google-ai-search-results --body \'{"runId":6809,"includeCitations":true,"limit":10}\'',
     ],
   },
+  'tracked-video-extract': {
+    summary: 'Extract assets and queue/read analysis for tracked identifiers or ad hoc public video URLs.',
+    operations: [
+      {
+        action: 'extract',
+        required: ['workspaceId or --workspace-id', 'items[] with exactly one selector'],
+        optional: [
+          'items[].searchResultId',
+          'items[].videoId',
+          'items[].videoUid',
+          'items[].platformVideoId',
+          'items[].url',
+          'allowUntracked',
+          'ensureAnalysis',
+          'includeAssets',
+          'includeSourceVideo',
+          'frameStrategy',
+          'frameCount',
+          'signedUrlSeconds',
+        ],
+        notes: 'URL items require request-level allowUntracked:true. Supported selectors are url, searchResultId, videoId, videoUid, or platformVideoId.',
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          allowUntracked: true,
+          ensureAnalysis: true,
+          items: [
+            {
+              url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
+            },
+          ],
+        },
+      },
+      {
+        action: 'queue-analysis',
+        required: ['workspaceId or --workspace-id', 'items[] with exactly one selector'],
+        optional: ['allowUntracked for URL items', 'queueOnly', 'includeRawAnalysis'],
+        notes: 'Set ensureAnalysis:true and queueOnly:true to enqueue analysis without asset URL generation.',
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          allowUntracked: true,
+          ensureAnalysis: true,
+          queueOnly: true,
+          includeAssets: false,
+          items: [
+            {
+              url: 'https://www.tiktok.com/@creator/video/7348293840000000000',
+            },
+          ],
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal video extract --url https://www.youtube.com/watch?v=dQw4w9WgXcQ --allow-untracked --wait --out-dir ./video-assets --workspace-id <workspace-uuid>',
+      'socialseal video queue-analysis --url https://www.tiktok.com/@creator/video/7348293840000000000 --allow-untracked --wait --workspace-id <workspace-uuid>',
+      'socialseal video extract --video-uid <video-uuid> --wait --workspace-id <workspace-uuid>',
+      'socialseal tools call --function tracked-video-extract --workspace-id <workspace-uuid> --body \'{"allowUntracked":true,"items":[{"url":"https://www.instagram.com/reel/SHORTCODE/"}]}\'',
+    ],
+  },
   'group-management': {
     summary: 'Manage single-platform tracking groups and memberships.',
     operations: [
@@ -751,6 +826,7 @@ function inferExtension(urlValue, contentType, fallback = '.bin') {
 function normalizeVideoExtractBody(body) {
   const normalized = { ...body };
   const hasInlineIdentifier =
+    normalized.url !== undefined ||
     normalized.videoId !== undefined ||
     normalized.searchResultId !== undefined ||
     normalized.videoUid !== undefined ||
@@ -758,12 +834,14 @@ function normalizeVideoExtractBody(body) {
 
   if (!Array.isArray(normalized.items) && hasInlineIdentifier) {
     normalized.items = [{
+      url: normalized.url,
       videoId: normalized.videoId,
       searchResultId: normalized.searchResultId,
       videoUid: normalized.videoUid,
       platformVideoId: normalized.platformVideoId,
       platformId: normalized.platformId,
     }];
+    delete normalized.url;
     delete normalized.videoId;
     delete normalized.searchResultId;
     delete normalized.videoUid;
@@ -774,6 +852,11 @@ function normalizeVideoExtractBody(body) {
   return normalized;
 }
 
+function hasUrlVideoItems(body) {
+  const items = Array.isArray(body?.items) ? body.items : [];
+  return items.some((item) => typeof item?.url === 'string' && item.url.trim().length > 0);
+}
+
 function buildVideoExtractBody(opts, workspaceId) {
   const parsed = opts.body
     ? ensureJsonObject(parseJsonInput(opts.body, { label: 'body' }), 'body')
@@ -782,6 +865,7 @@ function buildVideoExtractBody(opts, workspaceId) {
 
   if (!Array.isArray(normalized.items) || normalized.items.length === 0) {
     const inlineItem = stripUndefinedEntries({
+      url: trimString(opts.url) || undefined,
       videoId: trimString(opts.videoId) || undefined,
       searchResultId: opts.searchResultId !== undefined
         ? coercePositiveInteger(opts.searchResultId, 'searchResultId')
@@ -791,10 +875,10 @@ function buildVideoExtractBody(opts, workspaceId) {
     });
 
     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.', {
+      throw new CliError('Provide --body or one of --url, --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.',
+        hint: '--url requires --allow-untracked. --video-id accepts a video_uid or platform video id; it does not accept tracking item ids.',
       });
     }
 
@@ -811,6 +895,17 @@ function buildVideoExtractBody(opts, workspaceId) {
   }
 
   const nextBody = { ...bodyWithWorkspace };
+  if (opts.allowUntracked === true) {
+    nextBody.allowUntracked = true;
+  }
+  if (hasUrlVideoItems(nextBody) && nextBody.allowUntracked !== true) {
+    throw new CliError('URL video analysis requires --allow-untracked or allowUntracked:true in --body.', {
+      code: 'ALLOW_UNTRACKED_REQUIRED',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Pass --allow-untracked for ad hoc public URL analysis. Existing tracked identifier flows do not need this flag.',
+    });
+  }
+
   if (opts.wait) {
     nextBody.ensureAnalysis = true;
   } else if (opts.ensureAnalysis === true) {
@@ -868,11 +963,60 @@ function buildVideoQueueBody(opts, workspaceId) {
 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';
+    const itemStatus = String(result?.status || '').trim().toLowerCase();
+    const analysisStatus = String(
+      result?.analysis?.normalizedStatus || result?.analysis?.status || '',
+    ).trim().toLowerCase();
+    const status = itemStatus || analysisStatus;
+    return ACTIVE_STATUS_VALUES.has(status);
   });
 }
 
+function buildVideoExtractStatusPollBody(originalBody, payload) {
+  const results = Array.isArray(payload?.results) ? payload.results : [];
+  const items = results
+    .map((result) => {
+      const resolved = isJsonObject(result?.resolvedVideo)
+        ? result.resolvedVideo
+        : (isJsonObject(result?.resolved) ? result.resolved : {});
+      const videoUid = trimString(resolved.videoUid || resolved.video_uid);
+      if (videoUid) return { videoUid };
+      const platformVideoId = trimString(
+        resolved.platformVideoId || resolved.platform_video_id,
+      );
+      if (platformVideoId) {
+        const item = { platformVideoId };
+        if (Number.isInteger(resolved.platformId)) {
+          item.platformId = resolved.platformId;
+        } else if (Number.isInteger(resolved.platform_id)) {
+          item.platformId = resolved.platform_id;
+        }
+        return item;
+      }
+      const request = isJsonObject(result?.request) ? result.request : null;
+      if (!request || request.url) return null;
+      return request;
+    })
+    .filter(Boolean);
+
+  if (items.length === 0) {
+    const originalHasUrl = Array.isArray(originalBody.items) &&
+      originalBody.items.some((item) => Boolean(item?.url));
+    if (originalHasUrl) return null;
+    return originalBody;
+  }
+
+  return {
+    workspaceId: originalBody.workspaceId,
+    action: 'status',
+    items,
+    includeRawAnalysis: originalBody.includeRawAnalysis === true,
+    includeAssets: false,
+    includeSourceVideo: false,
+    ensureAnalysis: false,
+  };
+}
+
 async function downloadAssetToFile({ url, outDir, stem, timeoutMs }) {
   const response = await fetchWithTimeout(url, {
     method: 'GET',
@@ -4448,13 +4592,13 @@ async function handleVideoExtract(opts) {
     method: 'POST',
   });
 
-  const requestOnce = async (remainingTimeoutMs) => {
+  const requestOnce = async (remainingTimeoutMs, requestBody = body) => {
     const res = await callApi({
       apiBase: useGateway ? resolvedApiBase : legacyUrl,
       apiKey,
       path,
       method: 'POST',
-      body,
+      body: requestBody,
       workspaceId: effectiveWorkspaceId,
       timeoutMs: remainingTimeoutMs,
     });
@@ -4479,6 +4623,7 @@ async function handleVideoExtract(opts) {
   };
 
   let payload = await requestOnce(timeoutMs);
+  let pollBody = buildVideoExtractStatusPollBody(body, payload);
 
   if (opts.wait) {
     const pollIntervalMs = resolvePollIntervalMs(opts);
@@ -4497,7 +4642,16 @@ async function handleVideoExtract(opts) {
 
       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 (!pollBody) {
+        throw new CliError('Cannot poll URL analysis without a resolved video identifier.', {
+          code: 'MISSING_RESOLVED_VIDEO_ID',
+          exitCode: EXIT_CODES.SERVER,
+          hint: 'Retry without --wait, then poll with the returned videoUid or platformVideoId.',
+          details: truncateDetails(payload),
+        });
+      }
+      payload = await requestOnce(Math.max(1000, deadline - Date.now()), pollBody);
+      pollBody = buildVideoExtractStatusPollBody(body, payload);
     }
   }
 
@@ -4536,13 +4690,13 @@ async function handleVideoQueueAnalysis(opts) {
     method: 'POST',
   });
 
-  const requestOnce = async (remainingTimeoutMs) => {
+  const requestOnce = async (remainingTimeoutMs, requestBody = body) => {
     const res = await callApi({
       apiBase: useGateway ? resolvedApiBase : legacyUrl,
       apiKey,
       path,
       method: 'POST',
-      body,
+      body: requestBody,
       workspaceId: effectiveWorkspaceId,
       timeoutMs: remainingTimeoutMs,
     });
@@ -4567,6 +4721,7 @@ async function handleVideoQueueAnalysis(opts) {
   };
 
   let payload = await requestOnce(timeoutMs);
+  let pollBody = buildVideoExtractStatusPollBody(body, payload);
 
   if (opts.wait) {
     const pollIntervalMs = resolvePollIntervalMs(opts);
@@ -4585,7 +4740,16 @@ async function handleVideoQueueAnalysis(opts) {
 
       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()));
+      if (!pollBody) {
+        throw new CliError('Cannot poll URL analysis without a resolved video identifier.', {
+          code: 'MISSING_RESOLVED_VIDEO_ID',
+          exitCode: EXIT_CODES.SERVER,
+          hint: 'Retry without --wait, then poll with the returned videoUid or platformVideoId.',
+          details: truncateDetails(payload),
+        });
+      }
+      payload = await requestOnce(Math.max(1000, deadline - Date.now()), pollBody);
+      pollBody = buildVideoExtractStatusPollBody(body, payload);
     }
   }
 
@@ -4967,12 +5131,14 @@ 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')
+  .description('Queue video analysis for tracked videos, tracked search results, or ad hoc public URLs')
+  .option('--url <url>', 'Public TikTok, Instagram, or YouTube video URL (requires --allow-untracked)')
   .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('--allow-untracked', 'Allow ad hoc public URL analysis for videos not already tracked')
   .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)')
@@ -4986,12 +5152,14 @@ video
 
 video
   .command('extract')
-  .description('Resolve tracked videos/results into structured analysis plus reference assets')
+  .description('Resolve tracked videos/results or ad hoc public URLs into structured analysis plus reference assets')
+  .option('--url <url>', 'Public TikTok, Instagram, or YouTube video URL (requires --allow-untracked)')
   .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('--allow-untracked', 'Allow ad hoc public URL analysis for videos not already tracked')
   .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')