@robin7331/papyrus-cli 0.1.9 → 0.1.10

package/README.md

@@ -27,6 +27,9 @@ papyrus --help
 # Show installed CLI version
 papyrus --version
 
+# List available models for the current API key
+papyrus --models
+
 # Single file (default behavior; if no API key is found, Papyrus prompts you to paste one)
 papyrus ./path/to/input.pdf
 
@@ -88,9 +91,10 @@ papyrus config clear
 
 ## Arguments Reference
 
-### `<input>`
+### `[input]`
 
 Path to a single PDF file or a folder containing PDFs (processed recursively).
+Required unless you use `--models`.
 
 Example:
 
@@ -165,6 +169,7 @@ papyrus ./docs/invoice.pdf --prompt-file ./my-prompt.txt
 ### `-m, --model <model>`
 
 OpenAI model name used for conversion. Default is `gpt-4o-mini`.
+If the selected model is not available, Papyrus prints the available model IDs before exiting.
 
 Example:
 
@@ -172,6 +177,16 @@ Example:
 papyrus ./docs/invoice.pdf --model gpt-4.1-mini
 ```
 
+### `--models`
+
+Lists the available OpenAI model IDs for the current API key and exits.
+
+Example:
+
+```bash
+papyrus --models
+```
+
 ### `--concurrency <n>`
 
 Maximum parallel workers for folder input. Must be an integer between `1` and `100`. Default is `10`.

package/dist/cli.js

@@ -5,7 +5,7 @@ import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
 import { Command } from "commander";
 import { clearStoredApiKey, getConfigFilePath, getStoredApiKey, maskApiKey, setStoredApiKey } from "./config.js";
-import { convertPdf } from "./openaiPdfToMarkdown.js";
+import { assertModelAvailable, convertPdf, listAvailableModels, UnknownModelError } from "./openaiPdfToMarkdown.js";
 import { defaultOutputPath, formatDurationMs, isPdfPath, looksLikeFileOutput, parseConcurrency, parseFormat, resolveFolderOutputPath, truncate, validateOptionCombination } from "./cliHelpers.js";
 const program = new Command();
 const configFilePath = getConfigFilePath();
@@ -15,9 +15,10 @@ program
     .name("papyrus")
     .version(cliVersion, "-v, --version", "display version number")
     .description("Convert PDF files to Markdown or text using the OpenAI Agents SDK")
-    .argument("<input>", "Path to input PDF file or folder")
+    .argument("[input]", "Path to input PDF file or folder")
     .option("-o, --output <path>", "Path to output file (single input) or output directory (folder input)")
     .option("-m, --model <model>", "OpenAI model to use", "gpt-4o-mini")
+    .option("--models", "List available OpenAI models for the current API key and exit")
     .option("--concurrency <n>", "Max parallel workers for folder input (default: 10)", parseConcurrency)
     .option("-y, --yes", "Skip confirmation prompt in folder mode")
     .option("--format <format>", "Output file extension override (for example: md, txt, csv, json)", parseFormat)
@@ -25,13 +26,26 @@ program
     .option("--prompt <text>", "Custom prompt text (enables prompt mode)")
     .option("--prompt-file <path>", "Path to file containing prompt text (enables prompt mode)")
     .action(async (input, options) => {
-    const inputPath = resolve(input);
     const startedAt = Date.now();
     try {
+        if (options.models) {
+            await ensureApiKey();
+            printAvailableModels(await listAvailableModels());
+            return;
+        }
+        if (!input) {
+            throw new Error('Input path is required unless "--models" is used.');
+        }
+        const inputPath = resolve(input);
         validateOptionCombination(options);
         const promptText = await resolvePromptText(options);
         const conversionMode = resolveConversionMode(promptText);
         const inputKind = await detectInputKind(inputPath);
+        if (inputKind === "file" && !isPdfPath(inputPath)) {
+            throw new Error("Input file must have a .pdf extension.");
+        }
+        await ensureApiKey();
+        await assertModelAvailable(options.model);
         let usageTotals = emptyUsage();
         if (inputKind === "file") {
             usageTotals = await processSingleFile(inputPath, options, conversionMode, promptText);
@@ -47,6 +61,9 @@ program
         console.log(`Duration: ${((Date.now() - startedAt) / 1000).toFixed(2)}s`);
     }
     catch (error) {
+        if (error instanceof UnknownModelError) {
+            printAvailableModels(error.availableModels);
+        }
         const message = error instanceof Error ? error.message : String(error);
         console.error(`Conversion failed: ${message}`);
         console.error(`Duration: ${((Date.now() - startedAt) / 1000).toFixed(2)}s`);
@@ -113,10 +130,6 @@ program.parseAsync(process.argv).catch((error) => {
     process.exitCode = 1;
 });
 async function processSingleFile(inputPath, options, mode, promptText) {
-    if (!isPdfPath(inputPath)) {
-        throw new Error("Input file must have a .pdf extension.");
-    }
-    await ensureApiKey();
     const startedAt = Date.now();
     const displayInput = relative(process.cwd(), inputPath) || inputPath;
     const workerDashboard = process.stdout.isTTY
@@ -179,7 +192,6 @@ async function processFolder(inputDir, options, mode, promptText) {
         console.log("Cancelled. No files were processed.");
         return { total: files.length, succeeded: 0, failed: 0, cancelled: true, usage: emptyUsage() };
     }
-    await ensureApiKey();
     const outputRoot = options.output ? resolve(options.output) : undefined;
     let succeeded = 0;
     let failed = 0;
@@ -569,6 +581,12 @@ function mergeUsage(target, delta) {
 function printUsageTotals(usage) {
     console.log(`Token usage: input=${usage.inputTokens}, output=${usage.outputTokens}, total=${usage.totalTokens}, requests=${usage.requests}`);
 }
+function printAvailableModels(models) {
+    console.log(`Available models (${models.length}):`);
+    for (const model of models) {
+        console.log(model);
+    }
+}
 function getCliVersion() {
     try {
         const packageJsonPath = new URL("../package.json", import.meta.url);

package/dist/cliHelpers.d.ts

@@ -1,6 +1,7 @@
 export type CliOptions = {
     output?: string;
     model: string;
+    models?: boolean;
     concurrency?: number;
     yes?: boolean;
     format?: string;

package/dist/openaiPdfToMarkdown.d.ts

@@ -1,3 +1,4 @@
+import OpenAI from "openai";
 export type ConvertOptions = {
     inputPath: string;
     model: string;
@@ -19,4 +20,11 @@ export type ConvertUsage = {
     outputTokens: number;
     totalTokens: number;
 };
+export declare class UnknownModelError extends Error {
+    readonly model: string;
+    readonly availableModels: string[];
+    constructor(model: string, availableModels: string[]);
+}
 export declare function convertPdf(options: ConvertOptions): Promise<ConvertResult>;
+export declare function assertModelAvailable(model: string): Promise<void>;
+export declare function listAvailableModels(client?: OpenAI): Promise<string[]>;

package/dist/openaiPdfToMarkdown.js

@@ -4,6 +4,16 @@ import { resolve } from "node:path";
 import { Agent, run } from "@openai/agents";
 import OpenAI from "openai";
 import { z } from "zod";
+export class UnknownModelError extends Error {
+    model;
+    availableModels;
+    constructor(model, availableModels) {
+        super(`Model "${model}" is not available for this API key.`);
+        this.name = "UnknownModelError";
+        this.model = model;
+        this.availableModels = availableModels;
+    }
+}
 const AUTO_RESPONSE_SCHEMA = z.object({
     format: z.enum(["md", "txt"]),
     content: z.string().min(1)
@@ -14,11 +24,7 @@ const RATE_LIMIT_MAX_DELAY_MS = parsePositiveIntEnv("PAPYRUS_RATE_LIMIT_MAX_DELA
 export async function convertPdf(options) {
     const inputPath = resolve(options.inputPath);
     await access(inputPath);
-    const apiKey = process.env.OPENAI_API_KEY;
-    if (!apiKey) {
-        throw new Error("OPENAI_API_KEY is not set.");
-    }
-    const client = new OpenAI({ apiKey });
+    const client = createOpenAiClient();
     const uploaded = await withRateLimitRetry("file upload", () => client.files.create({
         file: createReadStream(inputPath),
         purpose: "user_data"
@@ -29,21 +35,30 @@ export async function convertPdf(options) {
         model: options.model
     });
     const promptText = buildPromptText(options);
-    const result = await withRateLimitRetry("model run", () => run(agent, [
-        {
-            role: "user",
-            content: [
-                {
-                    type: "input_text",
-                    text: promptText
-                },
-                {
-                    type: "input_file",
-                    file: { id: uploaded.id }
-                }
-            ]
+    let result;
+    try {
+        result = await withRateLimitRetry("model run", () => run(agent, [
+            {
+                role: "user",
+                content: [
+                    {
+                        type: "input_text",
+                        text: promptText
+                    },
+                    {
+                        type: "input_file",
+                        file: { id: uploaded.id }
+                    }
+                ]
+            }
+        ]));
+    }
+    catch (error) {
+        if (isUnknownModelError(error, options.model)) {
+            throw new UnknownModelError(options.model, await listAvailableModels(client));
         }
-    ]));
+        throw error;
+    }
     const rawOutput = (result.finalOutput ?? "").trim();
     if (!rawOutput) {
         throw new Error("No content returned by the API.");
@@ -59,6 +74,32 @@ export async function convertPdf(options) {
     }
     return { format: "txt", content: rawOutput, usage };
 }
+export async function assertModelAvailable(model) {
+    const client = createOpenAiClient();
+    try {
+        await client.models.retrieve(model);
+    }
+    catch (error) {
+        if (!isUnknownModelError(error, model)) {
+            throw error;
+        }
+        throw new UnknownModelError(model, await listAvailableModels(client));
+    }
+}
+export async function listAvailableModels(client = createOpenAiClient()) {
+    const modelIds = [];
+    for await (const model of client.models.list()) {
+        modelIds.push(model.id);
+    }
+    return modelIds.sort((left, right) => left.localeCompare(right, "en"));
+}
+function createOpenAiClient() {
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+        throw new Error("OPENAI_API_KEY is not set.");
+    }
+    return new OpenAI({ apiKey });
+}
 function buildPromptText(options) {
     const outputExtensionHint = normalizeExtensionHint(options.outputExtensionHint);
     if (options.mode === "prompt") {
@@ -111,6 +152,20 @@ function normalizeExtensionHint(extension) {
     const normalized = extension.trim().replace(/^\.+/, "");
     return normalized || undefined;
 }
+function isUnknownModelError(error, model) {
+    const message = error instanceof Error ? error.message : String(error);
+    const normalizedMessage = message.toLowerCase();
+    const errorStatus = typeof error === "object" && error !== null && "status" in error ? error.status : undefined;
+    const errorCode = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+    const quotedModel = model.toLowerCase();
+    if (errorStatus === 404 || errorCode === "model_not_found") {
+        return true;
+    }
+    return (normalizedMessage.includes(quotedModel) &&
+        (normalizedMessage.includes("does not exist") ||
+            normalizedMessage.includes("not found") ||
+            normalizedMessage.includes("unknown model")));
+}
 function parseAutoResponse(rawOutput) {
     let candidate = rawOutput.trim();
     const fencedMatch = candidate.match(/```(?:json)?\s*([\s\S]*?)```/i);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robin7331/papyrus-cli",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "private": false,
   "description": "Convert PDF to markdown or text with the OpenAI Agents SDK",
   "repository": {

package/src/cli.ts

@@ -13,9 +13,12 @@ import {
   setStoredApiKey
 } from "./config.js";
 import {
+  assertModelAvailable,
   convertPdf,
   type ConversionMode,
-  type ConvertUsage
+  type ConvertUsage,
+  listAvailableModels,
+  UnknownModelError
 } from "./openaiPdfToMarkdown.js";
 import {
   defaultOutputPath,
@@ -43,9 +46,10 @@ program
   .name("papyrus")
   .version(cliVersion, "-v, --version", "display version number")
   .description("Convert PDF files to Markdown or text using the OpenAI Agents SDK")
-  .argument("<input>", "Path to input PDF file or folder")
+  .argument("[input]", "Path to input PDF file or folder")
   .option("-o, --output <path>", "Path to output file (single input) or output directory (folder input)")
   .option("-m, --model <model>", "OpenAI model to use", "gpt-4o-mini")
+  .option("--models", "List available OpenAI models for the current API key and exit")
   .option(
     "--concurrency <n>",
     "Max parallel workers for folder input (default: 10)",
@@ -59,16 +63,32 @@ program
   )
   .option("--prompt <text>", "Custom prompt text (enables prompt mode)")
   .option("--prompt-file <path>", "Path to file containing prompt text (enables prompt mode)")
-  .action(async (input: string, options: CliOptions) => {
-    const inputPath = resolve(input);
+  .action(async (input: string | undefined, options: CliOptions) => {
     const startedAt = Date.now();
 
     try {
+      if (options.models) {
+        await ensureApiKey();
+        printAvailableModels(await listAvailableModels());
+        return;
+      }
+
+      if (!input) {
+        throw new Error('Input path is required unless "--models" is used.');
+      }
+
+      const inputPath = resolve(input);
       validateOptionCombination(options);
 
       const promptText = await resolvePromptText(options);
       const conversionMode = resolveConversionMode(promptText);
       const inputKind = await detectInputKind(inputPath);
+      if (inputKind === "file" && !isPdfPath(inputPath)) {
+        throw new Error("Input file must have a .pdf extension.");
+      }
+
+      await ensureApiKey();
+      await assertModelAvailable(options.model);
       let usageTotals: ConvertUsage = emptyUsage();
 
       if (inputKind === "file") {
@@ -84,6 +104,10 @@ program
       printUsageTotals(usageTotals);
       console.log(`Duration: ${((Date.now() - startedAt) / 1000).toFixed(2)}s`);
     } catch (error) {
+      if (error instanceof UnknownModelError) {
+        printAvailableModels(error.availableModels);
+      }
+
       const message = error instanceof Error ? error.message : String(error);
       console.error(`Conversion failed: ${message}`);
       console.error(`Duration: ${((Date.now() - startedAt) / 1000).toFixed(2)}s`);
@@ -160,11 +184,6 @@ async function processSingleFile(
   mode: ConversionMode,
   promptText?: string
 ): Promise<ConvertUsage> {
-  if (!isPdfPath(inputPath)) {
-    throw new Error("Input file must have a .pdf extension.");
-  }
-
-  await ensureApiKey();
   const startedAt = Date.now();
   const displayInput = relative(process.cwd(), inputPath) || inputPath;
   const workerDashboard = process.stdout.isTTY
@@ -258,7 +277,6 @@ async function processFolder(
     return { total: files.length, succeeded: 0, failed: 0, cancelled: true, usage: emptyUsage() };
   }
 
-  await ensureApiKey();
   const outputRoot = options.output ? resolve(options.output) : undefined;
   let succeeded = 0;
   let failed = 0;
@@ -765,6 +783,13 @@ function printUsageTotals(usage: ConvertUsage): void {
   );
 }
 
+function printAvailableModels(models: string[]): void {
+  console.log(`Available models (${models.length}):`);
+  for (const model of models) {
+    console.log(model);
+  }
+}
+
 function getCliVersion(): string {
   try {
     const packageJsonPath = new URL("../package.json", import.meta.url);

package/src/cliHelpers.ts

@@ -4,6 +4,7 @@ import { basename, dirname, extname, join, relative } from "node:path";
 export type CliOptions = {
   output?: string;
   model: string;
+  models?: boolean;
   concurrency?: number;
   yes?: boolean;
   format?: string;

package/src/openaiPdfToMarkdown.ts

@@ -30,6 +30,18 @@ export type ConvertUsage = {
   totalTokens: number;
 };
 
+export class UnknownModelError extends Error {
+  readonly model: string;
+  readonly availableModels: string[];
+
+  constructor(model: string, availableModels: string[]) {
+    super(`Model "${model}" is not available for this API key.`);
+    this.name = "UnknownModelError";
+    this.model = model;
+    this.availableModels = availableModels;
+  }
+}
+
 const AUTO_RESPONSE_SCHEMA = z.object({
   format: z.enum(["md", "txt"]),
   content: z.string().min(1)
@@ -43,12 +55,7 @@ export async function convertPdf(options: ConvertOptions): Promise<ConvertResult
   const inputPath = resolve(options.inputPath);
   await access(inputPath);
 
-  const apiKey = process.env.OPENAI_API_KEY;
-  if (!apiKey) {
-    throw new Error("OPENAI_API_KEY is not set.");
-  }
-
-  const client = new OpenAI({ apiKey });
+  const client = createOpenAiClient();
 
   const uploaded = await withRateLimitRetry("file upload", () =>
     client.files.create({
@@ -64,23 +71,32 @@ export async function convertPdf(options: ConvertOptions): Promise<ConvertResult
   });
 
   const promptText = buildPromptText(options);
-  const result = await withRateLimitRetry("model run", () =>
-    run(agent, [
-      {
-        role: "user",
-        content: [
-          {
-            type: "input_text",
-            text: promptText
-          },
-          {
-            type: "input_file",
-            file: { id: uploaded.id }
-          }
-        ]
-      }
-    ])
-  );
+  let result;
+  try {
+    result = await withRateLimitRetry("model run", () =>
+      run(agent, [
+        {
+          role: "user",
+          content: [
+            {
+              type: "input_text",
+              text: promptText
+            },
+            {
+              type: "input_file",
+              file: { id: uploaded.id }
+            }
+          ]
+        }
+      ])
+    );
+  } catch (error) {
+    if (isUnknownModelError(error, options.model)) {
+      throw new UnknownModelError(options.model, await listAvailableModels(client));
+    }
+
+    throw error;
+  }
 
   const rawOutput = (result.finalOutput ?? "").trim();
   if (!rawOutput) {
@@ -101,6 +117,39 @@ export async function convertPdf(options: ConvertOptions): Promise<ConvertResult
   return { format: "txt", content: rawOutput, usage };
 }
 
+export async function assertModelAvailable(model: string): Promise<void> {
+  const client = createOpenAiClient();
+
+  try {
+    await client.models.retrieve(model);
+  } catch (error) {
+    if (!isUnknownModelError(error, model)) {
+      throw error;
+    }
+
+    throw new UnknownModelError(model, await listAvailableModels(client));
+  }
+}
+
+export async function listAvailableModels(client = createOpenAiClient()): Promise<string[]> {
+  const modelIds: string[] = [];
+
+  for await (const model of client.models.list()) {
+    modelIds.push(model.id);
+  }
+
+  return modelIds.sort((left, right) => left.localeCompare(right, "en"));
+}
+
+function createOpenAiClient(): OpenAI {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) {
+    throw new Error("OPENAI_API_KEY is not set.");
+  }
+
+  return new OpenAI({ apiKey });
+}
+
 function buildPromptText(options: ConvertOptions): string {
   const outputExtensionHint = normalizeExtensionHint(options.outputExtensionHint);
   if (options.mode === "prompt") {
@@ -171,6 +220,27 @@ function normalizeExtensionHint(extension: string | undefined): string | undefin
   return normalized || undefined;
 }
 
+function isUnknownModelError(error: unknown, model: string): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  const normalizedMessage = message.toLowerCase();
+  const errorStatus =
+    typeof error === "object" && error !== null && "status" in error ? error.status : undefined;
+  const errorCode =
+    typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+  const quotedModel = model.toLowerCase();
+
+  if (errorStatus === 404 || errorCode === "model_not_found") {
+    return true;
+  }
+
+  return (
+    normalizedMessage.includes(quotedModel) &&
+    (normalizedMessage.includes("does not exist") ||
+      normalizedMessage.includes("not found") ||
+      normalizedMessage.includes("unknown model"))
+  );
+}
+
 function parseAutoResponse(rawOutput: string): Omit<ConvertResult, "usage"> {
   let candidate = rawOutput.trim();