felo-ai 0.2.24 → 0.2.28

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.25] - 2026-03-17
+
+### Added
+
+- **`felo livedoc download <id> <resource_id>`**: download a resource's source file directly to disk; follows the 302 redirect to the S3 presigned URL and streams the file; supports `--output <path>` to specify the destination filename (defaults to the filename from the `Content-Disposition` header)
+- **`felo livedoc content <id> <resource_id>`**: fetch the extracted text content of a resource; supported for document, web, video, ai_doc, ai_ppt, text, voice, and mindmap types
+- **`felo livedoc ppt-retrieve <id>`**: deep content retrieval from a specific PPT slide page; requires `--resource-id`, `--page-number`, and `--query`; supports `--max-chunk` (default 3); output format is identical to `retrieve`
+- **`add-urls` custom title support**: the API now accepts each URL entry as either a plain string or a `{"url": "...", "title": "..."}` object, allowing custom resource titles when adding URLs
+
+---
+
 ## [0.2.18] - 2026-03-14
 
 ### Added

package/felo-livedoc/SKILL.md

@@ -88,6 +88,8 @@ node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs add-doc SHORT_ID --ti
 node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs add-urls SHORT_ID --urls "https://example.com,https://example.org"
 ```
 
+Each URL can also be passed as a `url:title` pair using the `--url-titles` option, or by providing a JSON array. The API accepts both plain strings and `{"url": "...", "title": "..."}` objects — the script passes them through as-is when using `--json` mode. To add URLs with custom titles, use the JSON flag and construct the body manually, or rely on the auto-title from the page.
+
 **Upload a file:**
 ```bash
 node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs upload SHORT_ID --file ./document.pdf
@@ -126,6 +128,25 @@ node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs retrieve SHORT_ID --q
 ```bash
 node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs retrieve SHORT_ID --query "your search query" --resource-ids "id1,id2,id3"
 ```
+
+### Resource File & Content
+
+**Download resource source file (get presigned URL):**
+```bash
+node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs download SHORT_ID RESOURCE_ID
+node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs download SHORT_ID RESOURCE_ID --expires-in 7200
+```
+
+**Get extracted text content of a resource:**
+```bash
+node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs content SHORT_ID RESOURCE_ID
+```
+
+**PPT page deep retrieval:**
+```bash
+node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs ppt-retrieve SHORT_ID --resource-id RESOURCE_ID --page-number 3 --query "pricing information"
+node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs ppt-retrieve SHORT_ID --resource-id RESOURCE_ID --page-number 3 --query "pricing information" --max-chunk 5
+```
 ### Options
 
 All commands support:

package/felo-livedoc/scripts/run_livedoc.mjs

@@ -145,6 +145,9 @@ function usage() {
     '  remove-resource <short_id> <resource_id>  Delete a resource',
     '  retrieve <short_id>   Semantic search (--query required, --resource-ids optional)',
     '  route <short_id>      Route relevant resources by query (--query required)',
+    '  download <short_id> <resource_id>  Download source file to disk',
+    '  content <short_id> <resource_id>   Get text content of a resource',
+    '  ppt-retrieve <short_id>  PPT page deep retrieval (--resource-id, --page-number, --query required)',
     '',
     'Options:',
     '  --name <name>         LiveDoc name',
@@ -162,6 +165,11 @@ function usage() {
     '  --query <text>        Retrieval/route query',
     '  --resource-ids <ids>  Comma-separated resource IDs to search within (retrieve)',
     '  --max-resources <n>   Max resources to return (route)',
+    '  --resource-id <id>    PPT resource ID (ppt-retrieve)',
+    '  --page-number <n>     PPT page number, starts from 1 (ppt-retrieve)',
+    '  --max-chunk <n>       Max chunks to return (ppt-retrieve, default 3)',
+    '  --expires-in <s>      Presigned URL expiry in seconds (download, default 3600)',
+    '  --output <path>       Output file path (download, default: filename from response)',
     '  -j, --json            Output raw JSON',
     '  -t, --timeout <ms>    Timeout in ms (default: 60000)',
     '  --help                Show this help',
@@ -172,6 +180,7 @@ function parseArgs(argv) {
     action: '', positional: [], name: '', description: '', icon: '',
     keyword: '', page: '', size: '', type: '', content: '', title: '',
     urls: '', file: '', convert: false, query: '', resourceIds: '', maxResources: '',
+    resourceId: '', pageNumber: '', maxChunk: '', expiresIn: '',
     json: false, timeoutMs: DEFAULT_TIMEOUT_MS, help: false,
   };
   const positional = [];
@@ -194,6 +203,10 @@ function parseArgs(argv) {
     else if (a === '--query') out.query = argv[++i] || '';
     else if (a === '--resource-ids') out.resourceIds = argv[++i] || '';
     else if (a === '--max-resources') out.maxResources = argv[++i] || '';
+    else if (a === '--resource-id') out.resourceId = argv[++i] || '';
+    else if (a === '--page-number') out.pageNumber = argv[++i] || '';
+    else if (a === '--max-chunk') out.maxChunk = argv[++i] || '';
+    else if (a === '--expires-in') out.expiresIn = argv[++i] || '';
     else if (a === '-t' || a === '--timeout') {
       const n = parseInt(argv[++i] || '', 10);
       if (Number.isFinite(n) && n > 0) out.timeoutMs = n;
@@ -403,6 +416,79 @@ async function main() {
         code = 0;
         break;
       }
+      case 'download': {
+        if (!shortId) { console.error('ERROR: short_id is required'); break; }
+        if (!resourceId) { console.error('ERROR: resource_id is required'); break; }
+        spinnerId = startSpinner('Downloading resource');
+        const dlUrl = `${apiBase}/v2/livedocs/${shortId}/resources/${resourceId}/download${args.expiresIn ? `?expires_in=${args.expiresIn}` : ''}`;
+        const dlRes = await fetchWithRetry(dlUrl, { method: 'GET', headers: { Authorization: `Bearer ${apiKey}` }, redirect: 'follow' }, timeoutMs);
+        if (!dlRes.ok) {
+          let msg = dlRes.statusText;
+          try { const d = await dlRes.json(); msg = d?.message || d?.error || msg; } catch { /* ignore */ }
+          console.error(`ERROR: ${dlRes.status} ${msg}`);
+          break;
+        }
+        let filename = args.output;
+        if (!filename) {
+          const cd = dlRes.headers.get('content-disposition') || '';
+          const match = cd.match(/filename\*?=(?:UTF-8'')?["']?([^"';\r\n]+)/i);
+          filename = match ? decodeURIComponent(match[1].trim()) : resourceId;
+        }
+        const { createWriteStream } = await import('fs');
+        const writer = createWriteStream(filename);
+        const reader = dlRes.body.getReader();
+        await new Promise((resolve, reject) => {
+          writer.on('error', reject);
+          writer.on('finish', resolve);
+          const pump = async () => {
+            try {
+              while (true) {
+                const { done, value } = await reader.read();
+                if (done) { writer.end(); break; }
+                writer.write(value);
+              }
+            } catch (err) { reject(err); }
+          };
+          pump();
+        });
+        process.stdout.write(`Downloaded: ${filename}\n`);
+        code = 0;
+        break;
+      }
+      case 'content': {
+        if (!shortId) { console.error('ERROR: short_id is required'); break; }
+        if (!resourceId) { console.error('ERROR: resource_id is required'); break; }
+        spinnerId = startSpinner('Fetching resource content');
+        const payload = await apiRequest('GET', `/livedocs/${shortId}/resources/${resourceId}/content`, null, apiKey, apiBase, timeoutMs);
+        if (json) { console.log(JSON.stringify(payload, null, 2)); }
+        else {
+          const d = payload?.data;
+          process.stdout.write(`## ${d?.title || '(untitled)'}\n- Type: ${d?.type}\n\n${d?.content || '(empty)'}\n`);
+        }
+        code = 0;
+        break;
+      }
+      case 'ppt-retrieve': {
+        if (!shortId) { console.error('ERROR: short_id is required'); break; }
+        if (!args.resourceId) { console.error('ERROR: --resource-id is required'); break; }
+        if (!args.pageNumber) { console.error('ERROR: --page-number is required'); break; }
+        if (!args.query) { console.error('ERROR: --query is required'); break; }
+        spinnerId = startSpinner('Retrieving PPT page content');
+        const body = { resource_id: args.resourceId, page_number: parseInt(args.pageNumber, 10), query: args.query };
+        if (args.maxChunk) { const n = parseInt(args.maxChunk, 10); if (Number.isFinite(n) && n > 0) body.max_chunk = n; }
+        const payload = await apiRequest('POST', `/livedocs/${shortId}/resources/ppt-retrieve`, body, apiKey, apiBase, timeoutMs);
+        if (json) { console.log(JSON.stringify(payload, null, 2)); }
+        else {
+          const results = payload?.data || [];
+          if (!results.length) { process.stderr.write('No results found.\n'); }
+          else {
+            process.stdout.write(`Found ${results.length} result(s)\n\n`);
+            for (const r of results) process.stdout.write(formatRetrieveResult(r));
+          }
+        }
+        code = 0;
+        break;
+      }
       default:
         console.error(`Unknown action: ${action}`);
         usage();

package/felo-superAgent/SKILL.md

@@ -230,8 +230,7 @@ Examples:
 node felo-superAgent/scripts/run_superagent.mjs \
   --query "USER_QUERY_HERE" \
   --live-doc-id "LIVE_DOC_ID" \
-  --accept-language en \
-  --timeout 3600
+  --accept-language en
 ```
 
 **New conversation with skill ID (e.g., tweet writing):**
@@ -240,8 +239,7 @@ node felo-superAgent/scripts/run_superagent.mjs \
   --query "Write a tweet about the latest AI trends" \
   --live-doc-id "LIVE_DOC_ID" \
   --skill-id twitter-writer \
-  --accept-language en \
-  --timeout 3600
+  --accept-language en
 ```
 
 **Follow-up question (DEFAULT for 2nd+ messages):**
@@ -249,8 +247,7 @@ node felo-superAgent/scripts/run_superagent.mjs \
 node felo-superAgent/scripts/run_superagent.mjs \
   --query "USER_FOLLOW_UP_QUERY" \
   --thread-id "THREAD_SHORT_ID_FROM_PREVIOUS" \
-  --live-doc-id "LIVE_DOC_ID" \
-  --timeout 3600
+  --live-doc-id "LIVE_DOC_ID"
 ```
 
 ### Step 6: Extract State from stderr (Do NOT Re-output the Answer)
@@ -284,7 +281,7 @@ User: "What is quantum computing?"
 node felo-superAgent/scripts/run_superagent.mjs \
   --query "What is quantum computing?" \
   --live-doc-id "QPetunwpGnkKuZHStP7gwt" \
-  --accept-language en --timeout 3600
+  --accept-language en
 ```
 **Step 6:** The answer is already streamed to the user. Extract from stderr `[state]` line: `thread_short_id = "CmYpuGwBgCnrUdDx5ZtmxA"`, `live_doc_id = "QPetunwpGnkKuZHStP7gwt"`. Do NOT repeat the answer.
 
@@ -299,8 +296,7 @@ User: "What are its practical applications?"
 node felo-superAgent/scripts/run_superagent.mjs \
   --query "What are its practical applications?" \
   --thread-id "CmYpuGwBgCnrUdDx5ZtmxA" \
-  --live-doc-id "QPetunwpGnkKuZHStP7gwt" \
-  --timeout 3600
+  --live-doc-id "QPetunwpGnkKuZHStP7gwt"
 ```
 **Step 6:** Answer already streamed. Extract updated `thread_short_id` from stderr `[state]` line (may be the same), keep `live_doc_id`.
 
@@ -326,7 +322,7 @@ node felo-superAgent/scripts/run_superagent.mjs \
   --query "Help me write a tweet about AI trends" \
   --live-doc-id "QPetunwpGnkKuZHStP7gwt" \
   --skill-id twitter-writer \
-  --accept-language en --timeout 3600
+  --accept-language en
 ```
 **Step 6:** Answer already streamed. Extract new `thread_short_id` from stderr `[state]` line, keep same `live_doc_id`.
 
@@ -340,8 +336,7 @@ User: "Make it more casual and add some emojis"
 node felo-superAgent/scripts/run_superagent.mjs \
   --query "Make it more casual and add some emojis" \
   --thread-id "NEW_THREAD_FROM_TWEET" \
-  --live-doc-id "QPetunwpGnkKuZHStP7gwt" \
-  --timeout 3600
+  --live-doc-id "QPetunwpGnkKuZHStP7gwt"
 ```
 
 ### Example C: Logo Design
@@ -357,7 +352,7 @@ node felo-superAgent/scripts/run_superagent.mjs \
   --query "Design a logo for my coffee shop called Bean & Brew" \
   --live-doc-id "QPetunwpGnkKuZHStP7gwt" \
   --skill-id logo-and-branding \
-  --accept-language en --timeout 3600
+  --accept-language en
 ```
 
 ### Example D: E-commerce Product Image
@@ -373,7 +368,7 @@ node felo-superAgent/scripts/run_superagent.mjs \
   --query "Generate a product image for a wireless headphone on white background" \
   --live-doc-id "QPetunwpGnkKuZHStP7gwt" \
   --skill-id ecommerce-product-image \
-  --accept-language en --timeout 3600
+  --accept-language en
 ```
 
 ### Example E: User Requests a New Canvas
@@ -394,7 +389,6 @@ Extract new `live_doc_id`. Discard the old one. All subsequent calls use the new
 - `--query <text>` (REQUIRED) — User question, 1-2000 characters
 - `--live-doc-id <id>` (REQUIRED for new conversations) — LiveDoc ID (`live_doc_id`) to associate with
 - `--thread-id <id>` — Thread ID from previous response, for follow-up conversations
-- `--timeout <seconds>` — Request/stream timeout, default 3600 seconds
 
 **Skill parameters (new conversations only, ignored in follow-up):**
 - `--skill-id <id>` — Skill ID (see Constraint #8 for available skill IDs)
@@ -505,9 +499,8 @@ To use this skill, you need to set up your Felo API Key:
 
 ### Timeout Handling
 
-- Default timeout: 3600 seconds (recommended for all SuperAgent calls due to SSE streaming)
-- Idle timeout: 2 hours (no data received)
-- **Bash tool timeout:** MUST be set to at least 600000ms (10 minutes) when executing the script
+- The SSE stream has its own idle timeout: 2 hours (no data received). The stream stays open as long as data keeps flowing.
+- **Bash tool timeout:** MUST be set to at least 600000ms (10 minutes) when executing the script, because the SSE stream can run for a long time.
 
 ## Important Notes
 
@@ -561,3 +554,4 @@ Do NOT repeat or summarize the answer (already shown)
 - [SuperAgent API (Felo Open Platform)](https://openapi.felo.ai/docs/api-reference/v2/superagent.html)
 - [Felo Open Platform](https://openapi.felo.ai/docs/)
 - [Get API Key](https://felo.ai) (Settings -> API Keys)
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "felo-ai",
-  "version": "0.2.24",
+  "version": "0.2.28",
   "description": "Felo AI CLI - real-time search, PPT generation, SuperAgent conversation, LiveDoc management, web fetch, YouTube subtitles, LiveDoc knowledge base, and X (Twitter) search from the terminal",
   "type": "module",
   "main": "src/cli.js",
@@ -36,6 +36,6 @@
   },
   "scripts": {
     "test": "node --test tests/",
-    "publish": "npm publish"
+    "publish:local": "npm publish"
   }
 }

package/src/cli.js

@@ -674,6 +674,61 @@ livedocCmd
     flushStdioThenExit(code);
   });
 
+livedocCmd
+  .command("download <short_id> <resource_id>")
+  .description("Download a resource source file to disk")
+  .option("--output <path>", "output file path (default: filename from response)")
+  .option("--expires-in <seconds>", "presigned URL expiry in seconds (default 3600)")
+  .option("-t, --timeout <seconds>", "request timeout in seconds", "60")
+  .action(async (shortId, resourceId, opts) => {
+    const timeoutMs = parseInt(opts.timeout, 10) * 1000;
+    const code = await livedoc.downloadResource(shortId, resourceId, {
+      output: opts.output,
+      expiresIn: opts.expiresIn,
+      timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
+    });
+    process.exitCode = code;
+    flushStdioThenExit(code);
+  });
+
+livedocCmd
+  .command("content <short_id> <resource_id>")
+  .description("Get extracted text content of a resource")
+  .option("-j, --json", "output raw JSON")
+  .option("-t, --timeout <seconds>", "request timeout in seconds", "60")
+  .action(async (shortId, resourceId, opts) => {
+    const timeoutMs = parseInt(opts.timeout, 10) * 1000;
+    const code = await livedoc.getResourceContent(shortId, resourceId, {
+      json: opts.json,
+      timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
+    });
+    process.exitCode = code;
+    flushStdioThenExit(code);
+  });
+
+livedocCmd
+  .command("ppt-retrieve <short_id>")
+  .description("Deep content retrieval from a specific PPT page")
+  .requiredOption("--resource-id <id>", "PPT resource ID")
+  .requiredOption("--page-number <n>", "page number (starts from 1)")
+  .requiredOption("--query <query>", "retrieval query")
+  .option("--max-chunk <n>", "max chunks to return (default 3)")
+  .option("-j, --json", "output raw JSON")
+  .option("-t, --timeout <seconds>", "request timeout in seconds", "60")
+  .action(async (shortId, opts) => {
+    const timeoutMs = parseInt(opts.timeout, 10) * 1000;
+    const code = await livedoc.pptRetrieve(shortId, {
+      resourceId: opts.resourceId,
+      pageNumber: opts.pageNumber,
+      query: opts.query,
+      maxChunk: opts.maxChunk,
+      json: opts.json,
+      timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
+    });
+    process.exitCode = code;
+    flushStdioThenExit(code);
+  });
+
 program
   .command("summarize")
   .description("Summarize text or URL (coming when API is available)")

package/src/livedoc.js

@@ -432,3 +432,136 @@ export async function retrieve(shortId, opts = {}) {
     return 1;
   } finally { stopSpinner(spinnerId); }
 }
+
+export async function downloadResource(shortId, resourceId, opts = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
+  if (!shortId) { process.stderr.write('ERROR: short_id is required.\n'); return 1; }
+  if (!resourceId) { process.stderr.write('ERROR: resource_id is required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Downloading resource');
+
+  try {
+    const params = new URLSearchParams();
+    if (opts.expiresIn) params.set('expires_in', opts.expiresIn);
+    const qs = params.toString();
+    const url = `${apiBase}/v2/livedocs/${shortId}/resources/${resourceId}/download${qs ? `?${qs}` : ''}`;
+
+    // Follow redirects to get the actual file stream from S3
+    const res = await fetchWithTimeoutAndRetry(
+      url,
+      { method: 'GET', headers: { Authorization: `Bearer ${apiKey}` }, redirect: 'follow' },
+      timeoutMs,
+    );
+
+    if (!res.ok) {
+      let msg = res.statusText;
+      try { const d = await res.json(); msg = getMessage(d) || msg; } catch { /* ignore */ }
+      process.stderr.write(`ERROR: ${res.status} ${msg}\n`);
+      return 1;
+    }
+
+    // Determine output filename
+    let filename = opts.output;
+    if (!filename) {
+      // Try Content-Disposition header first
+      const cd = res.headers.get('content-disposition') || '';
+      const match = cd.match(/filename\*?=(?:UTF-8'')?["']?([^"';\r\n]+)/i);
+      if (match) {
+        filename = decodeURIComponent(match[1].trim());
+      } else {
+        // Fall back to resource_id as filename
+        filename = resourceId;
+      }
+    }
+
+    // Write file stream to disk
+    const { createWriteStream } = await import('fs');
+    const writer = createWriteStream(filename);
+    const reader = res.body.getReader();
+    await new Promise((resolve, reject) => {
+      writer.on('error', reject);
+      writer.on('finish', resolve);
+      const pump = async () => {
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) { writer.end(); break; }
+            writer.write(value);
+          }
+        } catch (err) { reject(err); }
+      };
+      pump();
+    });
+
+    stopSpinner(spinnerId);
+    process.stdout.write(`Downloaded: ${filename}\n`);
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to download resource: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
+export async function getResourceContent(shortId, resourceId, opts = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
+  if (!shortId) { process.stderr.write('ERROR: short_id is required.\n'); return 1; }
+  if (!resourceId) { process.stderr.write('ERROR: resource_id is required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Fetching resource content');
+
+  try {
+    const payload = await apiRequest('GET', `/livedocs/${shortId}/resources/${resourceId}/content`, null, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+    const d = payload?.data;
+    if (!d) { process.stderr.write('No content returned.\n'); return 0; }
+    process.stdout.write(`## ${d.title || '(untitled)'}\n`);
+    process.stdout.write(`- Type: ${d.type}\n\n`);
+    process.stdout.write(d.content || '(empty)');
+    process.stdout.write('\n');
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to get resource content: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
+export async function pptRetrieve(shortId, opts = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
+  if (!shortId) { process.stderr.write('ERROR: short_id is required.\n'); return 1; }
+  if (!opts.resourceId) { process.stderr.write('ERROR: --resource-id is required.\n'); return 1; }
+  if (!opts.pageNumber) { process.stderr.write('ERROR: --page-number is required.\n'); return 1; }
+  if (!opts.query) { process.stderr.write('ERROR: --query is required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Retrieving PPT page content');
+
+  try {
+    const body = {
+      resource_id: opts.resourceId,
+      page_number: parseInt(opts.pageNumber, 10),
+      query: opts.query,
+    };
+    if (opts.maxChunk) {
+      const n = parseInt(opts.maxChunk, 10);
+      if (Number.isFinite(n) && n > 0) body.max_chunk = n;
+    }
+    const payload = await apiRequest('POST', `/livedocs/${shortId}/resources/ppt-retrieve`, body, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+    const results = payload?.data || [];
+    if (!results.length) { process.stderr.write('No results found.\n'); return 0; }
+    process.stdout.write(`Found ${results.length} result(s)\n\n`);
+    for (const r of results) { process.stdout.write(formatRetrieveResult(r)); }
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to ppt-retrieve: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}