@robin7331/papyrus-cli 0.1.9 → 0.1.11

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,8 +5,8 @@ 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 { defaultOutputPath, formatDurationMs, isPdfPath, looksLikeFileOutput, parseConcurrency, parseFormat, resolveFolderOutputPath, truncate, validateOptionCombination } from "./cliHelpers.js";
+import { assertModelAvailable, convertPdf, listAvailableModels, UnknownModelError } from "./openaiPdfToMarkdown.js";
+import { defaultOutputPath, formatDurationMs, getSpinnerFrame, isPdfPath, looksLikeFileOutput, parseConcurrency, parseFormat, resolveFolderOutputPath, truncate, validateOptionCombination } from "./cliHelpers.js";
 const program = new Command();
 const configFilePath = getConfigFilePath();
 const OPENAI_API_KEYS_URL = "https://platform.openai.com/settings/organization/api-keys";
@@ -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;
@@ -434,17 +446,20 @@ async function runWithConcurrency(items, concurrency, worker) {
     await Promise.all(workers);
 }
 class AsciiWorkerDashboard {
+    static spinnerIntervalMs = 80;
     lanes;
     total;
     workerCount;
     completed = 0;
     failed = 0;
     renderedLineCount = 0;
+    spinnerTimer;
     constructor(total, workerCount) {
         this.total = total;
         this.workerCount = workerCount;
         this.lanes = Array.from({ length: workerCount }, () => ({
-            state: "idle"
+            state: "idle",
+            spinnerFrame: 0
         }));
         process.stdout.write("\x1b[?25l");
         this.render();
@@ -462,6 +477,8 @@ class AsciiWorkerDashboard {
         lane.state = "running";
         lane.file = file;
         lane.message = "processing...";
+        lane.spinnerFrame = 0;
+        this.syncSpinnerTimer();
         this.render();
     }
     setWorkerDone(workerId, file, message) {
@@ -472,6 +489,8 @@ class AsciiWorkerDashboard {
         lane.state = "done";
         lane.file = file;
         lane.message = message;
+        lane.spinnerFrame = 0;
+        this.syncSpinnerTimer();
         this.render();
     }
     setWorkerFailed(workerId, file, message) {
@@ -482,9 +501,12 @@ class AsciiWorkerDashboard {
         lane.state = "failed";
         lane.file = file;
         lane.message = message;
+        lane.spinnerFrame = 0;
+        this.syncSpinnerTimer();
         this.render();
     }
     stop() {
+        this.clearSpinnerTimer();
         this.render();
         process.stdout.write("\x1b[?25h");
     }
@@ -515,7 +537,7 @@ class AsciiWorkerDashboard {
     }
     renderIcon(lane) {
         if (lane.state === "running") {
-            return ">>";
+            return `${getSpinnerFrame(lane.spinnerFrame)} `;
         }
         if (lane.state === "done") {
             return "OK";
@@ -525,6 +547,41 @@ class AsciiWorkerDashboard {
         }
         return "..";
     }
+    syncSpinnerTimer() {
+        if (this.lanes.some((lane) => lane.state === "running")) {
+            this.ensureSpinnerTimer();
+            return;
+        }
+        this.clearSpinnerTimer();
+    }
+    ensureSpinnerTimer() {
+        if (this.spinnerTimer) {
+            return;
+        }
+        this.spinnerTimer = setInterval(() => {
+            let hasRunningLane = false;
+            for (const lane of this.lanes) {
+                if (lane.state !== "running") {
+                    continue;
+                }
+                lane.spinnerFrame += 1;
+                hasRunningLane = true;
+            }
+            if (!hasRunningLane) {
+                this.clearSpinnerTimer();
+                return;
+            }
+            this.render();
+        }, AsciiWorkerDashboard.spinnerIntervalMs);
+        this.spinnerTimer.unref?.();
+    }
+    clearSpinnerTimer() {
+        if (!this.spinnerTimer) {
+            return;
+        }
+        clearInterval(this.spinnerTimer);
+        this.spinnerTimer = undefined;
+    }
 }
 async function confirmFolderProcessing(totalFiles, concurrency, skipPrompt) {
     if (skipPrompt) {
@@ -569,6 +626,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;
@@ -16,4 +17,6 @@ export declare function resolveFolderOutputPath(inputPath: string, inputRoot: st
 export declare function isPdfPath(inputPath: string): boolean;
 export declare function looksLikeFileOutput(outputPath: string): boolean;
 export declare function truncate(value: string, maxLength: number): string;
+export declare const ASCII_SPINNER_FRAMES: string[];
+export declare function getSpinnerFrame(frameIndex: number): string;
 export declare function formatDurationMs(durationMs: number): string;

package/dist/cliHelpers.js

@@ -63,6 +63,12 @@ export function truncate(value, maxLength) {
     }
     return `${value.slice(0, maxLength - 3)}...`;
 }
+export const ASCII_SPINNER_FRAMES = ["|", "/", "-", "\\"];
+export function getSpinnerFrame(frameIndex) {
+    const normalizedIndex = ((Math.trunc(frameIndex) % ASCII_SPINNER_FRAMES.length) + ASCII_SPINNER_FRAMES.length)
+        % ASCII_SPINNER_FRAMES.length;
+    return ASCII_SPINNER_FRAMES[normalizedIndex] ?? ASCII_SPINNER_FRAMES[0];
+}
 export function formatDurationMs(durationMs) {
     return `${(durationMs / 1000).toFixed(2)}s`;
 }

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.11",
   "private": false,
   "description": "Convert PDF to markdown or text with the OpenAI Agents SDK",
   "repository": {
@@ -37,7 +37,6 @@
   },
   "dependencies": {
     "@openai/agents": "^0.5.3",
-    "@robin7331/papyrus-cli": "^0.1.4",
     "commander": "^14.0.0",
     "dotenv": "^17.3.1",
     "openai": "^6.7.0",

package/src/cli.ts

@@ -13,13 +13,17 @@ import {
   setStoredApiKey
 } from "./config.js";
 import {
+  assertModelAvailable,
   convertPdf,
   type ConversionMode,
-  type ConvertUsage
+  type ConvertUsage,
+  listAvailableModels,
+  UnknownModelError
 } from "./openaiPdfToMarkdown.js";
 import {
   defaultOutputPath,
   formatDurationMs,
+  getSpinnerFrame,
   isPdfPath,
   looksLikeFileOutput,
   parseConcurrency,
@@ -43,9 +47,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 +64,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 +105,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 +185,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 +278,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;
@@ -587,21 +606,25 @@ type WorkerLane = {
   state: "idle" | "running" | "done" | "failed";
   file?: string;
   message?: string;
+  spinnerFrame: number;
 };
 
 class AsciiWorkerDashboard {
+  private static readonly spinnerIntervalMs = 80;
   private readonly lanes: WorkerLane[];
   private readonly total: number;
   private readonly workerCount: number;
   private completed = 0;
   private failed = 0;
   private renderedLineCount = 0;
+  private spinnerTimer?: NodeJS.Timeout;
 
   constructor(total: number, workerCount: number) {
     this.total = total;
     this.workerCount = workerCount;
     this.lanes = Array.from({ length: workerCount }, () => ({
-      state: "idle"
+      state: "idle",
+      spinnerFrame: 0
     }));
 
     process.stdout.write("\x1b[?25l");
@@ -623,6 +646,8 @@ class AsciiWorkerDashboard {
     lane.state = "running";
     lane.file = file;
     lane.message = "processing...";
+    lane.spinnerFrame = 0;
+    this.syncSpinnerTimer();
     this.render();
   }
 
@@ -635,6 +660,8 @@ class AsciiWorkerDashboard {
     lane.state = "done";
     lane.file = file;
     lane.message = message;
+    lane.spinnerFrame = 0;
+    this.syncSpinnerTimer();
     this.render();
   }
 
@@ -647,10 +674,13 @@ class AsciiWorkerDashboard {
     lane.state = "failed";
     lane.file = file;
     lane.message = message;
+    lane.spinnerFrame = 0;
+    this.syncSpinnerTimer();
     this.render();
   }
 
   stop(): void {
+    this.clearSpinnerTimer();
     this.render();
     process.stdout.write("\x1b[?25h");
   }
@@ -688,7 +718,7 @@ class AsciiWorkerDashboard {
 
   private renderIcon(lane: WorkerLane): string {
     if (lane.state === "running") {
-      return ">>";
+      return `${getSpinnerFrame(lane.spinnerFrame)} `;
     }
 
     if (lane.state === "done") {
@@ -701,6 +731,50 @@ class AsciiWorkerDashboard {
 
     return "..";
   }
+
+  private syncSpinnerTimer(): void {
+    if (this.lanes.some((lane) => lane.state === "running")) {
+      this.ensureSpinnerTimer();
+      return;
+    }
+
+    this.clearSpinnerTimer();
+  }
+
+  private ensureSpinnerTimer(): void {
+    if (this.spinnerTimer) {
+      return;
+    }
+
+    this.spinnerTimer = setInterval(() => {
+      let hasRunningLane = false;
+      for (const lane of this.lanes) {
+        if (lane.state !== "running") {
+          continue;
+        }
+
+        lane.spinnerFrame += 1;
+        hasRunningLane = true;
+      }
+
+      if (!hasRunningLane) {
+        this.clearSpinnerTimer();
+        return;
+      }
+
+      this.render();
+    }, AsciiWorkerDashboard.spinnerIntervalMs);
+    this.spinnerTimer.unref?.();
+  }
+
+  private clearSpinnerTimer(): void {
+    if (!this.spinnerTimer) {
+      return;
+    }
+
+    clearInterval(this.spinnerTimer);
+    this.spinnerTimer = undefined;
+  }
 }
 
 async function confirmFolderProcessing(
@@ -765,6 +839,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;
@@ -99,6 +100,14 @@ export function truncate(value: string, maxLength: number): string {
   return `${value.slice(0, maxLength - 3)}...`;
 }
 
+export const ASCII_SPINNER_FRAMES = ["|", "/", "-", "\\"];
+
+export function getSpinnerFrame(frameIndex: number): string {
+  const normalizedIndex = ((Math.trunc(frameIndex) % ASCII_SPINNER_FRAMES.length) + ASCII_SPINNER_FRAMES.length)
+    % ASCII_SPINNER_FRAMES.length;
+  return ASCII_SPINNER_FRAMES[normalizedIndex] ?? ASCII_SPINNER_FRAMES[0];
+}
+
 export function formatDurationMs(durationMs: number): string {
   return `${(durationMs / 1000).toFixed(2)}s`;
 }

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();
 

package/test/cliHelpers.test.ts

@@ -2,8 +2,10 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import { InvalidArgumentError } from "commander";
 import {
+  ASCII_SPINNER_FRAMES,
   defaultOutputPath,
   formatDurationMs,
+  getSpinnerFrame,
   isPdfPath,
   looksLikeFileOutput,
   parseConcurrency,
@@ -130,6 +132,15 @@ test("truncate shortens long values and preserves short ones", () => {
   assert.equal(truncate("abcdefghij", 8), "abcde...");
 });
 
+test("getSpinnerFrame cycles through the configured ASCII frames", () => {
+  assert.deepEqual(
+    ASCII_SPINNER_FRAMES.map((_, index) => getSpinnerFrame(index)),
+    ASCII_SPINNER_FRAMES
+  );
+  assert.equal(getSpinnerFrame(ASCII_SPINNER_FRAMES.length), ASCII_SPINNER_FRAMES[0]);
+  assert.equal(getSpinnerFrame(-1), ASCII_SPINNER_FRAMES.at(-1));
+});
+
 test("formatDurationMs formats to seconds with two decimals", () => {
   assert.equal(formatDurationMs(0), "0.00s");
   assert.equal(formatDurationMs(1543), "1.54s");