@robin7331/papyrus-cli 0.1.7 → 0.1.9

package/README.md

@@ -30,7 +30,7 @@ papyrus --version
 # Single file (default behavior; if no API key is found, Papyrus prompts you to paste one)
 papyrus ./path/to/input.pdf
 
-# Single file with explicit format/output/model
+# Single file with explicit output extension/output/model
 papyrus ./path/to/input.pdf --format md --output ./out/result.md --model gpt-4o-mini
 
 # Default conversion with extra instructions
@@ -110,14 +110,14 @@ papyrus --version
 
 ### `--format <format>`
 
-Output format override:
-- `md` for GitHub-flavored Markdown
-- `txt` for plain text
+Output file extension override. Any extension is allowed (for example `md`, `txt`, `csv`, `json`).
+This flag controls the output filename extension only.
+When provided, Papyrus also passes the extension as a guidance hint to the model.
 
 Example:
 
 ```bash
-papyrus ./docs/invoice.pdf --format md
+papyrus ./docs/invoice.pdf --format csv
 ```
 
 ### `-o, --output <path>`
@@ -194,8 +194,10 @@ papyrus ./docs --yes
 
 ## Notes
 
-- In default conversion (without `--prompt`/`--prompt-file`) and without `--format`, the model returns structured JSON with `format` + `content`.
-- Single-file input now also shows a live worker lane (spinner in TTY) while conversion is running.
+- In default conversion (without `--prompt`/`--prompt-file`), the model returns structured JSON with `format` + `content`.
+- Without `--format`, output extension follows model-selected content format (`.md` or `.txt`).
+- With `--format`, only the output extension changes.
+- Single-file input now also shows a live worker lane in TTY while conversion is running.
 - Folder input is scanned recursively for `.pdf` files and processed in parallel.
 - In folder mode, `--output` must be a directory path and mirrored subfolders are preserved.
 - OpenAI rate-limit (`429`) responses are retried automatically using `Retry-After` (when present) plus exponential backoff.

package/dist/cli.js

@@ -20,7 +20,7 @@ program
     .option("-m, --model <model>", "OpenAI model to use", "gpt-4o-mini")
     .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 format override: md or txt", parseFormat)
+    .option("--format <format>", "Output file extension override (for example: md, txt, csv, json)", parseFormat)
     .option("--instructions <text>", "Additional conversion instructions (only when not using --prompt/--prompt-file)")
     .option("--prompt <text>", "Custom prompt text (enables prompt mode)")
     .option("--prompt-file <path>", "Path to file containing prompt text (enables prompt mode)")
@@ -132,21 +132,22 @@ async function processSingleFile(inputPath, options, mode, promptText) {
             inputPath,
             model: options.model,
             mode,
-            format: options.format,
             instructions: options.instructions,
-            promptText
+            promptText,
+            outputExtensionHint: options.format
         });
-        const outputPath = resolve(options.output ?? defaultOutputPath(inputPath, result.format));
+        const outputExtension = options.format ?? result.format;
+        const outputPath = resolve(options.output ?? defaultOutputPath(inputPath, outputExtension));
         await mkdir(dirname(outputPath), { recursive: true });
         await writeFile(outputPath, result.content, "utf8");
         if (workerDashboard) {
-            workerDashboard.setWorkerDone(0, displayInput, `${result.format} in ${formatDurationMs(Date.now() - startedAt)}`);
+            workerDashboard.setWorkerDone(0, displayInput, `${outputExtension} in ${formatDurationMs(Date.now() - startedAt)}`);
             workerDashboard.setSummary(1, 0);
         }
         else {
-            console.log(`[worker-1] Done ${displayInput} -> ${outputPath} (${result.format}, ${formatDurationMs(Date.now() - startedAt)})`);
+            console.log(`[worker-1] Done ${displayInput} -> ${outputPath} (${outputExtension}, ${formatDurationMs(Date.now() - startedAt)})`);
         }
-        console.log(`Output (${result.format}) written to: ${outputPath}`);
+        console.log(`Output (.${outputExtension}) written to: ${outputPath}`);
         return result.usage;
     }
     catch (error) {
@@ -166,7 +167,7 @@ async function processSingleFile(inputPath, options, mode, promptText) {
 }
 async function processFolder(inputDir, options, mode, promptText) {
     if (options.output && looksLikeFileOutput(options.output)) {
-        throw new Error("In folder mode, --output must be a directory path (not a .md/.txt file path).");
+        throw new Error("In folder mode, --output must be a directory path.");
     }
     const files = await collectPdfFiles(inputDir);
     if (files.length === 0) {
@@ -201,20 +202,21 @@ async function processFolder(inputDir, options, mode, promptText) {
                     inputPath: filePath,
                     model: options.model,
                     mode,
-                    format: options.format,
                     instructions: options.instructions,
-                    promptText
+                    promptText,
+                    outputExtensionHint: options.format
                 });
-                const outputPath = resolveFolderOutputPath(filePath, inputDir, outputRoot, result.format);
+                const outputExtension = options.format ?? result.format;
+                const outputPath = resolveFolderOutputPath(filePath, inputDir, outputRoot, outputExtension);
                 await mkdir(dirname(outputPath), { recursive: true });
                 await writeFile(outputPath, result.content, "utf8");
                 succeeded += 1;
                 mergeUsage(usage, result.usage);
                 if (workerDashboard) {
-                    workerDashboard.setWorkerDone(workerId, relativeInput, `${result.format} in ${formatDurationMs(Date.now() - startedAt)}`);
+                    workerDashboard.setWorkerDone(workerId, relativeInput, `${outputExtension} in ${formatDurationMs(Date.now() - startedAt)}`);
                 }
                 else {
-                    console.log(`[worker-${workerId + 1}] Done ${relativeInput} -> ${outputPath} (${result.format}, ${formatDurationMs(Date.now() - startedAt)})`);
+                    console.log(`[worker-${workerId + 1}] Done ${relativeInput} -> ${outputPath} (${outputExtension}, ${formatDurationMs(Date.now() - startedAt)})`);
                 }
             }
             catch (error) {
@@ -431,12 +433,10 @@ async function runWithConcurrency(items, concurrency, worker) {
     });
     await Promise.all(workers);
 }
-const SPINNER_FRAMES = ["-", "\\", "|", "/"];
 class AsciiWorkerDashboard {
     lanes;
     total;
     workerCount;
-    spinnerTimer;
     completed = 0;
     failed = 0;
     renderedLineCount = 0;
@@ -444,15 +444,10 @@ class AsciiWorkerDashboard {
         this.total = total;
         this.workerCount = workerCount;
         this.lanes = Array.from({ length: workerCount }, () => ({
-            state: "idle",
-            spinnerFrame: 0
+            state: "idle"
         }));
         process.stdout.write("\x1b[?25l");
         this.render();
-        this.spinnerTimer = setInterval(() => {
-            this.tickSpinners();
-            this.render();
-        }, 100);
     }
     setSummary(completed, failed) {
         this.completed = completed;
@@ -466,7 +461,7 @@ class AsciiWorkerDashboard {
         }
         lane.state = "running";
         lane.file = file;
-        lane.message = "processing";
+        lane.message = "processing...";
         this.render();
     }
     setWorkerDone(workerId, file, message) {
@@ -490,7 +485,6 @@ class AsciiWorkerDashboard {
         this.render();
     }
     stop() {
-        clearInterval(this.spinnerTimer);
         this.render();
         process.stdout.write("\x1b[?25h");
     }
@@ -519,17 +513,9 @@ class AsciiWorkerDashboard {
         }
         return lines;
     }
-    tickSpinners() {
-        for (const lane of this.lanes) {
-            if (lane.state !== "running") {
-                continue;
-            }
-            lane.spinnerFrame = (lane.spinnerFrame + 1) % SPINNER_FRAMES.length;
-        }
-    }
     renderIcon(lane) {
         if (lane.state === "running") {
-            return SPINNER_FRAMES[lane.spinnerFrame];
+            return ">>";
         }
         if (lane.state === "done") {
             return "OK";

package/dist/cliHelpers.d.ts

@@ -1,19 +1,18 @@
-import { type OutputFormat } from "./openaiPdfToMarkdown.js";
 export type CliOptions = {
     output?: string;
     model: string;
     concurrency?: number;
     yes?: boolean;
-    format?: OutputFormat;
+    format?: string;
     instructions?: string;
     prompt?: string;
     promptFile?: string;
 };
-export declare function parseFormat(value: string): OutputFormat;
+export declare function parseFormat(value: string): string;
 export declare function parseConcurrency(value: string): number;
 export declare function validateOptionCombination(options: CliOptions): void;
-export declare function defaultOutputPath(inputPath: string, format: OutputFormat): string;
-export declare function resolveFolderOutputPath(inputPath: string, inputRoot: string, outputRoot: string | undefined, format: OutputFormat): string;
+export declare function defaultOutputPath(inputPath: string, extension: string): string;
+export declare function resolveFolderOutputPath(inputPath: string, inputRoot: string, outputRoot: string | undefined, extension: string): string;
 export declare function isPdfPath(inputPath: string): boolean;
 export declare function looksLikeFileOutput(outputPath: string): boolean;
 export declare function truncate(value: string, maxLength: number): string;

package/dist/cliHelpers.js

@@ -1,10 +1,14 @@
 import { InvalidArgumentError } from "commander";
 import { basename, dirname, extname, join, relative } from "node:path";
 export function parseFormat(value) {
-    if (value === "md" || value === "txt") {
-        return value;
+    const normalized = value.trim().replace(/^\.+/, "");
+    if (!normalized) {
+        throw new InvalidArgumentError("Format must be a non-empty file extension.");
+    }
+    if (normalized.includes("/") || normalized.includes("\\")) {
+        throw new InvalidArgumentError("Format must be a file extension, not a path.");
     }
-    throw new InvalidArgumentError("Format must be either 'md' or 'txt'.");
+    return normalized;
 }
 export function parseConcurrency(value) {
     const parsed = Number(value);
@@ -22,21 +26,22 @@ export function validateOptionCombination(options) {
         throw new Error("--instructions cannot be combined with --prompt or --prompt-file.");
     }
 }
-export function defaultOutputPath(inputPath, format) {
-    const extension = format === "md" ? ".md" : ".txt";
+export function defaultOutputPath(inputPath, extension) {
+    const normalizedExtension = extension.startsWith(".") ? extension : `.${extension}`;
     if (extname(inputPath).toLowerCase() === ".pdf") {
-        return inputPath.slice(0, -4) + extension;
+        return inputPath.slice(0, -4) + normalizedExtension;
     }
-    return inputPath + extension;
+    return inputPath + normalizedExtension;
 }
-export function resolveFolderOutputPath(inputPath, inputRoot, outputRoot, format) {
+export function resolveFolderOutputPath(inputPath, inputRoot, outputRoot, extension) {
     if (!outputRoot) {
-        return defaultOutputPath(inputPath, format);
+        return defaultOutputPath(inputPath, extension);
     }
     const relativePath = relative(inputRoot, inputPath);
     const relativeDir = dirname(relativePath);
     const base = basename(relativePath, extname(relativePath));
-    const filename = `${base}.${format}`;
+    const normalizedExtension = extension.startsWith(".") ? extension.slice(1) : extension;
+    const filename = `${base}.${normalizedExtension}`;
     if (relativeDir === ".") {
         return join(outputRoot, filename);
     }

package/dist/openaiPdfToMarkdown.d.ts

@@ -2,9 +2,9 @@ export type ConvertOptions = {
     inputPath: string;
     model: string;
     mode: ConversionMode;
-    format?: OutputFormat;
     instructions?: string;
     promptText?: string;
+    outputExtensionHint?: string;
 };
 export type ConversionMode = "auto" | "prompt";
 export type OutputFormat = "md" | "txt";

package/dist/openaiPdfToMarkdown.js

@@ -54,13 +54,13 @@ export async function convertPdf(options) {
         outputTokens: result.state.usage.outputTokens,
         totalTokens: result.state.usage.totalTokens
     };
-    if (options.mode === "auto" && !options.format) {
+    if (options.mode === "auto") {
         return { ...parseAutoResponse(rawOutput), usage };
     }
-    const format = options.format ?? "txt";
-    return { format, content: rawOutput, usage };
+    return { format: "txt", content: rawOutput, usage };
 }
 function buildPromptText(options) {
+    const outputExtensionHint = normalizeExtensionHint(options.outputExtensionHint);
     if (options.mode === "prompt") {
         if (!options.promptText) {
             throw new Error("promptText is required when mode is 'prompt'.");
@@ -70,35 +70,16 @@ function buildPromptText(options) {
             "Return only the final converted content.",
             `User prompt:\n${options.promptText}`
         ];
-        if (options.format === "md") {
-            promptModeParts.push("Output format requirement: Return only GitHub-flavored Markdown.");
-        }
-        else if (options.format === "txt") {
-            promptModeParts.push("Output format requirement: Return plain text only and do not use Markdown syntax.");
-        }
-        else {
-            promptModeParts.push("If the prompt does not enforce a format, prefer plain text without Markdown syntax.");
+        if (outputExtensionHint) {
+            promptModeParts.push([
+                `Output file extension hint: .${outputExtensionHint}.`,
+                "Prefer content that is practical for saving under this extension.",
+                "Treat this as guidance and still follow the user prompt exactly."
+            ].join(" "));
         }
         return promptModeParts.join("\n\n");
     }
-    if (options.format === "md") {
-        return withAdditionalInstructions([
-            "Convert this PDF into clean GitHub-flavored Markdown.",
-            "Preserve headings, paragraphs, lists, and tables.",
-            "Render tables as Markdown pipe tables with header separators.",
-            "If cells are empty due to merged cells, keep the table readable and consistent.",
-            "Return only Markdown without code fences."
-        ].join(" "), options.instructions);
-    }
-    if (options.format === "txt") {
-        return withAdditionalInstructions([
-            "Convert this PDF into clean plain text.",
-            "Preserve reading order and paragraph boundaries.",
-            "Represent tables in readable plain text (no Markdown syntax).",
-            "Return plain text only and do not use Markdown syntax or code fences."
-        ].join(" "), options.instructions);
-    }
-    return withAdditionalInstructions([
+    let autoPrompt = withAdditionalInstructions([
         "Decide the best output format for this PDF: Markdown ('md') or plain text ('txt').",
         "Choose 'md' for documents with meaningful headings, lists, and tables that benefit from Markdown.",
         "Choose 'txt' for mostly linear text where Markdown adds little value.",
@@ -108,6 +89,14 @@ function buildPromptText(options) {
         "If format is 'txt', output plain text only and do not use Markdown syntax.",
         "Do not wrap the JSON in code fences."
     ].join("\n"), options.instructions);
+    if (outputExtensionHint) {
+        autoPrompt = `${autoPrompt}\n\n${[
+            `Output file extension hint: .${outputExtensionHint}.`,
+            "Prefer content that is practical for that extension while still returning JSON with format='md' or 'txt'.",
+            "This is guidance only and should not break the required JSON schema."
+        ].join(" ")}`;
+    }
+    return autoPrompt;
 }
 function withAdditionalInstructions(base, additional) {
     if (!additional) {
@@ -115,6 +104,13 @@ function withAdditionalInstructions(base, additional) {
     }
     return `${base}\n\nAdditional user instructions:\n${additional}`;
 }
+function normalizeExtensionHint(extension) {
+    if (!extension) {
+        return undefined;
+    }
+    const normalized = extension.trim().replace(/^\.+/, "");
+    return normalized || undefined;
+}
 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.7",
+  "version": "0.1.9",
   "private": false,
   "description": "Convert PDF to markdown or text with the OpenAI Agents SDK",
   "repository": {

package/src/cli.ts

@@ -52,7 +52,7 @@ program
     parseConcurrency
   )
   .option("-y, --yes", "Skip confirmation prompt in folder mode")
-  .option("--format <format>", "Output format override: md or txt", parseFormat)
+  .option("--format <format>", "Output file extension override (for example: md, txt, csv, json)", parseFormat)
   .option(
     "--instructions <text>",
     "Additional conversion instructions (only when not using --prompt/--prompt-file)"
@@ -182,12 +182,13 @@ async function processSingleFile(
       inputPath,
       model: options.model,
       mode,
-      format: options.format,
       instructions: options.instructions,
-      promptText
+      promptText,
+      outputExtensionHint: options.format
     });
 
-    const outputPath = resolve(options.output ?? defaultOutputPath(inputPath, result.format));
+    const outputExtension = options.format ?? result.format;
+    const outputPath = resolve(options.output ?? defaultOutputPath(inputPath, outputExtension));
     await mkdir(dirname(outputPath), { recursive: true });
     await writeFile(outputPath, result.content, "utf8");
 
@@ -195,16 +196,16 @@ async function processSingleFile(
       workerDashboard.setWorkerDone(
         0,
         displayInput,
-        `${result.format} in ${formatDurationMs(Date.now() - startedAt)}`
+        `${outputExtension} in ${formatDurationMs(Date.now() - startedAt)}`
       );
       workerDashboard.setSummary(1, 0);
     } else {
       console.log(
-        `[worker-1] Done ${displayInput} -> ${outputPath} (${result.format}, ${formatDurationMs(Date.now() - startedAt)})`
+        `[worker-1] Done ${displayInput} -> ${outputPath} (${outputExtension}, ${formatDurationMs(Date.now() - startedAt)})`
       );
     }
 
-    console.log(`Output (${result.format}) written to: ${outputPath}`);
+    console.log(`Output (.${outputExtension}) written to: ${outputPath}`);
     return result.usage;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -242,9 +243,7 @@ async function processFolder(
   promptText?: string
 ): Promise<FolderSummary> {
   if (options.output && looksLikeFileOutput(options.output)) {
-    throw new Error(
-      "In folder mode, --output must be a directory path (not a .md/.txt file path)."
-    );
+    throw new Error("In folder mode, --output must be a directory path.");
   }
 
   const files = await collectPdfFiles(inputDir);
@@ -285,12 +284,13 @@ async function processFolder(
           inputPath: filePath,
           model: options.model,
           mode,
-          format: options.format,
           instructions: options.instructions,
-          promptText
+          promptText,
+          outputExtensionHint: options.format
         });
 
-        const outputPath = resolveFolderOutputPath(filePath, inputDir, outputRoot, result.format);
+        const outputExtension = options.format ?? result.format;
+        const outputPath = resolveFolderOutputPath(filePath, inputDir, outputRoot, outputExtension);
         await mkdir(dirname(outputPath), { recursive: true });
         await writeFile(outputPath, result.content, "utf8");
         succeeded += 1;
@@ -300,11 +300,11 @@ async function processFolder(
           workerDashboard.setWorkerDone(
             workerId,
             relativeInput,
-            `${result.format} in ${formatDurationMs(Date.now() - startedAt)}`
+            `${outputExtension} in ${formatDurationMs(Date.now() - startedAt)}`
           );
         } else {
           console.log(
-            `[worker-${workerId + 1}] Done ${relativeInput} -> ${outputPath} (${result.format}, ${formatDurationMs(Date.now() - startedAt)})`
+            `[worker-${workerId + 1}] Done ${relativeInput} -> ${outputPath} (${outputExtension}, ${formatDurationMs(Date.now() - startedAt)})`
           );
         }
       } catch (error) {
@@ -583,20 +583,16 @@ async function runWithConcurrency<T>(
   await Promise.all(workers);
 }
 
-const SPINNER_FRAMES = ["-", "\\", "|", "/"];
-
 type WorkerLane = {
   state: "idle" | "running" | "done" | "failed";
   file?: string;
   message?: string;
-  spinnerFrame: number;
 };
 
 class AsciiWorkerDashboard {
   private readonly lanes: WorkerLane[];
   private readonly total: number;
   private readonly workerCount: number;
-  private readonly spinnerTimer: NodeJS.Timeout;
   private completed = 0;
   private failed = 0;
   private renderedLineCount = 0;
@@ -605,16 +601,11 @@ class AsciiWorkerDashboard {
     this.total = total;
     this.workerCount = workerCount;
     this.lanes = Array.from({ length: workerCount }, () => ({
-      state: "idle",
-      spinnerFrame: 0
+      state: "idle"
     }));
 
     process.stdout.write("\x1b[?25l");
     this.render();
-    this.spinnerTimer = setInterval(() => {
-      this.tickSpinners();
-      this.render();
-    }, 100);
   }
 
   setSummary(completed: number, failed: number): void {
@@ -631,7 +622,7 @@ class AsciiWorkerDashboard {
 
     lane.state = "running";
     lane.file = file;
-    lane.message = "processing";
+    lane.message = "processing...";
     this.render();
   }
 
@@ -660,7 +651,6 @@ class AsciiWorkerDashboard {
   }
 
   stop(): void {
-    clearInterval(this.spinnerTimer);
     this.render();
     process.stdout.write("\x1b[?25h");
   }
@@ -696,19 +686,9 @@ class AsciiWorkerDashboard {
     return lines;
   }
 
-  private tickSpinners(): void {
-    for (const lane of this.lanes) {
-      if (lane.state !== "running") {
-        continue;
-      }
-
-      lane.spinnerFrame = (lane.spinnerFrame + 1) % SPINNER_FRAMES.length;
-    }
-  }
-
   private renderIcon(lane: WorkerLane): string {
     if (lane.state === "running") {
-      return SPINNER_FRAMES[lane.spinnerFrame];
+      return ">>";
     }
 
     if (lane.state === "done") {

package/src/cliHelpers.ts

@@ -1,24 +1,28 @@
 import { InvalidArgumentError } from "commander";
 import { basename, dirname, extname, join, relative } from "node:path";
-import { type OutputFormat } from "./openaiPdfToMarkdown.js";
 
 export type CliOptions = {
   output?: string;
   model: string;
   concurrency?: number;
   yes?: boolean;
-  format?: OutputFormat;
+  format?: string;
   instructions?: string;
   prompt?: string;
   promptFile?: string;
 };
 
-export function parseFormat(value: string): OutputFormat {
-  if (value === "md" || value === "txt") {
-    return value;
+export function parseFormat(value: string): string {
+  const normalized = value.trim().replace(/^\.+/, "");
+  if (!normalized) {
+    throw new InvalidArgumentError("Format must be a non-empty file extension.");
+  }
+
+  if (normalized.includes("/") || normalized.includes("\\")) {
+    throw new InvalidArgumentError("Format must be a file extension, not a path.");
   }
 
-  throw new InvalidArgumentError("Format must be either 'md' or 'txt'.");
+  return normalized;
 }
 
 export function parseConcurrency(value: string): number {
@@ -41,30 +45,31 @@ export function validateOptionCombination(options: CliOptions): void {
   }
 }
 
-export function defaultOutputPath(inputPath: string, format: OutputFormat): string {
-  const extension = format === "md" ? ".md" : ".txt";
+export function defaultOutputPath(inputPath: string, extension: string): string {
+  const normalizedExtension = extension.startsWith(".") ? extension : `.${extension}`;
 
   if (extname(inputPath).toLowerCase() === ".pdf") {
-    return inputPath.slice(0, -4) + extension;
+    return inputPath.slice(0, -4) + normalizedExtension;
   }
 
-  return inputPath + extension;
+  return inputPath + normalizedExtension;
 }
 
 export function resolveFolderOutputPath(
   inputPath: string,
   inputRoot: string,
   outputRoot: string | undefined,
-  format: OutputFormat
+  extension: string
 ): string {
   if (!outputRoot) {
-    return defaultOutputPath(inputPath, format);
+    return defaultOutputPath(inputPath, extension);
   }
 
   const relativePath = relative(inputRoot, inputPath);
   const relativeDir = dirname(relativePath);
   const base = basename(relativePath, extname(relativePath));
-  const filename = `${base}.${format}`;
+  const normalizedExtension = extension.startsWith(".") ? extension.slice(1) : extension;
+  const filename = `${base}.${normalizedExtension}`;
 
   if (relativeDir === ".") {
     return join(outputRoot, filename);

package/src/openaiPdfToMarkdown.ts

@@ -9,9 +9,9 @@ export type ConvertOptions = {
   inputPath: string;
   model: string;
   mode: ConversionMode;
-  format?: OutputFormat;
   instructions?: string;
   promptText?: string;
+  outputExtensionHint?: string;
 };
 
 export type ConversionMode = "auto" | "prompt";
@@ -94,63 +94,40 @@ export async function convertPdf(options: ConvertOptions): Promise<ConvertResult
     totalTokens: result.state.usage.totalTokens
   };
 
-  if (options.mode === "auto" && !options.format) {
+  if (options.mode === "auto") {
     return { ...parseAutoResponse(rawOutput), usage };
   }
 
-  const format = options.format ?? "txt";
-  return { format, content: rawOutput, usage };
+  return { format: "txt", content: rawOutput, usage };
 }
 
 function buildPromptText(options: ConvertOptions): string {
+  const outputExtensionHint = normalizeExtensionHint(options.outputExtensionHint);
   if (options.mode === "prompt") {
     if (!options.promptText) {
       throw new Error("promptText is required when mode is 'prompt'.");
     }
 
-    const promptModeParts = [
+    const promptModeParts: string[] = [
       "Apply the following user prompt to the PDF.",
       "Return only the final converted content.",
       `User prompt:\n${options.promptText}`
     ];
 
-    if (options.format === "md") {
-      promptModeParts.push("Output format requirement: Return only GitHub-flavored Markdown.");
-    } else if (options.format === "txt") {
-      promptModeParts.push("Output format requirement: Return plain text only and do not use Markdown syntax.");
-    } else {
-      promptModeParts.push("If the prompt does not enforce a format, prefer plain text without Markdown syntax.");
+    if (outputExtensionHint) {
+      promptModeParts.push(
+        [
+          `Output file extension hint: .${outputExtensionHint}.`,
+          "Prefer content that is practical for saving under this extension.",
+          "Treat this as guidance and still follow the user prompt exactly."
+        ].join(" ")
+      );
     }
 
     return promptModeParts.join("\n\n");
   }
 
-  if (options.format === "md") {
-    return withAdditionalInstructions(
-      [
-        "Convert this PDF into clean GitHub-flavored Markdown.",
-        "Preserve headings, paragraphs, lists, and tables.",
-        "Render tables as Markdown pipe tables with header separators.",
-        "If cells are empty due to merged cells, keep the table readable and consistent.",
-        "Return only Markdown without code fences."
-      ].join(" "),
-      options.instructions
-    );
-  }
-
-  if (options.format === "txt") {
-    return withAdditionalInstructions(
-      [
-        "Convert this PDF into clean plain text.",
-        "Preserve reading order and paragraph boundaries.",
-        "Represent tables in readable plain text (no Markdown syntax).",
-        "Return plain text only and do not use Markdown syntax or code fences."
-      ].join(" "),
-      options.instructions
-    );
-  }
-
-  return withAdditionalInstructions(
+  let autoPrompt = withAdditionalInstructions(
     [
       "Decide the best output format for this PDF: Markdown ('md') or plain text ('txt').",
       "Choose 'md' for documents with meaningful headings, lists, and tables that benefit from Markdown.",
@@ -163,6 +140,18 @@ function buildPromptText(options: ConvertOptions): string {
     ].join("\n"),
     options.instructions
   );
+
+  if (outputExtensionHint) {
+    autoPrompt = `${autoPrompt}\n\n${
+      [
+        `Output file extension hint: .${outputExtensionHint}.`,
+        "Prefer content that is practical for that extension while still returning JSON with format='md' or 'txt'.",
+        "This is guidance only and should not break the required JSON schema."
+      ].join(" ")
+    }`;
+  }
+
+  return autoPrompt;
 }
 
 function withAdditionalInstructions(base: string, additional?: string): string {
@@ -173,6 +162,15 @@ function withAdditionalInstructions(base: string, additional?: string): string {
   return `${base}\n\nAdditional user instructions:\n${additional}`;
 }
 
+function normalizeExtensionHint(extension: string | undefined): string | undefined {
+  if (!extension) {
+    return undefined;
+  }
+
+  const normalized = extension.trim().replace(/^\.+/, "");
+  return normalized || undefined;
+}
+
 function parseAutoResponse(rawOutput: string): Omit<ConvertResult, "usage"> {
   let candidate = rawOutput.trim();
 

package/test/cliHelpers.test.ts

@@ -17,10 +17,16 @@ import {
 test("parseFormat accepts valid values", () => {
   assert.equal(parseFormat("md"), "md");
   assert.equal(parseFormat("txt"), "txt");
+  assert.equal(parseFormat("csv"), "csv");
+  assert.equal(parseFormat(".json"), "json");
+  assert.equal(parseFormat("tar.gz"), "tar.gz");
 });
 
 test("parseFormat rejects invalid values", () => {
-  assert.throws(() => parseFormat("json"), InvalidArgumentError);
+  assert.throws(() => parseFormat(""), InvalidArgumentError);
+  assert.throws(() => parseFormat("   "), InvalidArgumentError);
+  assert.throws(() => parseFormat("../json"), InvalidArgumentError);
+  assert.throws(() => parseFormat("a/b"), InvalidArgumentError);
 });
 
 test("parseConcurrency accepts in-range integers", () => {
@@ -75,6 +81,7 @@ test("validateOptionCombination rejects --instructions with prompt flags", () =>
 test("defaultOutputPath replaces .pdf extension and appends for other files", () => {
   assert.equal(defaultOutputPath("/tmp/input.pdf", "md"), "/tmp/input.md");
   assert.equal(defaultOutputPath("/tmp/input.PDF", "txt"), "/tmp/input.txt");
+  assert.equal(defaultOutputPath("/tmp/input.pdf", ".csv"), "/tmp/input.csv");
   assert.equal(defaultOutputPath("/tmp/input", "md"), "/tmp/input.md");
 });
 
@@ -93,6 +100,11 @@ test("resolveFolderOutputPath preserves nested structure when output root is set
     resolveFolderOutputPath("/data/invoices/file.pdf", "/data/invoices", "/exports", "txt"),
     "/exports/file.txt"
   );
+
+  assert.equal(
+    resolveFolderOutputPath("/data/invoices/file.pdf", "/data/invoices", "/exports", ".csv"),
+    "/exports/file.csv"
+  );
 });
 
 test("resolveFolderOutputPath falls back to default path when no output root", () => {