felo-ai 0.2.12 → 0.2.14

package/src/cli.js

@@ -8,6 +8,7 @@ import { superAgent } from "./superAgent.js";
 import { webFetch } from "./webFetch.js";
 import { youtubeSubtitling } from "./youtubeSubtitling.js";
 import * as xSearch from "./xSearch.js";
+import * as livedoc from "./livedoc.js";
 import * as config from "./config.js";
 
 const require = createRequire(import.meta.url);
@@ -349,6 +350,210 @@ program
     flushStdioThenExit(code);
   });
 
+// ── LiveDoc ──
+const livedocCmd = program
+  .command("livedoc")
+  .description("Manage Felo LiveDocs (knowledge bases) and resources");
+
+livedocCmd
+  .command("create")
+  .description("Create a new LiveDoc")
+  .requiredOption("--name <name>", "LiveDoc name")
+  .option("--description <desc>", "LiveDoc description")
+  .option("--icon <icon>", "LiveDoc icon")
+  .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 livedoc.createLiveDoc({
+      name: opts.name,
+      description: opts.description,
+      icon: opts.icon,
+      json: opts.json,
+      timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
+    });
+    process.exitCode = code;
+    flushStdioThenExit(code);
+  });
+
+livedocCmd
+  .command("list")
+  .description("List LiveDocs")
+  .option("--keyword <kw>", "search keyword")
+  .option("--page <n>", "page number")
+  .option("--size <n>", "page size")
+  .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 livedoc.listLiveDocs({
+      keyword: opts.keyword,
+      page: opts.page,
+      size: opts.size,
+      json: opts.json,
+      timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
+    });
+    process.exitCode = code;
+    flushStdioThenExit(code);
+  });
+
+livedocCmd
+  .command("update <short_id>")
+  .description("Update a LiveDoc")
+  .option("--name <name>", "new name")
+  .option("--description <desc>", "new description")
+  .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.updateLiveDoc(shortId, {
+      name: opts.name,
+      description: opts.description,
+      json: opts.json,
+      timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
+    });
+    process.exitCode = code;
+    flushStdioThenExit(code);
+  });
+
+livedocCmd
+  .command("delete <short_id>")
+  .description("Delete a LiveDoc")
+  .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.deleteLiveDoc(shortId, {
+      json: opts.json,
+      timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
+    });
+    process.exitCode = code;
+    flushStdioThenExit(code);
+  });
+
+livedocCmd
+  .command("resources <short_id>")
+  .description("List resources in a LiveDoc")
+  .option("--type <type>", "filter by resource type")
+  .option("--page <n>", "page number")
+  .option("--size <n>", "page size")
+  .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.listResources(shortId, {
+      type: opts.type,
+      page: opts.page,
+      size: opts.size,
+      json: opts.json,
+      timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
+    });
+    process.exitCode = code;
+    flushStdioThenExit(code);
+  });
+
+livedocCmd
+  .command("resource <short_id> <resource_id>")
+  .description("Get a single 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.getResource(shortId, resourceId, {
+      json: opts.json,
+      timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
+    });
+    process.exitCode = code;
+    flushStdioThenExit(code);
+  });
+
+livedocCmd
+  .command("add-doc <short_id>")
+  .description("Create a text document resource")
+  .requiredOption("--content <content>", "document content")
+  .option("--title <title>", "document title")
+  .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.addDoc(shortId, {
+      content: opts.content,
+      title: opts.title,
+      json: opts.json,
+      timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
+    });
+    process.exitCode = code;
+    flushStdioThenExit(code);
+  });
+
+livedocCmd
+  .command("add-urls <short_id>")
+  .description("Add URL resources (max 10, comma-separated)")
+  .requiredOption("--urls <urls>", "comma-separated URLs")
+  .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.addUrls(shortId, {
+      urls: opts.urls,
+      json: opts.json,
+      timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
+    });
+    process.exitCode = code;
+    flushStdioThenExit(code);
+  });
+
+livedocCmd
+  .command("upload <short_id>")
+  .description("Upload a file as resource")
+  .requiredOption("--file <path>", "file path to upload")
+  .option("--convert", "convert file to document (use upload-doc endpoint)")
+  .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.uploadFile(shortId, {
+      file: opts.file,
+      convert: opts.convert,
+      json: opts.json,
+      timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
+    });
+    process.exitCode = code;
+    flushStdioThenExit(code);
+  });
+
+livedocCmd
+  .command("remove-resource <short_id> <resource_id>")
+  .description("Delete 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.removeResource(shortId, resourceId, {
+      json: opts.json,
+      timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
+    });
+    process.exitCode = code;
+    flushStdioThenExit(code);
+  });
+
+livedocCmd
+  .command("retrieve <short_id>")
+  .description("Semantic search across resources")
+  .requiredOption("--query <query>", "search query")
+  .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.retrieve(shortId, {
+      query: opts.query,
+      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

@@ -0,0 +1,401 @@
+import { getApiKey, fetchWithTimeoutAndRetry, NO_KEY_MESSAGE } from './search.js';
+import * as config from './config.js';
+import fs from 'fs/promises';
+import path from 'path';
+
+const DEFAULT_API_BASE = 'https://openapi.felo.ai';
+const DEFAULT_TIMEOUT_MS = 60_000;
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const SPINNER_INTERVAL_MS = 80;
+const STATUS_PAD = 56;
+
+// ── Shared helpers ──
+
+function startSpinner(message) {
+  const start = Date.now();
+  let i = 0;
+  const id = setInterval(() => {
+    const elapsed = Math.floor((Date.now() - start) / 1000);
+    const line = `${message} ${SPINNER_FRAMES[i % SPINNER_FRAMES.length]} ${elapsed}s`;
+    process.stderr.write(`\r${line.padEnd(STATUS_PAD, ' ')}`);
+    i += 1;
+  }, SPINNER_INTERVAL_MS);
+  return id;
+}
+
+function stopSpinner(id) {
+  if (id != null) clearInterval(id);
+  process.stderr.write(`\r${' '.repeat(STATUS_PAD)}\r`);
+}
+
+async function getApiBase() {
+  let base = process.env.FELO_API_BASE?.trim();
+  if (!base) {
+    const v = await config.getConfigValue('FELO_API_BASE');
+    base = typeof v === 'string' ? v.trim() : '';
+  }
+  return (base || DEFAULT_API_BASE).replace(/\/$/, '');
+}
+
+function getMessage(payload) {
+  return payload?.message || payload?.error || payload?.msg || payload?.code || 'Unknown error';
+}
+
+async function apiRequest(method, apiPath, body, apiKey, apiBase, timeoutMs) {
+  const url = `${apiBase}/v2${apiPath}`;
+  const headers = {
+    Accept: 'application/json',
+    Authorization: `Bearer ${apiKey}`,
+  };
+  const init = { method, headers };
+
+  if (body !== undefined && body !== null) {
+    headers['Content-Type'] = 'application/json';
+    init.body = JSON.stringify(body);
+  }
+  const res = await fetchWithTimeoutAndRetry(url, init, timeoutMs);
+  let data = {};
+  try { data = await res.json(); } catch { data = {}; }
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${getMessage(data)}`);
+  if (data.status === 'error') throw new Error(getMessage(data));
+  return data;
+}
+
+async function uploadFormData(apiPath, formData, apiKey, apiBase, timeoutMs) {
+  const url = `${apiBase}/v2${apiPath}`;
+  const res = await fetchWithTimeoutAndRetry(
+    url,
+    {
+      method: 'POST',
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: formData,
+    },
+    timeoutMs,
+  );
+  let data = {};
+  try { data = await res.json(); } catch { data = {}; }
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${getMessage(data)}`);
+  if (data.status === 'error') throw new Error(getMessage(data));
+  return data;
+}
+
+// ── Formatting helpers ──
+
+function formatLiveDoc(doc) {
+  if (!doc) return '';
+  let out = `## ${doc.name || '(untitled)'}\n`;
+  out += `- ID: \`${doc.short_id}\`\n`;
+  if (doc.description) out += `- Description: ${doc.description}\n`;
+  if (doc.icon) out += `- Icon: ${doc.icon}\n`;
+  if (doc.created_at) out += `- Created: ${doc.created_at}\n`;
+  if (doc.modified_at) out += `- Modified: ${doc.modified_at}\n`;
+  out += '\n';
+  return out;
+}
+function formatResource(res) {
+  if (!res) return '';
+  let out = `### ${res.title || '(untitled)'}\n`;
+  out += `- Resource ID: \`${res.id}\`\n`;
+  if (res.resource_type) out += `- Type: ${res.resource_type}\n`;
+  if (res.status) out += `- Status: ${res.status}\n`;
+  if (res.source) out += `- Source: ${res.source}\n`;
+  if (res.link) out += `- Link: ${res.link}\n`;
+  if (res.snippet) out += `- Snippet: ${res.snippet}\n`;
+  if (res.created_at) out += `- Created: ${res.created_at}\n`;
+  out += '\n';
+  return out;
+}
+
+function formatRetrieveResult(r) {
+  if (!r) return '';
+  const score = r.score != null ? `${(r.score * 100).toFixed(1)}%` : 'N/A';
+  let out = `### ${r.title || '(untitled)'} (score: ${score})\n`;
+  out += `- ID: \`${r.id}\`\n`;
+  if (r.content) {
+    const preview = r.content.length > 300 ? r.content.slice(0, 300) + '...' : r.content;
+    out += `- Content: ${preview}\n`;
+  }
+  out += '\n';
+  return out;
+}
+
+// ── Exported functions ──
+
+export async function createLiveDoc(opts = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
+  if (!opts.name) { process.stderr.write('ERROR: --name is required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Creating LiveDoc');
+
+  try {
+    const body = { name: opts.name };
+    if (opts.description) body.description = opts.description;
+    if (opts.icon) body.icon = opts.icon;
+    const payload = await apiRequest('POST', '/livedocs', body, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+    const doc = payload?.data;
+    process.stdout.write(`LiveDoc created successfully!\n\n`);
+    process.stdout.write(formatLiveDoc(doc));
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to create LiveDoc: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+export async function listLiveDocs(opts = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Listing LiveDocs');
+
+  try {
+    const params = new URLSearchParams();
+    if (opts.keyword) params.set('keyword', opts.keyword);
+    if (opts.page) params.set('page', opts.page);
+    if (opts.size) params.set('size', opts.size);
+    const qs = params.toString();
+    const apiPath = `/livedocs${qs ? `?${qs}` : ''}`;
+    const payload = await apiRequest('GET', apiPath, null, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+
+    const data = payload?.data;
+    const items = data?.items || [];
+    if (!items.length) { process.stderr.write('No LiveDocs found.\n'); return 0; }
+    process.stdout.write(`Found ${data.total || items.length} LiveDoc(s)\n\n`);
+    for (const doc of items) { process.stdout.write(formatLiveDoc(doc)); }
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to list LiveDocs: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
+export async function updateLiveDoc(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; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Updating LiveDoc');
+
+  try {
+    const body = {};
+    if (opts.name) body.name = opts.name;
+    if (opts.description) body.description = opts.description;
+    const payload = await apiRequest('PUT', `/livedocs/${shortId}`, body, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+    process.stdout.write(`LiveDoc updated successfully!\n\n`);
+    process.stdout.write(formatLiveDoc(payload?.data));
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to update LiveDoc: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+export async function deleteLiveDoc(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; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Deleting LiveDoc');
+
+  try {
+    await apiRequest('DELETE', `/livedocs/${shortId}`, null, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify({ status: 'ok' }, null, 2)); return 0; }
+    process.stdout.write(`LiveDoc \`${shortId}\` deleted.\n`);
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to delete LiveDoc: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
+export async function listResources(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; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Listing resources');
+
+  try {
+    const params = new URLSearchParams();
+    if (opts.type) params.set('resource_types', opts.type);
+    if (opts.page) params.set('page', opts.page);
+    if (opts.size) params.set('size', opts.size);
+    const qs = params.toString();
+    const apiPath = `/livedocs/${shortId}/resources${qs ? `?${qs}` : ''}`;
+    const payload = await apiRequest('GET', apiPath, null, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+
+    const data = payload?.data;
+    const items = data?.items || [];
+    if (!items.length) { process.stderr.write('No resources found.\n'); return 0; }
+    process.stdout.write(`Found ${data.total || items.length} resource(s)\n\n`);
+    for (const r of items) { process.stdout.write(formatResource(r)); }
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to list resources: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+export async function getResource(shortId, resourceId, opts = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
+  if (!shortId || !resourceId) { process.stderr.write('ERROR: short_id and resource_id are required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Fetching resource');
+
+  try {
+    const payload = await apiRequest('GET', `/livedocs/${shortId}/resources/${resourceId}`, null, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+    process.stdout.write(formatResource(payload?.data));
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to get resource: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
+export async function addDoc(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.content) { process.stderr.write('ERROR: --content is required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Creating document resource');
+
+  try {
+    const body = { content: opts.content };
+    if (opts.title) body.title = opts.title;
+    const payload = await apiRequest('POST', `/livedocs/${shortId}/resources/doc`, body, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+    process.stdout.write(`Document resource created!\n\n`);
+    process.stdout.write(formatResource(payload?.data));
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to create document: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
+export async function addUrls(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.urls) { process.stderr.write('ERROR: --urls is required.\n'); return 1; }
+
+  const urls = opts.urls.split(',').map(u => u.trim()).filter(Boolean);
+  if (!urls.length) { process.stderr.write('ERROR: at least one URL is required.\n'); return 1; }
+  if (urls.length > 10) { process.stderr.write('ERROR: maximum 10 URLs allowed.\n'); return 1; }
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner(`Adding ${urls.length} URL(s)`);
+
+  try {
+    const payload = await apiRequest('POST', `/livedocs/${shortId}/resources/urls`, { urls }, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+
+    const results = payload?.data || [];
+    for (const r of results) {
+      const icon = r.status === 'success' ? '✓' : r.status === 'existed' ? '~' : '✗';
+      let line = `${icon} ${r.url} → ${r.status}`;
+      if (r.resource_id) line += ` (id: ${r.resource_id})`;
+      if (r.fail_reason) line += ` (${r.fail_reason})`;
+      process.stdout.write(line + '\n');
+    }
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to add URLs: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
+export async function uploadFile(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.file) { process.stderr.write('ERROR: --file is required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const endpoint = opts.convert ? 'upload-doc' : 'upload';
+  const spinnerId = startSpinner(`Uploading file (${endpoint})`);
+
+  try {
+    const fileBuffer = await fs.readFile(opts.file);
+    const blob = new Blob([fileBuffer]);
+    const formData = new FormData();
+    formData.append('file', blob, path.basename(opts.file));
+
+    const payload = await uploadFormData(`/livedocs/${shortId}/resources/${endpoint}`, formData, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify(payload, null, 2)); return 0; }
+    process.stdout.write(`File uploaded successfully!\n\n`);
+    process.stdout.write(formatResource(payload?.data));
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to upload file: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+export async function removeResource(shortId, resourceId, opts = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) { console.error(NO_KEY_MESSAGE.trim()); return 1; }
+  if (!shortId || !resourceId) { process.stderr.write('ERROR: short_id and resource_id are required.\n'); return 1; }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const spinnerId = startSpinner('Deleting resource');
+
+  try {
+    await apiRequest('DELETE', `/livedocs/${shortId}/resources/${resourceId}`, null, apiKey, apiBase, timeoutMs);
+    if (opts.json) { console.log(JSON.stringify({ status: 'ok' }, null, 2)); return 0; }
+    process.stdout.write(`Resource \`${resourceId}\` deleted.\n`);
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Failed to delete resource: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}
+
+export async function retrieve(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.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 from knowledge base');
+
+  try {
+    const body = { content: opts.query };
+    const payload = await apiRequest('POST', `/livedocs/${shortId}/resources/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 retrieve: ${err?.message || err}\n`);
+    return 1;
+  } finally { stopSpinner(spinnerId); }
+}