felo-ai 0.2.25 → 0.2.30

package/.claude-plugin/marketplace.json

@@ -0,0 +1,85 @@
+{
+  "name": "felo-ai",
+  "owner": {
+    "name": "Felo-Inc",
+    "url": "https://github.com/Felo-Inc"
+  },
+  "metadata": {
+    "description": "Felo AI skills for Claude Code — real-time search, PPT generation, SuperAgent, LiveDoc knowledge base, web fetch, YouTube subtitles, and X (Twitter) search",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "felo-search",
+      "description": "Real-time web search powered by Felo AI",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./felo-search"
+      ]
+    },
+    {
+      "name": "felo-livedoc",
+      "description": "Manage knowledge bases (LiveDocs) and semantic retrieval via Felo API",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./felo-livedoc"
+      ]
+    },
+    {
+      "name": "felo-slides",
+      "description": "Generate PPT presentations from a prompt using Felo AI",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./felo-slides"
+      ]
+    },
+    {
+      "name": "felo-superAgent",
+      "description": "SuperAgent conversation with SSE streaming and LiveDoc integration",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./felo-superAgent"
+      ]
+    },
+    {
+      "name": "felo-web-fetch",
+      "description": "Fetch and extract webpage content in markdown, text, or HTML format",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./felo-web-fetch"
+      ]
+    },
+    {
+      "name": "felo-youtube-subtitling",
+      "description": "Fetch YouTube video subtitles and captions by URL or video ID",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./felo-youtube-subtitling"
+      ]
+    },
+    {
+      "name": "felo-x-search",
+      "description": "Search X (Twitter) tweets, users, and replies via Felo API",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./felo-x-search"
+      ]
+    },
+    {
+      "name": "felo-content-to-slides",
+      "description": "Fetch content from a webpage or YouTube video and generate a PPT",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./felo-content-to-slides"
+      ]
+    }
+  ]
+}

package/CHANGELOG.md

@@ -5,7 +5,15 @@ 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.24] - 2026-03-17
+## [0.2.29] - 2026-03-18
+
+### Fixed
+
+- Fix spinner animation displaying repeated lines in non-TTY environments (e.g. Claude Code TUI, pipes, CI) by checking `process.stderr.isTTY` before writing `\r` control characters; spinner is silently skipped when stderr is not a TTY
+
+---
+
+## [0.2.25] - 2026-03-17
 
 ### Added
 

package/felo-content-to-slides/SKILL.md

@@ -56,6 +56,7 @@ felo content-to-slides -v "https://www.youtube.com/watch?v=ID" [options]
 | `-l, --language <code>` | For --video: subtitle language (e.g. en, zh-CN) |
 | `-t, --timeout <seconds>` | Fetch timeout (default 60) |
 | `--poll-timeout <seconds>` | Max seconds to wait for PPT task (default 1200) |
+| `--theme <id>` | PPT theme ID (list themes with `felo ppt-themes`) |
 | `-j, --json` | Output JSON with task_id and ppt/live_doc URL |
 | `--verbose` | Show polling status |
 
@@ -67,6 +68,9 @@ Provide **either** `--url` or `--video`, not both.
 # Web page → PPT (with readability)
 node src/cli.js content-to-slides --url "https://openclaw.ai/" --readability
 
+# Web page → PPT with a specific theme
+node src/cli.js content-to-slides --url "https://openclaw.ai/" --readability --theme "THEME_ID"
+
 # YouTube → PPT, with extra instruction
 node src/cli.js content-to-slides -v "https://www.youtube.com/watch?v=xxx" --extra-prompt "max 10 slides"
 

package/felo-livedoc/scripts/run_livedoc.mjs

@@ -12,6 +12,7 @@ const SPINNER_INTERVAL_MS = 80;
 const STATUS_PAD = 56;
 
 function startSpinner(message) {
+  if (!process.stderr.isTTY) return null;
   const start = Date.now();
   let i = 0;
   const id = setInterval(() => {
@@ -25,7 +26,7 @@ function startSpinner(message) {
 
 function stopSpinner(id) {
   if (id != null) clearInterval(id);
-  process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
+  if (process.stderr.isTTY) process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
 }
 
 function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }

package/felo-slides/SKILL.md

@@ -75,9 +75,22 @@ node felo-slides/scripts/run_ppt_task.mjs \
   --timeout 60
 ```
 
+To apply a specific theme, first list available themes with `felo ppt-themes`, then pass the theme ID:
+
+```bash
+node felo-slides/scripts/run_ppt_task.mjs \
+  --query "USER_PROMPT_HERE" \
+  --theme "THEME_ID_HERE" \
+  --interval 10 \
+  --max-wait 1800 \
+  --timeout 60
+```
+
 Script behavior:
 
 - Creates task via `POST https://openapi.felo.ai/v2/ppts`
+- Supports optional `--theme <id>` to apply a PPT theme (sends `ppt_config.ai_theme_id`)
+- Supports optional `--task-id <id>` to resume polling an existing task (skips creation)
 - Polls via `GET https://openapi.felo.ai/v2/tasks/{task_id}/historical`
 - Treats `COMPLETED`/`SUCCESS` as success terminal (case-insensitive)
 - Treats `FAILED`/`ERROR` as failure terminal
@@ -152,6 +165,14 @@ Timeout handling:
 
 - If timeout reached, return last known status and instruct user to retry later
 - Include `task_id` so user can query again
+- **IMPORTANT**: To resume a timed-out task, use `--task-id` instead of `--query` to avoid creating a duplicate PPT:
+
+```bash
+node felo-slides/scripts/run_ppt_task.mjs \
+  --task-id "TASK_ID_HERE" \
+  --interval 10 \
+  --max-wait 1800
+```
 
 ## Important Notes
 

package/felo-slides/scripts/run_ppt_task.mjs

@@ -12,7 +12,9 @@ function usage() {
       '  node felo-slides/scripts/run_ppt_task.mjs --query "your prompt" [options]',
       '',
       'Options:',
-      '  --query <text>        PPT prompt (required)',
+      '  --query <text>        PPT prompt (required unless --task-id is given)',
+      '  --task-id <id>        Resume polling an existing task (skip creation)',
+      '  --theme <id>          PPT theme ID (from ppt-themes)',
       '  --interval <seconds>  Poll interval, default 10',
       '  --max-wait <seconds>  Max wait time, default 1800',
       '  --timeout <seconds>   Request timeout, default 60',
@@ -26,6 +28,8 @@ function usage() {
 function parseArgs(argv) {
   const out = {
     query: '',
+    taskId: '',
+    theme: '',
     intervalSec: DEFAULT_INTERVAL_SEC,
     maxWaitSec: DEFAULT_MAX_WAIT_SEC,
     timeoutSec: DEFAULT_TIMEOUT_SEC,
@@ -44,6 +48,12 @@ function parseArgs(argv) {
     } else if (a === '--query') {
       out.query = argv[i + 1] ?? '';
       i += 1;
+    } else if (a === '--task-id') {
+      out.taskId = argv[i + 1] ?? '';
+      i += 1;
+    } else if (a === '--theme') {
+      out.theme = argv[i + 1] ?? '';
+      i += 1;
     } else if (a === '--interval') {
       out.intervalSec = Number.parseInt(argv[i + 1] ?? '', 10);
       i += 1;
@@ -128,7 +138,11 @@ function extractTaskUrls(historicalData, createData) {
   };
 }
 
-async function createTask(apiKey, apiBase, query, timeoutMs) {
+async function createTask(apiKey, apiBase, query, timeoutMs, theme) {
+  const reqBody = { query };
+  if (theme) {
+    reqBody.ppt_config = { ai_theme_id: theme };
+  }
   const payload = await fetchJson(
     `${apiBase}/v2/ppts`,
     {
@@ -138,7 +152,7 @@ async function createTask(apiKey, apiBase, query, timeoutMs) {
         Authorization: `Bearer ${apiKey}`,
         'Content-Type': 'application/json',
       },
-      body: JSON.stringify({ query }),
+      body: JSON.stringify(reqBody),
     },
     timeoutMs
   );
@@ -170,7 +184,7 @@ async function main() {
     usage();
     process.exit(0);
   }
-  if (!args.query) {
+  if (!args.query && !args.taskId) {
     usage();
     process.exit(1);
   }
@@ -186,10 +200,22 @@ async function main() {
   const intervalMs = args.intervalSec * 1000;
   const maxWaitMs = args.maxWaitSec * 1000;
 
-  const createData = await createTask(apiKey, apiBase, args.query, timeoutMs);
-  const taskId = createData.task_id;
-  if (args.verbose) {
-    console.error(`Task ID: ${taskId}`);
+  let createData = {};
+  let taskId;
+
+  if (args.taskId) {
+    // Resume polling an existing task
+    taskId = args.taskId;
+    if (args.verbose) {
+      console.error(`Resuming task: ${taskId}`);
+    }
+  } else {
+    // Create a new task
+    createData = await createTask(apiKey, apiBase, args.query, timeoutMs, args.theme);
+    taskId = createData.task_id;
+    if (args.verbose) {
+      console.error(`Task ID: ${taskId}`);
+    }
   }
 
   const startAt = Date.now();

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/felo-web-fetch/scripts/run_web_fetch.mjs

@@ -7,6 +7,7 @@ const SPINNER_INTERVAL_MS = 80;
 const STATUS_PAD = 56;
 
 function startSpinner(message) {
+  if (!process.stderr.isTTY) return null;
   const start = Date.now();
   let i = 0;
   const id = setInterval(() => {
@@ -20,7 +21,7 @@ function startSpinner(message) {
 
 function stopSpinner(id) {
   if (id != null) clearInterval(id);
-  process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
+  if (process.stderr.isTTY) process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
 }
 
 function usage() {

package/felo-x-search/scripts/run_x_search.mjs

@@ -9,6 +9,7 @@ const SPINNER_INTERVAL_MS = 80;
 const STATUS_PAD = 56;
 
 function startSpinner(message) {
+  if (!process.stderr.isTTY) return null;
   const start = Date.now();
   let i = 0;
   const id = setInterval(() => {
@@ -22,7 +23,7 @@ function startSpinner(message) {
 
 function stopSpinner(id) {
   if (id != null) clearInterval(id);
-  process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
+  if (process.stderr.isTTY) process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
 }
 
 function sleep(ms) {

package/felo-youtube-subtitling/scripts/run_youtube_subtitling.mjs

@@ -7,6 +7,7 @@ const SPINNER_INTERVAL_MS = 80;
 const STATUS_PAD = 52;
 
 function startSpinner(message) {
+  if (!process.stderr.isTTY) return null;
   const start = Date.now();
   let i = 0;
   const id = setInterval(() => {
@@ -20,7 +21,7 @@ function startSpinner(message) {
 
 function stopSpinner(id) {
   if (id != null) clearInterval(id);
-  process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
+  if (process.stderr.isTTY) process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
 }
 
 /** Extract video ID from YouTube URL or return string if plain ID. Returns null if invalid. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "felo-ai",
-  "version": "0.2.25",
+  "version": "0.2.30",
   "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",

package/src/cli.js

@@ -3,7 +3,7 @@
 import { createRequire } from "module";
 import { Command } from "commander";
 import { search } from "./search.js";
-import { slides } from "./slides.js";
+import { slides, listPptThemes } from "./slides.js";
 import { superAgent, listLiveDocs, listLiveDocResources } from "./superAgent.js";
 import { webFetch } from "./webFetch.js";
 import { youtubeSubtitling } from "./youtubeSubtitling.js";
@@ -71,7 +71,7 @@ program
     "Generate PPT/slides from a prompt (async task, outputs live doc URL when done)"
   )
   .argument(
-    "<query>",
+    "[query]",
     'PPT generation prompt (e.g. "Felo, 2 pages" or "Introduction to React")'
   )
   .option("-j, --json", "output raw JSON with task_id and live_doc_url")
@@ -86,14 +86,49 @@ program
     "max seconds to wait for task completion",
     "1200"
   )
+  .option("--theme <id>", "PPT theme ID (from ppt-themes command)")
+  .option("--task-id <id>", "resume polling an existing task (skip creation)")
   .action(async (query, opts) => {
+    if (!query && !opts.taskId) {
+      console.error("Error: provide a <query> or --task-id to resume an existing task");
+      flushStdioThenExit(1);
+      return;
+    }
     const timeoutMs = parseInt(opts.timeout, 10) * 1000;
     const pollTimeoutMs = parseInt(opts.pollTimeout, 10) * 1000 || 1_200_000;
-    const code = await slides(query, {
+    const pptConfig = opts.theme ? { ai_theme_id: opts.theme } : undefined;
+    const code = await slides(query || "", {
       json: opts.json,
       verbose: opts.verbose,
       timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
       pollTimeoutMs: Number.isNaN(pollTimeoutMs) ? 1_200_000 : pollTimeoutMs,
+      pptConfig,
+      taskId: opts.taskId,
+    });
+    process.exitCode = code;
+    flushStdioThenExit(code);
+  });
+
+program
+  .command("ppt-themes")
+  .description("List available PPT themes with optional filtering")
+  .option("--lang <code>", "language code (e.g. en, zh-Hans)")
+  .option("--type <type>", "filter by theme type (e.g. default, custom)")
+  .option("-k, --keyword <keyword>", "search keyword for theme titles")
+  .option("-p, --page <number>", "page number (starting from 1)", "1")
+  .option("-s, --size <number>", "page size (max 100)", "20")
+  .option("-j, --json", "output raw JSON")
+  .option("-t, --timeout <seconds>", "request timeout in seconds", "60")
+  .action(async (opts) => {
+    const timeoutMs = parseInt(opts.timeout, 10) * 1000;
+    const code = await listPptThemes({
+      lang: opts.lang,
+      type: opts.type,
+      keyword: opts.keyword,
+      page: parseInt(opts.page, 10) || 1,
+      size: parseInt(opts.size, 10) || 20,
+      json: opts.json,
+      timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
     });
     process.exitCode = code;
     flushStdioThenExit(code);
@@ -341,6 +376,7 @@ program
   )
   .option("-j, --json", "Output JSON with task_id and ppt/live_doc URL")
   .option("--verbose", "Show polling status")
+  .option("--theme <id>", "PPT theme ID (from ppt-themes command)")
   .action(async (opts) => {
     const timeoutMs = parseInt(opts.timeout, 10) * 1000;
     const pollTimeoutMs = parseInt(opts.pollTimeout, 10) * 1000;
@@ -354,6 +390,7 @@ program
       pollTimeoutMs: Number.isNaN(pollTimeoutMs) ? 1_200_000 : pollTimeoutMs,
       json: opts.json,
       verbose: opts.verbose,
+      theme: opts.theme,
     });
     process.exitCode = code;
     flushStdioThenExit(code);

package/src/contentToSlides.js

@@ -77,5 +77,6 @@ export async function contentToSlides(opts) {
     verbose: opts?.verbose,
     timeoutMs: fetchTimeoutMs,
     pollTimeoutMs: opts?.pollTimeoutMs,
+    pptConfig: opts?.theme ? { ai_theme_id: opts.theme } : undefined,
   });
 }

package/src/livedoc.js

@@ -12,6 +12,7 @@ const STATUS_PAD = 56;
 // ── Shared helpers ──
 
 function startSpinner(message) {
+  if (!process.stderr.isTTY) return null;
   const start = Date.now();
   let i = 0;
   const id = setInterval(() => {
@@ -25,7 +26,7 @@ function startSpinner(message) {
 
 function stopSpinner(id) {
   if (id != null) clearInterval(id);
-  process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
+  if (process.stderr.isTTY) process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
 }
 
 async function getApiBase() {

package/src/slides.js

@@ -48,9 +48,18 @@ function normalizeTaskStatus(status) {
 /**
  * Create a PPT task. Returns { task_id, livedoc_short_id, ppt_business_id } or throws.
  * Uses fetchWithTimeoutAndRetry for 5xx retry (per PPT Task API error codes).
+ * @param {string} apiKey
+ * @param {string} query
+ * @param {number} timeoutMs
+ * @param {string} apiBase
+ * @param {{ ai_theme_id?: string }} [pptConfig]
  */
-async function createPptTask(apiKey, query, timeoutMs, apiBase) {
+async function createPptTask(apiKey, query, timeoutMs, apiBase, pptConfig) {
   const url = `${apiBase}/v2/ppts`;
+  const body = { query: query.trim() };
+  if (pptConfig && Object.keys(pptConfig).length > 0) {
+    body.ppt_config = pptConfig;
+  }
   const res = await fetchWithTimeoutAndRetry(
     url,
     {
@@ -60,7 +69,7 @@ async function createPptTask(apiKey, query, timeoutMs, apiBase) {
         Authorization: `Bearer ${apiKey}`,
         "Content-Type": "application/json",
       },
-      body: JSON.stringify({ query: query.trim() }),
+      body: JSON.stringify(body),
     },
     timeoutMs
   );
@@ -150,18 +159,30 @@ export async function slides(query, options = {}) {
   try {
     const apiBase = await getApiBase();
 
-    process.stderr.write("Creating PPT task...\n");
+    let createResult = {};
+    let taskId;
 
-    const createResult = await createPptTask(
-      apiKey,
-      query,
-      requestTimeoutMs,
-      apiBase
-    );
-    const taskId = createResult.task_id;
+    if (options.taskId) {
+      // Resume polling an existing task
+      taskId = options.taskId;
+      if (options.verbose || options.json) {
+        process.stderr.write(`Resuming task: ${taskId}\n`);
+      }
+    } else {
+      process.stderr.write("Creating PPT task...\n");
+
+      createResult = await createPptTask(
+        apiKey,
+        query,
+        requestTimeoutMs,
+        apiBase,
+        options.pptConfig
+      );
+      taskId = createResult.task_id;
 
-    if (options.json && options.verbose) {
-      process.stderr.write(`Task ID: ${taskId}\n`);
+      if (options.json && options.verbose) {
+        process.stderr.write(`Task ID: ${taskId}\n`);
+      }
     }
 
     // 默认显示 spinner 动画；仅在使用 -v/--json 时改为逐行状态输出
@@ -330,3 +351,79 @@ export async function slides(query, options = {}) {
     return 1;
   }
 }
+
+/**
+ * List available PPT themes. Returns exit code (0 success, 1 failure).
+ * @param {Object} options - { lang?, type?, keyword?, page?, size?, json?, timeoutMs? }
+ */
+export async function listPptThemes(options = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) {
+    console.error(NO_KEY_MESSAGE.trim());
+    return 1;
+  }
+
+  const timeoutMs = options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+
+  try {
+    const apiBase = await getApiBase();
+    const params = new URLSearchParams();
+    if (options.lang) params.set("lang", options.lang);
+    if (options.type) params.set("type", options.type);
+    if (options.keyword) params.set("keyword", options.keyword);
+    if (options.page) params.set("page", String(options.page));
+    if (options.size) params.set("size", String(options.size));
+
+    const qs = params.toString();
+    const url = `${apiBase}/v2/ppt-themes${qs ? `?${qs}` : ""}`;
+
+    const res = await fetchWithTimeoutAndRetry(
+      url,
+      {
+        method: "GET",
+        headers: {
+          Accept: "application/json",
+          Authorization: `Bearer ${apiKey}`,
+        },
+      },
+      timeoutMs
+    );
+
+    const data = await res.json().catch(() => ({}));
+
+    if (data.status === "error") {
+      const msg = data.message || data.code || "Unknown error";
+      throw new Error(msg);
+    }
+
+    if (!res.ok) {
+      const msg =
+        data.message || data.error || res.statusText || `HTTP ${res.status}`;
+      throw new Error(msg);
+    }
+
+    const themes = data.data ?? [];
+
+    if (options.json) {
+      console.log(JSON.stringify(data, null, 2));
+      return 0;
+    }
+
+    if (!Array.isArray(themes) || themes.length === 0) {
+      console.log("No themes found.");
+      return 0;
+    }
+
+    for (const t of themes) {
+      console.log(`${t.id}  ${t.title || "(untitled)"}`);
+      if (t.subtitle) console.log(`  subtitle: ${t.subtitle}`);
+      if (t.description) console.log(`  ${t.description}`);
+      console.log();
+    }
+
+    return 0;
+  } catch (err) {
+    console.error("Error:", err.message || err);
+    return 1;
+  }
+}

package/src/webFetch.js

@@ -8,6 +8,7 @@ const SPINNER_INTERVAL_MS = 80;
 const STATUS_PAD = 56;
 
 function startSpinner(message) {
+  if (!process.stderr.isTTY) return null;
   const start = Date.now();
   let i = 0;
   const id = setInterval(() => {
@@ -21,7 +22,7 @@ function startSpinner(message) {
 
 function stopSpinner(id) {
   if (id != null) clearInterval(id);
-  process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
+  if (process.stderr.isTTY) process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
 }
 
 async function getApiBase() {

package/src/xSearch.js

@@ -8,6 +8,7 @@ const SPINNER_INTERVAL_MS = 80;
 const STATUS_PAD = 56;
 
 function startSpinner(message) {
+  if (!process.stderr.isTTY) return null;
   const start = Date.now();
   let i = 0;
   const id = setInterval(() => {
@@ -21,7 +22,7 @@ function startSpinner(message) {
 
 function stopSpinner(id) {
   if (id != null) clearInterval(id);
-  process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
+  if (process.stderr.isTTY) process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
 }
 
 async function getApiBase() {

package/src/youtubeSubtitling.js

@@ -8,6 +8,7 @@ const SPINNER_INTERVAL_MS = 80;
 const STATUS_PAD = 52;
 
 function startSpinner(message) {
+  if (!process.stderr.isTTY) return null;
   const start = Date.now();
   let i = 0;
   const id = setInterval(() => {
@@ -21,7 +22,7 @@ function startSpinner(message) {
 
 function stopSpinner(id) {
   if (id != null) clearInterval(id);
-  process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
+  if (process.stderr.isTTY) process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
 }
 
 /** Extract video ID from a YouTube URL or return the string if it looks like a plain ID. Returns null if invalid. */