okrapdf 0.12.1 → 0.14.0

package/dist/cli/bin.js

@@ -6,15 +6,26 @@ import {
   authStatus,
   authToken,
   authWhoAmI,
+  collectionAddDocs,
+  collectionCreate,
+  collectionDelete,
   collectionExport,
   collectionList,
   collectionQueryRaw,
+  collectionRemoveDocs,
   collectionSetVisibility,
+  collectionShow,
+  deleteDocument,
   find,
   formatCollectionCsv,
+  formatCollectionDetail,
   formatCollectionExportFlat,
   formatCollectionList,
   formatCollectionTable,
+  formatDocumentList,
+  formatExtractCsv,
+  formatExtractJson,
+  formatExtractTable,
   formatFindOutput,
   formatHistoryOutput,
   formatPageOutput,
@@ -29,33 +40,230 @@ import {
   getBaseUrl,
   handleError,
   history,
+  listDocuments,
+  localDoctor,
+  localIngest,
+  localPage,
+  localSearch,
+  localStatus,
+  localSummary,
+  localTables,
   pageEdit,
   pageGet,
   pageResolve,
   pageVersions,
   progress,
+  readDocument,
   search,
   tables,
   toc,
   tree,
   upload,
   writeOutput
-} from "../chunk-XOHPZW3V.js";
+} from "../chunk-ETARIBOV.js";
+import "../chunk-MSZQPLMQ.js";
 import {
   OkraClient
-} from "../chunk-2HJPTW6S.js";
+} from "../chunk-YGIBZV5J.js";
 import "../chunk-NIZM2ETT.js";
 
 // src/cli/bin.ts
 import { Command } from "commander";
-import { writeFileSync } from "fs";
+import { realpathSync, writeFileSync } from "fs";
+import { resolve } from "path";
+import { pathToFileURL } from "url";
+
+// package.json
+var package_default = {
+  name: "okrapdf",
+  version: "0.14.0",
+  okraApi: "^1.14.0",
+  description: "OkraPDF \u2014 upload a PDF, get an API. Runtime client, React hooks, and CLI.",
+  type: "module",
+  exports: {
+    ".": {
+      import: {
+        types: "./dist/index.d.ts",
+        default: "./dist/index.js"
+      }
+    },
+    "./doc": {
+      import: {
+        types: "./dist/url.d.ts",
+        default: "./dist/url.js"
+      }
+    },
+    "./browser": {
+      import: {
+        types: "./dist/browser.d.ts",
+        default: "./dist/browser.js"
+      }
+    },
+    "./worker": {
+      import: {
+        types: "./dist/worker.d.ts",
+        default: "./dist/worker.js"
+      }
+    },
+    "./react": {
+      import: {
+        types: "./dist/react/index.d.ts",
+        default: "./dist/react/index.js"
+      }
+    },
+    "./cli": {
+      import: {
+        types: "./dist/cli/index.d.ts",
+        default: "./dist/cli/index.js"
+      }
+    }
+  },
+  bin: {
+    okra: "./dist/cli/bin.js"
+  },
+  files: [
+    "dist"
+  ],
+  scripts: {
+    build: "tsup",
+    "docs:cli": "node ./scripts/generate-cli-docs.mjs",
+    "docs:cli:check": "node ./scripts/generate-cli-docs.mjs --check",
+    test: "vitest run --exclude '**/**.e2e.test.ts'",
+    "test:e2e": "vitest run src/client.e2e.test.ts",
+    "test:watch": "vitest",
+    typecheck: "tsc --noEmit"
+  },
+  dependencies: {
+    commander: "^12.0.0",
+    ws: "^8.19.0",
+    zod: "^4.3.6"
+  },
+  peerDependencies: {
+    react: ">=18"
+  },
+  peerDependenciesMeta: {
+    react: {
+      optional: true
+    }
+  },
+  devDependencies: {
+    "@types/node": "^20.14.0",
+    "@types/react": "^18.2.0",
+    "@types/ws": "^8.18.1",
+    react: "^18.2.0",
+    tsup: "^8.0.0",
+    typescript: "^5.5.0",
+    vitest: "^2.0.0"
+  },
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "https://github.com/okrapdf/okrapdf-sdk"
+  },
+  homepage: "https://okrapdf.com",
+  author: "OkraPDF",
+  keywords: [
+    "pdf",
+    "ocr",
+    "document",
+    "extraction",
+    "api",
+    "sdk",
+    "structured-output"
+  ],
+  publishConfig: {
+    access: "public"
+  }
+};
+
+// src/cli/bin.ts
+var CLI_VERSION = package_default.version;
+var PRIMARY_COMMANDS = ["auth", "upload", "extract", "chat", "list", "read", "delete", "collection"];
+var ADVANCED_COMMANDS = ["status", "tree", "find", "page", "search", "tables", "history", "toc", "local"];
+var PRIMARY_COLLECTION_SUBCOMMANDS = ["list", "query"];
+var ADVANCED_COLLECTION_SUBCOMMANDS = ["create", "show", "delete", "add", "remove", "publish", "unpublish", "export"];
+var ROOT_HELP_FOOTER = [
+  "",
+  "Primary workflows:",
+  "  okra auth login",
+  "  okra upload ./report.pdf",
+  '  okra chat "Summarize this document" --doc doc-abc123',
+  "  okra extract ./report.pdf --schema ./schema.json",
+  '  okra collection query earnings "What changed quarter over quarter?" -o earnings.csv',
+  "",
+  "Advanced inspection and local-only commands are intentionally hidden from",
+  "default help during the v0.14 clean-house release candidate."
+].join("\n");
+var COLLECTION_HELP_FOOTER = [
+  "",
+  "Stable v0.14 collection workflow:",
+  '  okra collection query <name> "<question>"',
+  "",
+  "Experimental structured fan-out remains available via:",
+  '  okra collection query <name> "<question>" --schema ./schema.json',
+  "  okra collection extract <name> --schema ./schema.json",
+  "",
+  "Advanced collection management commands remain available but are",
+  "intentionally hidden from default help during the clean-house release",
+  "candidate."
+].join("\n");
 var program = new Command();
 program.showHelpAfterError();
 program.showSuggestionAfterError();
-program.name("okra").description("OkraPDF CLI \u2014 upload PDFs, query collections, extract data").version("0.12.1").option("-j, --json", "Output JSON (structured, machine-readable)").option("-q, --quiet", "Suppress progress and human-readable frills").option("-o, --output <file>", "Write output to file instead of stdout");
+program.name("okra").description("Okra CLI \u2014 upload PDFs, chat with documents, and extract structured data").version(CLI_VERSION).option("-j, --json", "Output JSON (structured, machine-readable)").option("-q, --quiet", "Suppress progress and human-readable frills").option("-o, --output <file>", "Write output to file instead of stdout");
+program.addHelpText(
+  "after",
+  ROOT_HELP_FOOTER
+);
 function globals() {
   return program.opts();
 }
+function getMissingApiKeyMessage() {
+  return [
+    "No API key found.",
+    "",
+    "Set one up with:",
+    "  okra auth login",
+    '  export OKRA_API_KEY="okra_xxx"',
+    "",
+    "Get your API key at:",
+    "  https://app.okrapdf.com/settings",
+    "",
+    "CLI docs:",
+    "  https://docs.okrapdf.com/api-reference/cli"
+  ].join("\n");
+}
+function formatDocumentReadyMessage(docId, pages) {
+  return [
+    `Ready: ${docId}${typeof pages === "number" ? ` (${pages} pages)` : ""}`,
+    "",
+    "Next:",
+    `  okra chat "Summarize this document" --doc ${docId}`,
+    `  okra read ${docId}`,
+    `  okra extract ${docId} --schema ./schema.json`
+  ].join("\n");
+}
+function formatQueuedDocumentMessage(docId) {
+  return [
+    `Queued: ${docId}`,
+    "",
+    "Next:",
+    `  okra status ${docId}`,
+    "",
+    "Once processing finishes:",
+    `  okra chat "Summarize this document" --doc ${docId}`,
+    `  okra read ${docId}`
+  ].join("\n");
+}
+function isDirectExecution() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(resolve(entry))).href;
+  } catch {
+    return import.meta.url === pathToFileURL(resolve(entry)).href;
+  }
+}
 function getClient() {
   const apiKey = getApiKey();
   const baseUrl = getBaseUrl();
@@ -64,55 +272,205 @@ function getClient() {
     if (g.json) {
       process.stderr.write(JSON.stringify({ error: "No API key found", code: 401 }) + "\n");
     } else {
-      process.stderr.write(
-        'No API key found.\n\n  Get one: https://docs.okrapdf.com/api-keys\n  Then:    export OKRA_API_KEY="okra_xxx"\n  Or:      npx okra auth login\n\n  Docs:    https://docs.okrapdf.com\n  Discord: https://discord.gg/BHNmbZVs\n'
-      );
+      process.stderr.write(getMissingApiKeyMessage() + "\n");
     }
     process.exit(1);
   }
   return new OkraClient({ apiKey, baseUrl });
 }
+function writeLocalResult(result, humanText) {
+  const g = globals();
+  if (g.json) {
+    writeOutput(JSON.stringify(result), g.output);
+  } else {
+    writeOutput(humanText, g.output);
+  }
+}
+var localCmd = program.command("local", { hidden: true }).description("Offline PDF tools for local OpenClaw/opencode harnesses");
+localCmd.command("ingest <source>").description("Ingest a local PDF into the offline document store").option("--data-dir <path>", "Override local document store path").action(async (source, options) => {
+  const g = globals();
+  try {
+    const result = localIngest(source, { dataDir: options.dataDir });
+    writeLocalResult(
+      result,
+      `Indexed ${result.filename} as ${result.documentId} (${result.pageCount} pages, ${result.charCount} chars)`
+    );
+  } catch (error) {
+    handleError(error, g.json);
+  }
+});
+localCmd.command("status").description("Get local document status").requiredOption("--doc <id>", "Local document ID").option("--data-dir <path>", "Override local document store path").action(async (options) => {
+  const g = globals();
+  try {
+    const result = localStatus(options.doc, { dataDir: options.dataDir });
+    writeLocalResult(
+      result,
+      `${result.documentId}: ${result.status} (${result.pagesWithText}/${result.pageCount} pages with text)`
+    );
+  } catch (error) {
+    handleError(error, g.json);
+  }
+});
+localCmd.command("summary").description("Produce an extractive summary of a local PDF").requiredOption("--doc <id>", "Local document ID").option("--data-dir <path>", "Override local document store path").action(async (options) => {
+  const g = globals();
+  try {
+    const result = localSummary(options.doc, { dataDir: options.dataDir });
+    writeLocalResult(result, result.summary);
+  } catch (error) {
+    handleError(error, g.json);
+  }
+});
+localCmd.command("search").description("Search within a local PDF").requiredOption("--doc <id>", "Local document ID").requiredOption("--query <text>", "Search query").option("--data-dir <path>", "Override local document store path").action(async (options) => {
+  const g = globals();
+  try {
+    const result = localSearch(options.doc, options.query, { dataDir: options.dataDir });
+    const preview = result.matches.map((match) => `p.${match.page}: ${match.snippet}`).join("\n");
+    writeLocalResult(result, preview || `No matches found for "${options.query}"`);
+  } catch (error) {
+    handleError(error, g.json);
+  }
+});
+localCmd.command("page").description("Read one extracted page from a local PDF").requiredOption("--doc <id>", "Local document ID").requiredOption("--page <n>", "1-indexed page number", parseInt).option("--data-dir <path>", "Override local document store path").action(async (options) => {
+  const g = globals();
+  try {
+    const result = localPage(options.doc, options.page, { dataDir: options.dataDir });
+    writeLocalResult(result, result.text);
+  } catch (error) {
+    handleError(error, g.json);
+  }
+});
+localCmd.command("tables").description("Detect table-like layout blocks from a local PDF").requiredOption("--doc <id>", "Local document ID").option("--query <text>", "Optional query to rank table-like blocks").option("--data-dir <path>", "Override local document store path").action(async (options) => {
+  const g = globals();
+  try {
+    const result = localTables(options.doc, options.query, { dataDir: options.dataDir });
+    const preview = result.tables.map((table) => `p.${table.page} (${table.rowCount} rows)
+${table.preview}`).join("\n\n");
+    writeLocalResult(result, preview || "No table-like blocks found");
+  } catch (error) {
+    handleError(error, g.json);
+  }
+});
+localCmd.command("doctor").description("Check local offline PDF tool availability").option("--data-dir <path>", "Override local document store path").action(async (options) => {
+  const g = globals();
+  try {
+    const result = localDoctor({ dataDir: options.dataDir });
+    const human = [
+      `data dir: ${result.dataDir}`,
+      `pdftotext: ${result.tools.pdftotext.available ? result.tools.pdftotext.path : "missing"}`,
+      `pdfinfo: ${result.tools.pdfinfo.available ? result.tools.pdfinfo.path : "missing"}`,
+      `pdftoppm: ${result.tools.pdftoppm.available ? result.tools.pdftoppm.path : "missing"}`,
+      `tesseract: ${result.tools.tesseract.available ? result.tools.tesseract.path : "missing"}`
+    ].join("\n");
+    writeLocalResult(result, human);
+  } catch (error) {
+    handleError(error, g.json);
+  }
+});
 async function runUploadCommand(source, options) {
   const g = globals();
   try {
     const client = getClient();
+    let vendorOptions;
+    if (options.vendorOptions) {
+      try {
+        vendorOptions = JSON.parse(options.vendorOptions);
+      } catch {
+        process.stderr.write("Error: --vendor-options must be valid JSON\n");
+        process.exit(1);
+      }
+    }
     const result = await upload(client, source, {
       ...g,
-      noWait: options.wait === false
+      noWait: options.wait === false,
+      vendorOptions
     });
     if (g.json) {
       writeOutput(JSON.stringify(result), g.output);
     } else {
-      const lines = [`Done \u2014 ${result.pages ?? "?"} pages`, ""];
-      lines.push(`  ${result.id}`);
-      if (result.urls) {
-        const short = result.id.slice(0, 11) + "...";
-        lines.push("");
-        lines.push(`  Markdown:   ${result.urls.full_md.replace(result.id, short)}`);
-        lines.push(`  Page 1:     ${result.urls.page_png.replace(result.id, short).replace("{N}", "1")}`);
-        lines.push(`  Completion: ${result.urls.completion.replace(result.id, short)}`);
-        lines.push("");
-        lines.push("  URL patterns:");
-        lines.push("    /v1/documents/{id}/pg_{N}.md             page markdown");
-        lines.push("    /v1/documents/{id}/d_shimmer/pg_{N}.png  page image");
-        lines.push("    /v1/documents/{id}/full.md               full document");
-        lines.push("");
-        lines.push("  Docs: https://docs.okrapdf.com  Discord: https://discord.gg/BHNmbZVs");
-      }
-      writeOutput(lines.join("\n"), g.output);
+      writeOutput(
+        options.wait === false ? formatQueuedDocumentMessage(result.id) : formatDocumentReadyMessage(result.id, result.pages),
+        g.output
+      );
     }
   } catch (error) {
     handleError(error, g.json);
   }
 }
 function registerUploadCommand(commandName, description) {
-  program.command(`${commandName} <source>`).description(description).option("--no-wait", "Fire-and-forget (don't wait for processing)").action(async (source, options) => {
+  program.command(`${commandName} <source>`).description(description).summary("Upload a PDF and wait for processing").option("--no-wait", "Fire-and-forget (don't wait for processing)").option("--vendor-options <json>", `JSON vendor-specific options (e.g., '{"model":"gemini-3.1-pro","parse_mode":"parse_page_with_agent"}')`).action(async (source, options) => {
     await runUploadCommand(source, options);
   });
 }
 registerUploadCommand("upload", "Upload a PDF (file path or URL), wait for processing");
-registerUploadCommand("extract", "Alias for upload (compatibility)");
-program.command("status <docId>").description("Get document processing status").action(async (docId) => {
+program.command("extract <source>").description("Extract structured data from a document (doc ID, URL, or file path)").summary("Upload a PDF and extract structured data").option("--no-wait", "Fire-and-forget (don't wait for processing)").option("--schema <file>", "JSON Schema file or inline JSON for structured extraction").option("--prompt <query>", 'Extraction prompt (default: "Extract all data according to the schema")').action(async (source, options) => {
+  const g = globals();
+  try {
+    const client = getClient();
+    const { readFileSync } = await import("fs");
+    const isExistingDoc = /^(?:ocr|doc)-[A-Za-z0-9_-]+$/.test(source);
+    let docId;
+    if (isExistingDoc) {
+      docId = source;
+    } else {
+      const result = await upload(client, source, {
+        ...g,
+        noWait: options.wait === false
+      });
+      docId = result.id;
+      if (!options.schema || options.wait === false) {
+        if (g.json) {
+          writeOutput(JSON.stringify(result), g.output);
+        } else {
+          writeOutput(
+            options.wait === false ? formatQueuedDocumentMessage(docId) : formatDocumentReadyMessage(docId, result.pages),
+            g.output
+          );
+        }
+        return;
+      }
+    }
+    if (!options.schema) {
+      if (isExistingDoc) {
+        writeOutput("Error: --schema is required when extracting from an existing document.", g.output);
+        process.exitCode = 1;
+        return;
+      }
+      return;
+    }
+    let schemaJson;
+    const schemaArg = options.schema;
+    if (schemaArg.startsWith("{")) {
+      schemaJson = JSON.parse(schemaArg);
+    } else {
+      schemaJson = JSON.parse(readFileSync(schemaArg, "utf8"));
+    }
+    const prompt = options.prompt || "Extract all data from this document according to the schema.";
+    progress(`Extracting from ${docId}\u2026`, g.quiet);
+    const extraction = await client.generate(docId, prompt, { schema: schemaJson });
+    if (g.json) {
+      writeOutput(JSON.stringify({
+        doc_id: docId,
+        data: extraction.data ?? extraction.answer
+      }), g.output);
+    } else if (g.output && g.output.endsWith(".csv")) {
+      const data = extraction.data ?? {};
+      const keys = Object.keys(data);
+      const header = ["doc_id", ...keys].join(",");
+      const values = keys.map((k) => {
+        const v = data[k];
+        if (v == null) return "";
+        if (typeof v === "string") return `"${String(v).replace(/"/g, '""')}"`;
+        return String(v);
+      });
+      writeOutput([header, [docId, ...values].join(",")].join("\n"), g.output);
+    } else {
+      writeOutput(JSON.stringify(extraction.data ?? extraction.answer, null, 2), g.output);
+    }
+  } catch (error) {
+    handleError(error, g.json);
+  }
+});
+program.command("status <docId>", { hidden: true }).description("Get document processing status").action(async (docId) => {
   const g = globals();
   try {
     const client = getClient();
@@ -133,10 +491,32 @@ program.command("status <docId>").description("Get document processing status").
     handleError(error, g.json);
   }
 });
-program.command("chat <question>").description("Ask a question about a processed document").requiredOption("--doc <id>", "Document ID").option("--model <name>", "Override model").action(async (question, options) => {
+program.command("chat <question>").description("Ask a question about a processed document").summary("Ask a question about one document").requiredOption("--doc <id>", "Document ID").option("--model <name>", "Override model").option("--stream", "Stream response tokens as they arrive").action(async (question, options) => {
   const g = globals();
   try {
     const client = getClient();
+    if (options.stream) {
+      let fullText = "";
+      for await (const event of client.stream(options.doc, question, {
+        model: options.model
+      })) {
+        if (event.type === "text_delta") {
+          fullText += event.text;
+          if (!g.json) process.stdout.write(event.text);
+        } else if (event.type === "done") {
+          if (!g.json) process.stdout.write("\n");
+          if (g.json) {
+            writeOutput(
+              JSON.stringify({ docId: options.doc, question, answer: fullText }),
+              g.output
+            );
+          }
+        } else if (event.type === "error") {
+          throw new Error(event.message);
+        }
+      }
+      return;
+    }
     const result = await client.generate(options.doc, question, options.model ? { model: options.model } : void 0);
     if (g.json) {
       writeOutput(JSON.stringify({ docId: options.doc, question, ...result }), g.output);
@@ -147,8 +527,51 @@ program.command("chat <question>").description("Ask a question about a processed
     handleError(error, g.json);
   }
 });
+program.command("list").alias("ls").description("List all documents").summary("List your documents").action(async () => {
+  const g = globals();
+  try {
+    const client = getClient();
+    const { documents } = await listDocuments(client, g);
+    writeOutput(formatDocumentList(documents, g.json), g.output);
+  } catch (error) {
+    handleError(error, g.json);
+  }
+});
+program.command("delete <docId>").alias("rm").description("Delete a document").summary("Delete one document").action(async (docId) => {
+  const g = globals();
+  try {
+    const client = getClient();
+    const result = await deleteDocument(client, docId, g);
+    if (g.json) {
+      writeOutput(JSON.stringify(result), g.output);
+    } else {
+      writeOutput(`Deleted ${docId}`, g.output);
+    }
+  } catch (error) {
+    handleError(error, g.json);
+  }
+});
+program.command("read <docId>").description("Read document as markdown").summary("Read document markdown").option("-p, --pages <range>", "Page range (e.g., 1-5, 10-15)").action(async (docId, options) => {
+  const g = globals();
+  try {
+    const client = getClient();
+    const result = await readDocument(client, docId, { ...g, pages: options.pages });
+    if (g.json) {
+      writeOutput(JSON.stringify(result), g.output);
+    } else {
+      writeOutput(result.markdown, g.output);
+    }
+  } catch (error) {
+    handleError(error, g.json);
+  }
+});
 var collectionCmd = program.command("collection").alias("collections").alias("col").description("Collection operations");
-collectionCmd.command("list").alias("ls").description("List available collections").action(async () => {
+collectionCmd.summary("Query across collections");
+collectionCmd.addHelpText(
+  "after",
+  COLLECTION_HELP_FOOTER
+);
+collectionCmd.command("list").alias("ls").description("List available collections").summary("List collections").action(async () => {
   const g = globals();
   try {
     const client = getClient();
@@ -158,7 +581,73 @@ collectionCmd.command("list").alias("ls").description("List available collection
     handleError(error, g.json);
   }
 });
-collectionCmd.command("query <nameOrId> <question>").description("Fan-out query across collection documents").option("--schema <file>", "JSON Schema file for structured extraction").action(async (nameOrId, question, options) => {
+collectionCmd.command("create <name>", { hidden: true }).description("Create a new collection").option("--description <text>", "Collection description").option("--docs <ids>", "Comma-separated document IDs to seed").action(async (name, options) => {
+  const g = globals();
+  try {
+    const client = getClient();
+    const result = await collectionCreate(client, name, { ...g, ...options });
+    if (g.json) {
+      writeOutput(JSON.stringify(result), g.output);
+    } else {
+      writeOutput(`Created collection "${result.name}" (${result.id})`, g.output);
+    }
+  } catch (error) {
+    handleError(error, g.json);
+  }
+});
+collectionCmd.command("show <nameOrId>", { hidden: true }).description("Show collection details and documents").action(async (nameOrId) => {
+  const g = globals();
+  try {
+    const client = getClient();
+    const detail = await collectionShow(client, nameOrId);
+    writeOutput(formatCollectionDetail(detail, g.json), g.output);
+  } catch (error) {
+    handleError(error, g.json);
+  }
+});
+collectionCmd.command("delete <nameOrId>", { hidden: true }).alias("rm").description("Delete a collection (documents are preserved)").action(async (nameOrId) => {
+  const g = globals();
+  try {
+    const client = getClient();
+    await collectionDelete(client, nameOrId);
+    if (g.json) {
+      writeOutput(JSON.stringify({ ok: true, deleted: nameOrId }), g.output);
+    } else {
+      writeOutput(`Deleted collection "${nameOrId}"`, g.output);
+    }
+  } catch (error) {
+    handleError(error, g.json);
+  }
+});
+collectionCmd.command("add <nameOrId> <docIds...>", { hidden: true }).description("Add documents to a collection").action(async (nameOrId, docIds) => {
+  const g = globals();
+  try {
+    const client = getClient();
+    const result = await collectionAddDocs(client, nameOrId, docIds);
+    if (g.json) {
+      writeOutput(JSON.stringify(result), g.output);
+    } else {
+      writeOutput(`Added ${docIds.length} document(s) to "${nameOrId}"`, g.output);
+    }
+  } catch (error) {
+    handleError(error, g.json);
+  }
+});
+collectionCmd.command("remove <nameOrId> <docIds...>", { hidden: true }).description("Remove documents from a collection").action(async (nameOrId, docIds) => {
+  const g = globals();
+  try {
+    const client = getClient();
+    const result = await collectionRemoveDocs(client, nameOrId, docIds);
+    if (g.json) {
+      writeOutput(JSON.stringify(result), g.output);
+    } else {
+      writeOutput(`Removed ${docIds.length} document(s) from "${nameOrId}"`, g.output);
+    }
+  } catch (error) {
+    handleError(error, g.json);
+  }
+});
+collectionCmd.command("query <nameOrId> <question>").description("Fan-out query across collection documents").summary("Ask the same question across a collection").option("--schema <file>", "Experimental: JSON Schema file for structured extraction").action(async (nameOrId, question, options) => {
   const g = globals();
   try {
     const client = getClient();
@@ -185,7 +674,44 @@ collectionCmd.command("query <nameOrId> <question>").description("Fan-out query
     handleError(error, g.json);
   }
 });
-collectionCmd.command("publish <nameOrId>").description("Make a collection publicly queryable").action(async (nameOrId) => {
+collectionCmd.command("extract <nameOrId>", { hidden: true }).description("Experimental: extract structured data from all documents in a collection").summary("Experimental structured extraction").requiredOption("--schema <file>", "Experimental: JSON Schema file or inline JSON for structured extraction").option("--prompt <query>", "Extraction prompt (default: auto-generated from schema)").action(async (nameOrId, options) => {
+  const g = globals();
+  try {
+    const client = getClient();
+    const { readFileSync } = await import("fs");
+    let schemaJson;
+    const schemaArg = options.schema;
+    if (schemaArg.startsWith("{")) {
+      schemaJson = JSON.parse(schemaArg);
+    } else {
+      schemaJson = JSON.parse(readFileSync(schemaArg, "utf8"));
+    }
+    const prompt = options.prompt || "Extract all data from this document according to the schema.";
+    const { results, summary } = await collectionQueryRaw(
+      client,
+      nameOrId,
+      prompt,
+      { ...g, schema: schemaJson }
+    );
+    if (g.json) {
+      writeOutput(formatExtractJson(results), g.output);
+    } else if (g.output && g.output.endsWith(".csv")) {
+      writeOutput(formatExtractCsv(results), g.output);
+    } else if (g.output) {
+      writeOutput(formatExtractJson(results), g.output);
+    } else {
+      writeOutput(formatExtractTable(results));
+    }
+    progress(
+      `
+${summary.completed} documents \u2014 $${summary.total_cost_usd.toFixed(4)} total`,
+      g.quiet
+    );
+  } catch (error) {
+    handleError(error, g.json);
+  }
+});
+collectionCmd.command("publish <nameOrId>", { hidden: true }).description("Make a collection publicly queryable").action(async (nameOrId) => {
   const g = globals();
   try {
     const client = getClient();
@@ -203,7 +729,7 @@ Share with: okra collection query ${nameOrId} "your question"`,
     handleError(error, g.json);
   }
 });
-collectionCmd.command("unpublish <nameOrId>").description("Make a collection private (owner-only)").action(async (nameOrId) => {
+collectionCmd.command("unpublish <nameOrId>", { hidden: true }).description("Make a collection private (owner-only)").action(async (nameOrId) => {
   const g = globals();
   try {
     const client = getClient();
@@ -217,7 +743,7 @@ collectionCmd.command("unpublish <nameOrId>").description("Make a collection pri
     handleError(error, g.json);
   }
 });
-collectionCmd.command("export <nameOrId>").description("Export pre-computed markdown for all documents in a collection").option("--flat", "Concatenated markdown with # headers + === separators").option("--zip", "One markdown file per document in a .zip archive").action(async (nameOrId, options) => {
+collectionCmd.command("export <nameOrId>", { hidden: true }).description("Export pre-computed markdown for all documents in a collection").option("--flat", "Concatenated markdown with # headers + === separators").option("--zip", "One markdown file per document in a .zip archive").action(async (nameOrId, options) => {
   const g = globals();
   try {
     const client = getClient();
@@ -294,7 +820,7 @@ authCmd.command("logout").description("Remove API key from global config").actio
     handleError(error, globals().json);
   }
 });
-program.command("tree <jobId>").description("Show document verification tree").option("-s, --status <status>", "Filter by status (complete|partial|pending|flagged|empty|gap)").option("-e, --entity <type>", "Filter by entity type (table|figure|footnote)").option("-f, --format <format>", "Output format (text|json|markdown)", "text").action(async (jobId, options) => {
+program.command("tree <jobId>", { hidden: true }).description("Show document verification tree").option("-s, --status <status>", "Filter by status (complete|partial|pending|flagged|empty|gap)").option("-e, --entity <type>", "Filter by entity type (table|figure|footnote)").option("-f, --format <format>", "Output format (text|json|markdown)", "text").action(async (jobId, options) => {
   const g = globals();
   try {
     const client = getClient();
@@ -308,7 +834,7 @@ program.command("tree <jobId>").description("Show document verification tree").o
     handleError(error, g.json);
   }
 });
-program.command("find <jobId> <selector>").description("Find entities using jQuery-like selectors").option("-k, --top-k <n>", "Limit results", parseInt).option("-c, --min-confidence <n>", "Minimum confidence (0-1)", parseFloat).option("-p, --pages <range>", "Page range (e.g., 1-10)").option("--sort <by>", "Sort by (confidence|page|type)").option("--stats", "Show aggregate statistics").option("-f, --format <format>", "Output format (text|json|entities|ids)", "text").action(async (jobId, selector, options) => {
+program.command("find <jobId> <selector>", { hidden: true }).description("Find entities using jQuery-like selectors").option("-k, --top-k <n>", "Limit results", parseInt).option("-c, --min-confidence <n>", "Minimum confidence (0-1)", parseFloat).option("-p, --pages <range>", "Page range (e.g., 1-10)").option("--sort <by>", "Sort by (confidence|page|type)").option("--stats", "Show aggregate statistics").option("-f, --format <format>", "Output format (text|json|entities|ids)", "text").action(async (jobId, selector, options) => {
   const g = globals();
   try {
     const client = getClient();
@@ -329,7 +855,7 @@ program.command("find <jobId> <selector>").description("Find entities using jQue
     handleError(error, g.json);
   }
 });
-var pageCmd = program.command("page").description("Page content operations");
+var pageCmd = program.command("page", { hidden: true }).description("Page content operations");
 pageCmd.command("get <jobId> <pageNum>").description("Get page content").option("-v, --version <n>", "Specific version", parseInt).option("-f, --format <format>", "Output format (text|json|markdown)", "markdown").action(async (jobId, pageNum, options) => {
   const g = globals();
   try {
@@ -391,7 +917,7 @@ pageCmd.command("versions <jobId> <pageNum>").description("List page versions").
     handleError(error, g.json);
   }
 });
-program.command("search <jobId> <query>").description("Search page content").option("-f, --format <format>", "Output format (text|json)", "text").action(async (jobId, query, options) => {
+program.command("search <jobId> <query>", { hidden: true }).description("Search page content").option("-f, --format <format>", "Output format (text|json)", "text").action(async (jobId, query, options) => {
   const g = globals();
   try {
     const client = getClient();
@@ -402,7 +928,7 @@ program.command("search <jobId> <query>").description("Search page content").opt
     handleError(error, g.json);
   }
 });
-program.command("tables <jobId>").description("List extracted tables").option("-p, --page <n>", "Filter by page", parseInt).option("-s, --status <status>", "Filter by status (pending|verified|flagged|rejected)").option("-f, --format <format>", "Output format (text|json|markdown)", "text").action(async (jobId, options) => {
+program.command("tables <jobId>", { hidden: true }).description("List extracted tables").option("-p, --page <n>", "Filter by page", parseInt).option("-s, --status <status>", "Filter by status (pending|verified|flagged|rejected)").option("-f, --format <format>", "Output format (text|json|markdown)", "text").action(async (jobId, options) => {
   const g = globals();
   try {
     const client = getClient();
@@ -416,7 +942,7 @@ program.command("tables <jobId>").description("List extracted tables").option("-
     handleError(error, g.json);
   }
 });
-program.command("history <jobId>").description("Show verification history").option("-l, --limit <n>", "Limit entries", parseInt, 50).option("-f, --format <format>", "Output format (text|json)", "text").action(async (jobId, options) => {
+program.command("history <jobId>", { hidden: true }).description("Show verification history").option("-l, --limit <n>", "Limit entries", parseInt, 50).option("-f, --format <format>", "Output format (text|json)", "text").action(async (jobId, options) => {
   const g = globals();
   try {
     const client = getClient();
@@ -427,7 +953,7 @@ program.command("history <jobId>").description("Show verification history").opti
     handleError(error, g.json);
   }
 });
-program.command("toc <jobId>").description("Extract table of contents from PDF").option("--max-depth <n>", "Maximum TOC depth", parseInt).option("-f, --format <format>", "Output format (text|json|markdown)", "text").option("--watch", "Watch live extraction events via WebSocket").action(async (jobId, options) => {
+program.command("toc <jobId>", { hidden: true }).description("Extract table of contents from PDF").option("--max-depth <n>", "Maximum TOC depth", parseInt).option("-f, --format <format>", "Output format (text|json|markdown)", "text").option("--watch", "Watch live extraction events via WebSocket").action(async (jobId, options) => {
   const g = globals();
   try {
     const client = getClient();
@@ -441,5 +967,18 @@ program.command("toc <jobId>").description("Extract table of contents from PDF")
     handleError(error, g.json);
   }
 });
-program.parse();
+if (isDirectExecution()) {
+  void program.parseAsync();
+}
+export {
+  ADVANCED_COLLECTION_SUBCOMMANDS,
+  ADVANCED_COMMANDS,
+  CLI_VERSION,
+  COLLECTION_HELP_FOOTER,
+  PRIMARY_COLLECTION_SUBCOMMANDS,
+  PRIMARY_COMMANDS,
+  ROOT_HELP_FOOTER,
+  getMissingApiKeyMessage,
+  program
+};
 //# sourceMappingURL=bin.js.map