@robin7331/papyrus-cli 0.1.3 → 0.1.5

package/README.md

@@ -21,80 +21,69 @@ npm i -g @robin7331/papyrus-cli
 papyrus --help
 ```
 
-## API Key Setup
-
-Papyrus requires `OPENAI_API_KEY`.
-
-macOS/Linux (persistent):
+## Usage
 
 ```bash
-echo 'export OPENAI_API_KEY="your_api_key_here"' >> ~/.zshrc
-source ~/.zshrc
-```
-
-PowerShell (persistent):
-
-```powershell
-setx OPENAI_API_KEY "your_api_key_here"
-# restart PowerShell after running setx
-```
+# Show installed CLI version
+papyrus --version
 
-One-off execution:
+# Single file (auto mode; if no API key is found, Papyrus prompts you to paste one)
+papyrus ./path/to/input.pdf
 
-```bash
-OPENAI_API_KEY="your_api_key_here" papyrus ./path/to/input.pdf
-```
+# Single file with explicit format/output/model
+papyrus ./path/to/input.pdf --format md --output ./out/result.md --model gpt-4o-mini
 
-Security note: Papyrus intentionally does not provide an `--api-key` flag to avoid leaking keys via shell history or process lists.
+# Auto mode with extra instructions
+papyrus ./path/to/input.pdf --instructions "Prioritize table accuracy." --format txt
 
-## Usage
+# Prompt mode (inline prompt)
+papyrus ./path/to/input.pdf --mode prompt --prompt "Extract all invoice line items as bullet points." --format md
 
-Single file (auto mode):
+# Prompt mode (prompt file)
+papyrus ./path/to/input.pdf --mode prompt --prompt-file ./my-prompt.txt --format txt
 
-```bash
-papyrus ./path/to/input.pdf
-```
+# Folder mode (recursive scan, asks for confirmation)
+papyrus ./path/to/folder
 
-Single file with explicit format/output/model:
+# Folder mode with explicit concurrency and output directory
+papyrus ./path/to/folder --concurrency 4 --output ./out
 
-```bash
-papyrus ./path/to/input.pdf --format md --output ./out/result.md --model gpt-4o-mini
+# Folder mode without confirmation prompt
+papyrus ./path/to/folder --yes
 ```
 
-Auto mode with extra instructions:
-
-```bash
-papyrus ./path/to/input.pdf --instructions "Prioritize table accuracy." --format txt
-```
+## API Key Setup
 
-Prompt mode (inline prompt):
+Papyrus requires `OPENAI_API_KEY`.
 
-```bash
-papyrus ./path/to/input.pdf --mode prompt --prompt "Extract all invoice line items as bullet points." --format md
-```
+If no API key is found in your environment or local config, Papyrus will prompt you interactively to paste one, and can save it for future runs.
 
-Prompt mode (prompt file):
+macOS/Linux (persistent):
 
 ```bash
-papyrus ./path/to/input.pdf --mode prompt --prompt-file ./my-prompt.txt --format txt
+echo 'export OPENAI_API_KEY="your_api_key_here"' >> ~/.zshrc
+source ~/.zshrc
 ```
 
-Folder mode (recursive scan, asks for confirmation):
+PowerShell (persistent):
 
-```bash
-papyrus ./path/to/folder
+```powershell
+setx OPENAI_API_KEY "your_api_key_here"
+# restart PowerShell after running setx
 ```
 
-Folder mode with explicit concurrency and output directory:
+One-off execution:
 
 ```bash
-papyrus ./path/to/folder --concurrency 4 --output ./out
+OPENAI_API_KEY="your_api_key_here" papyrus ./path/to/input.pdf
 ```
 
-Folder mode without confirmation prompt:
+Papyrus config commands (optional, local persistent storage in `~/.config/papyrus/config.json`):
 
 ```bash
-papyrus ./path/to/folder --yes
+papyrus config init
+papyrus config show
+papyrus config clear
 ```
 
 ## Arguments Reference
@@ -109,6 +98,16 @@ Example:
 papyrus ./docs/invoice.pdf
 ```
 
+### `-v, --version`
+
+Print the installed Papyrus CLI version.
+
+Example:
+
+```bash
+papyrus --version
+```
+
 ### `--format <format>`
 
 Output format override:

package/dist/cli.js

@@ -1,13 +1,19 @@
 #!/usr/bin/env node
 import "dotenv/config";
+import { readFileSync } from "node:fs";
 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, parseMode, 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";
+const cliVersion = getCliVersion();
 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")
     .option("-o, --output <path>", "Path to output file (single input) or output directory (folder input)")
@@ -47,11 +53,70 @@ program
         process.exitCode = 1;
     }
 });
-program.parseAsync(process.argv);
+const configCommand = program
+    .command("config")
+    .description("Manage persistent configuration");
+configCommand
+    .command("init")
+    .description("Interactively save an OpenAI API key to the local Papyrus config file")
+    .option("-f, --force", "Overwrite an existing saved API key without confirmation")
+    .action(async (options) => {
+    try {
+        await handleConfigInit(options);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Config init failed: ${message}`);
+        process.exitCode = 1;
+    }
+});
+configCommand
+    .command("show")
+    .description("Show the saved API key in masked form")
+    .action(async () => {
+    try {
+        const storedApiKey = await getStoredApiKey();
+        console.log(`Config file: ${configFilePath}`);
+        if (!storedApiKey) {
+            console.log("OpenAI API key: not set");
+            return;
+        }
+        console.log(`OpenAI API key: ${maskApiKey(storedApiKey)}`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Config show failed: ${message}`);
+        process.exitCode = 1;
+    }
+});
+configCommand
+    .command("clear")
+    .description("Remove the saved API key from local config")
+    .action(async () => {
+    try {
+        const didClear = await clearStoredApiKey();
+        if (!didClear) {
+            console.log(`No saved API key found in ${configFilePath}.`);
+            return;
+        }
+        console.log(`Removed saved API key from ${configFilePath}.`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Config clear failed: ${message}`);
+        process.exitCode = 1;
+    }
+});
+program.parseAsync(process.argv).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Command failed: ${message}`);
+    process.exitCode = 1;
+});
 async function processSingleFile(inputPath, options, promptText) {
     if (!isPdfPath(inputPath)) {
         throw new Error("Input file must have a .pdf extension.");
     }
+    await ensureApiKey();
     const result = await convertPdf({
         inputPath,
         model: options.model,
@@ -80,6 +145,7 @@ async function processFolder(inputDir, options, 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;
@@ -171,6 +237,120 @@ async function resolvePromptText(options) {
     }
     return promptFromFile;
 }
+async function handleConfigInit(options) {
+    const existingKey = await getStoredApiKey();
+    if (existingKey && !options.force) {
+        const overwrite = await askYesNo("An API key is already stored. Overwrite it? [y/N] ", false);
+        if (!overwrite) {
+            console.log("No changes made.");
+            return;
+        }
+    }
+    const apiKey = await promptForApiKey();
+    await setStoredApiKey(apiKey);
+    console.log(`Saved OpenAI API key to ${configFilePath}`);
+}
+async function ensureApiKey() {
+    const envApiKey = normalizeApiKey(process.env.OPENAI_API_KEY);
+    if (envApiKey) {
+        process.env.OPENAI_API_KEY = envApiKey;
+        return;
+    }
+    const storedApiKey = await getStoredApiKey();
+    if (storedApiKey) {
+        process.env.OPENAI_API_KEY = storedApiKey;
+        return;
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error([
+            "OPENAI_API_KEY is not set.",
+            `Run "papyrus config init" to store one in ${configFilePath},`,
+            "or set OPENAI_API_KEY in your environment."
+        ].join(" "));
+    }
+    console.log(`No OpenAI API key found in environment or ${configFilePath}.`);
+    const apiKey = await promptForApiKey();
+    const shouldSave = await askYesNo(`Save this key to ${configFilePath} for future runs? [Y/n] `, true);
+    if (shouldSave) {
+        await setStoredApiKey(apiKey);
+        console.log(`Saved OpenAI API key to ${configFilePath}`);
+    }
+    process.env.OPENAI_API_KEY = apiKey;
+}
+async function promptForApiKey() {
+    console.log(`Create a new API key at: ${OPENAI_API_KEYS_URL}`);
+    const apiKey = normalizeApiKey(await promptHidden("Paste OpenAI API key: "));
+    if (!apiKey) {
+        throw new Error("API key cannot be empty.");
+    }
+    return apiKey;
+}
+async function promptHidden(question) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error("This prompt requires an interactive terminal.");
+    }
+    return new Promise((resolve, reject) => {
+        const stdin = process.stdin;
+        let value = "";
+        let consumeEscapeSequence = false;
+        const wasRaw = stdin.isRaw ?? false;
+        process.stdout.write(question);
+        const cleanup = () => {
+            stdin.off("data", onData);
+            if (stdin.isTTY) {
+                stdin.setRawMode(wasRaw);
+            }
+            stdin.pause();
+            process.stdout.write("\n");
+        };
+        const onData = (chunk) => {
+            const content = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+            for (const character of content) {
+                if (consumeEscapeSequence) {
+                    if (/[A-Za-z~]/.test(character)) {
+                        consumeEscapeSequence = false;
+                    }
+                    continue;
+                }
+                if (character === "\u001b") {
+                    consumeEscapeSequence = true;
+                    continue;
+                }
+                if (character === "\u0003") {
+                    cleanup();
+                    reject(new Error("Cancelled by user."));
+                    return;
+                }
+                if (character === "\r" || character === "\n") {
+                    cleanup();
+                    resolve(value);
+                    return;
+                }
+                if (character === "\u007f" || character === "\b") {
+                    value = value.slice(0, -1);
+                    continue;
+                }
+                if (character < " ") {
+                    continue;
+                }
+                value += character;
+            }
+        };
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.on("data", onData);
+    });
+}
+function normalizeApiKey(value) {
+    if (!value) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    return trimmed;
+}
 async function detectInputKind(inputPath) {
     const metadata = await stat(inputPath);
     if (metadata.isFile()) {
@@ -334,14 +514,20 @@ async function confirmFolderProcessing(totalFiles, concurrency, skipPrompt) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         throw new Error("Folder mode requires an interactive terminal confirmation. Use --yes to skip the prompt.");
     }
+    return askYesNo(`Process ${totalFiles} PDF file(s) with concurrency ${concurrency}? [Y/n] `, true);
+}
+async function askYesNo(question, defaultYes) {
     const { createInterface } = await import("node:readline/promises");
     const rl = createInterface({
         input: process.stdin,
         output: process.stdout
     });
     try {
-        const answer = (await rl.question(`Process ${totalFiles} PDF file(s) with concurrency ${concurrency}? [Y/n] `)).trim().toLowerCase();
-        return answer === "" || answer === "y" || answer === "yes";
+        const answer = (await rl.question(question)).trim().toLowerCase();
+        if (answer === "") {
+            return defaultYes;
+        }
+        return answer === "y" || answer === "yes";
     }
     finally {
         rl.close();
@@ -364,3 +550,17 @@ function mergeUsage(target, delta) {
 function printUsageTotals(usage) {
     console.log(`Token usage: input=${usage.inputTokens}, output=${usage.outputTokens}, total=${usage.totalTokens}, requests=${usage.requests}`);
 }
+function getCliVersion() {
+    try {
+        const packageJsonPath = new URL("../package.json", import.meta.url);
+        const raw = readFileSync(packageJsonPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.version === "string" && parsed.version.trim().length > 0) {
+            return parsed.version;
+        }
+    }
+    catch {
+        // ignore and use fallback
+    }
+    return "0.0.0";
+}

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+export type PapyrusConfig = {
+    openaiApiKey?: string;
+};
+type ConfigPathOptions = {
+    configFilePath?: string;
+};
+export declare function getConfigFilePath(options?: ConfigPathOptions): string;
+export declare function readPapyrusConfig(options?: ConfigPathOptions): Promise<PapyrusConfig>;
+export declare function getStoredApiKey(options?: ConfigPathOptions): Promise<string | undefined>;
+export declare function setStoredApiKey(apiKey: string, options?: ConfigPathOptions): Promise<void>;
+export declare function clearStoredApiKey(options?: ConfigPathOptions): Promise<boolean>;
+export declare function maskApiKey(apiKey: string): string;
+export {};

package/dist/config.js

@@ -0,0 +1,105 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+export function getConfigFilePath(options) {
+    if (options?.configFilePath) {
+        return options.configFilePath;
+    }
+    return join(homedir(), ".config", "papyrus", "config.json");
+}
+export async function readPapyrusConfig(options) {
+    const configObject = await readConfigObject(options);
+    const openaiApiKey = normalizeApiKey(configObject.openaiApiKey);
+    return openaiApiKey ? { openaiApiKey } : {};
+}
+export async function getStoredApiKey(options) {
+    const config = await readPapyrusConfig(options);
+    return config.openaiApiKey;
+}
+export async function setStoredApiKey(apiKey, options) {
+    const normalizedApiKey = normalizeApiKey(apiKey);
+    if (!normalizedApiKey) {
+        throw new Error("API key cannot be empty.");
+    }
+    const configObject = await readConfigObject(options);
+    configObject.openaiApiKey = normalizedApiKey;
+    await writeConfigObject(configObject, options);
+}
+export async function clearStoredApiKey(options) {
+    const configPath = getConfigFilePath(options);
+    const configObject = await readConfigObject(options);
+    if (!("openaiApiKey" in configObject)) {
+        return false;
+    }
+    delete configObject.openaiApiKey;
+    if (Object.keys(configObject).length === 0) {
+        await rm(configPath, { force: true });
+        return true;
+    }
+    await writeConfigObject(configObject, options);
+    return true;
+}
+export function maskApiKey(apiKey) {
+    const normalizedApiKey = normalizeApiKey(apiKey);
+    if (!normalizedApiKey) {
+        return "(empty)";
+    }
+    if (normalizedApiKey.length <= 8) {
+        return `${normalizedApiKey[0]}***${normalizedApiKey[normalizedApiKey.length - 1]}`;
+    }
+    return `${normalizedApiKey.slice(0, 4)}...${normalizedApiKey.slice(-4)}`;
+}
+async function readConfigObject(options) {
+    const configPath = getConfigFilePath(options);
+    let raw;
+    try {
+        raw = await readFile(configPath, "utf8");
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return {};
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid JSON in ${configPath}: ${message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Invalid config in ${configPath}: expected a JSON object.`);
+    }
+    return { ...parsed };
+}
+async function writeConfigObject(configObject, options) {
+    const configPath = getConfigFilePath(options);
+    const configDir = dirname(configPath);
+    await mkdir(configDir, { recursive: true, mode: 0o700 });
+    try {
+        await chmod(configDir, 0o700);
+    }
+    catch (error) {
+        if (!isNodeError(error) || error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+    const serialized = `${JSON.stringify(configObject, null, 2)}\n`;
+    await writeFile(configPath, serialized, { encoding: "utf8", mode: 0o600 });
+    await chmod(configPath, 0o600);
+}
+function normalizeApiKey(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    return trimmed;
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/package.json

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

package/src/cli.ts

@@ -1,9 +1,17 @@
 #!/usr/bin/env node
 
 import "dotenv/config";
+import { readFileSync } from "node:fs";
 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,
   type ConvertUsage
@@ -23,9 +31,17 @@ import {
 } from "./cliHelpers.js";
 
 const program = new Command();
+const configFilePath = getConfigFilePath();
+const OPENAI_API_KEYS_URL = "https://platform.openai.com/settings/organization/api-keys";
+const cliVersion = getCliVersion();
+
+type ConfigInitOptions = {
+  force?: boolean;
+};
 
 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")
   .option("-o, --output <path>", "Path to output file (single input) or output directory (folder input)")
@@ -75,7 +91,68 @@ program
     }
   });
 
-program.parseAsync(process.argv);
+const configCommand = program
+  .command("config")
+  .description("Manage persistent configuration");
+
+configCommand
+  .command("init")
+  .description("Interactively save an OpenAI API key to the local Papyrus config file")
+  .option("-f, --force", "Overwrite an existing saved API key without confirmation")
+  .action(async (options: ConfigInitOptions) => {
+    try {
+      await handleConfigInit(options);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`Config init failed: ${message}`);
+      process.exitCode = 1;
+    }
+  });
+
+configCommand
+  .command("show")
+  .description("Show the saved API key in masked form")
+  .action(async () => {
+    try {
+      const storedApiKey = await getStoredApiKey();
+      console.log(`Config file: ${configFilePath}`);
+      if (!storedApiKey) {
+        console.log("OpenAI API key: not set");
+        return;
+      }
+
+      console.log(`OpenAI API key: ${maskApiKey(storedApiKey)}`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`Config show failed: ${message}`);
+      process.exitCode = 1;
+    }
+  });
+
+configCommand
+  .command("clear")
+  .description("Remove the saved API key from local config")
+  .action(async () => {
+    try {
+      const didClear = await clearStoredApiKey();
+      if (!didClear) {
+        console.log(`No saved API key found in ${configFilePath}.`);
+        return;
+      }
+
+      console.log(`Removed saved API key from ${configFilePath}.`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`Config clear failed: ${message}`);
+      process.exitCode = 1;
+    }
+  });
+
+program.parseAsync(process.argv).catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`Command failed: ${message}`);
+  process.exitCode = 1;
+});
 
 async function processSingleFile(
   inputPath: string,
@@ -86,6 +163,7 @@ async function processSingleFile(
     throw new Error("Input file must have a .pdf extension.");
   }
 
+  await ensureApiKey();
   const result = await convertPdf({
     inputPath,
     model: options.model,
@@ -133,6 +211,7 @@ 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;
@@ -248,6 +327,150 @@ async function resolvePromptText(options: CliOptions): Promise<string | undefine
   return promptFromFile;
 }
 
+async function handleConfigInit(options: ConfigInitOptions): Promise<void> {
+  const existingKey = await getStoredApiKey();
+  if (existingKey && !options.force) {
+    const overwrite = await askYesNo("An API key is already stored. Overwrite it? [y/N] ", false);
+    if (!overwrite) {
+      console.log("No changes made.");
+      return;
+    }
+  }
+
+  const apiKey = await promptForApiKey();
+  await setStoredApiKey(apiKey);
+  console.log(`Saved OpenAI API key to ${configFilePath}`);
+}
+
+async function ensureApiKey(): Promise<void> {
+  const envApiKey = normalizeApiKey(process.env.OPENAI_API_KEY);
+  if (envApiKey) {
+    process.env.OPENAI_API_KEY = envApiKey;
+    return;
+  }
+
+  const storedApiKey = await getStoredApiKey();
+  if (storedApiKey) {
+    process.env.OPENAI_API_KEY = storedApiKey;
+    return;
+  }
+
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(
+      [
+        "OPENAI_API_KEY is not set.",
+        `Run "papyrus config init" to store one in ${configFilePath},`,
+        "or set OPENAI_API_KEY in your environment."
+      ].join(" ")
+    );
+  }
+
+  console.log(`No OpenAI API key found in environment or ${configFilePath}.`);
+  const apiKey = await promptForApiKey();
+  const shouldSave = await askYesNo(
+    `Save this key to ${configFilePath} for future runs? [Y/n] `,
+    true
+  );
+
+  if (shouldSave) {
+    await setStoredApiKey(apiKey);
+    console.log(`Saved OpenAI API key to ${configFilePath}`);
+  }
+
+  process.env.OPENAI_API_KEY = apiKey;
+}
+
+async function promptForApiKey(): Promise<string> {
+  console.log(`Create a new API key at: ${OPENAI_API_KEYS_URL}`);
+  const apiKey = normalizeApiKey(await promptHidden("Paste OpenAI API key: "));
+  if (!apiKey) {
+    throw new Error("API key cannot be empty.");
+  }
+
+  return apiKey;
+}
+
+async function promptHidden(question: string): Promise<string> {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error("This prompt requires an interactive terminal.");
+  }
+
+  return new Promise((resolve, reject) => {
+    const stdin = process.stdin;
+    let value = "";
+    let consumeEscapeSequence = false;
+    const wasRaw = stdin.isRaw ?? false;
+    process.stdout.write(question);
+
+    const cleanup = (): void => {
+      stdin.off("data", onData);
+      if (stdin.isTTY) {
+        stdin.setRawMode(wasRaw);
+      }
+
+      stdin.pause();
+      process.stdout.write("\n");
+    };
+
+    const onData = (chunk: string | Buffer): void => {
+      const content = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      for (const character of content) {
+        if (consumeEscapeSequence) {
+          if (/[A-Za-z~]/.test(character)) {
+            consumeEscapeSequence = false;
+          }
+          continue;
+        }
+
+        if (character === "\u001b") {
+          consumeEscapeSequence = true;
+          continue;
+        }
+
+        if (character === "\u0003") {
+          cleanup();
+          reject(new Error("Cancelled by user."));
+          return;
+        }
+
+        if (character === "\r" || character === "\n") {
+          cleanup();
+          resolve(value);
+          return;
+        }
+
+        if (character === "\u007f" || character === "\b") {
+          value = value.slice(0, -1);
+          continue;
+        }
+
+        if (character < " ") {
+          continue;
+        }
+
+        value += character;
+      }
+    };
+
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on("data", onData);
+  });
+}
+
+function normalizeApiKey(value: string | undefined): string | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  return trimmed;
+}
+
 async function detectInputKind(inputPath: string): Promise<"file" | "directory"> {
   const metadata = await stat(inputPath);
   if (metadata.isFile()) {
@@ -467,6 +690,13 @@ async function confirmFolderProcessing(
     );
   }
 
+  return askYesNo(
+    `Process ${totalFiles} PDF file(s) with concurrency ${concurrency}? [Y/n] `,
+    true
+  );
+}
+
+async function askYesNo(question: string, defaultYes: boolean): Promise<boolean> {
   const { createInterface } = await import("node:readline/promises");
   const rl = createInterface({
     input: process.stdin,
@@ -474,11 +704,12 @@ async function confirmFolderProcessing(
   });
 
   try {
-    const answer = (await rl.question(
-      `Process ${totalFiles} PDF file(s) with concurrency ${concurrency}? [Y/n] `
-    )).trim().toLowerCase();
+    const answer = (await rl.question(question)).trim().toLowerCase();
+    if (answer === "") {
+      return defaultYes;
+    }
 
-    return answer === "" || answer === "y" || answer === "yes";
+    return answer === "y" || answer === "yes";
   } finally {
     rl.close();
   }
@@ -505,3 +736,18 @@ function printUsageTotals(usage: ConvertUsage): void {
     `Token usage: input=${usage.inputTokens}, output=${usage.outputTokens}, total=${usage.totalTokens}, requests=${usage.requests}`
   );
 }
+
+function getCliVersion(): string {
+  try {
+    const packageJsonPath = new URL("../package.json", import.meta.url);
+    const raw = readFileSync(packageJsonPath, "utf8");
+    const parsed = JSON.parse(raw) as { version?: unknown };
+    if (typeof parsed.version === "string" && parsed.version.trim().length > 0) {
+      return parsed.version;
+    }
+  } catch {
+    // ignore and use fallback
+  }
+
+  return "0.0.0";
+}

package/src/config.ts

@@ -0,0 +1,141 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+export type PapyrusConfig = {
+  openaiApiKey?: string;
+};
+
+type ConfigPathOptions = {
+  configFilePath?: string;
+};
+
+export function getConfigFilePath(options?: ConfigPathOptions): string {
+  if (options?.configFilePath) {
+    return options.configFilePath;
+  }
+
+  return join(homedir(), ".config", "papyrus", "config.json");
+}
+
+export async function readPapyrusConfig(options?: ConfigPathOptions): Promise<PapyrusConfig> {
+  const configObject = await readConfigObject(options);
+  const openaiApiKey = normalizeApiKey(configObject.openaiApiKey);
+  return openaiApiKey ? { openaiApiKey } : {};
+}
+
+export async function getStoredApiKey(options?: ConfigPathOptions): Promise<string | undefined> {
+  const config = await readPapyrusConfig(options);
+  return config.openaiApiKey;
+}
+
+export async function setStoredApiKey(
+  apiKey: string,
+  options?: ConfigPathOptions
+): Promise<void> {
+  const normalizedApiKey = normalizeApiKey(apiKey);
+  if (!normalizedApiKey) {
+    throw new Error("API key cannot be empty.");
+  }
+
+  const configObject = await readConfigObject(options);
+  configObject.openaiApiKey = normalizedApiKey;
+  await writeConfigObject(configObject, options);
+}
+
+export async function clearStoredApiKey(options?: ConfigPathOptions): Promise<boolean> {
+  const configPath = getConfigFilePath(options);
+  const configObject = await readConfigObject(options);
+  if (!("openaiApiKey" in configObject)) {
+    return false;
+  }
+
+  delete configObject.openaiApiKey;
+  if (Object.keys(configObject).length === 0) {
+    await rm(configPath, { force: true });
+    return true;
+  }
+
+  await writeConfigObject(configObject, options);
+  return true;
+}
+
+export function maskApiKey(apiKey: string): string {
+  const normalizedApiKey = normalizeApiKey(apiKey);
+  if (!normalizedApiKey) {
+    return "(empty)";
+  }
+
+  if (normalizedApiKey.length <= 8) {
+    return `${normalizedApiKey[0]}***${normalizedApiKey[normalizedApiKey.length - 1]}`;
+  }
+
+  return `${normalizedApiKey.slice(0, 4)}...${normalizedApiKey.slice(-4)}`;
+}
+
+async function readConfigObject(options?: ConfigPathOptions): Promise<Record<string, unknown>> {
+  const configPath = getConfigFilePath(options);
+
+  let raw: string;
+  try {
+    raw = await readFile(configPath, "utf8");
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return {};
+    }
+
+    throw error;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid JSON in ${configPath}: ${message}`);
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`Invalid config in ${configPath}: expected a JSON object.`);
+  }
+
+  return { ...(parsed as Record<string, unknown>) };
+}
+
+async function writeConfigObject(
+  configObject: Record<string, unknown>,
+  options?: ConfigPathOptions
+): Promise<void> {
+  const configPath = getConfigFilePath(options);
+  const configDir = dirname(configPath);
+  await mkdir(configDir, { recursive: true, mode: 0o700 });
+
+  try {
+    await chmod(configDir, 0o700);
+  } catch (error) {
+    if (!isNodeError(error) || error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  const serialized = `${JSON.stringify(configObject, null, 2)}\n`;
+  await writeFile(configPath, serialized, { encoding: "utf8", mode: 0o600 });
+  await chmod(configPath, 0o600);
+}
+
+function normalizeApiKey(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  return trimmed;
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}

package/test/config.test.ts

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import test from "node:test";
+import {
+  clearStoredApiKey,
+  getStoredApiKey,
+  maskApiKey,
+  readPapyrusConfig,
+  setStoredApiKey
+} from "../src/config.js";
+
+async function withTempConfigPath(
+  run: (configFilePath: string) => Promise<void>
+): Promise<void> {
+  const root = await mkdtemp(join(tmpdir(), "papyrus-config-test-"));
+  try {
+    await run(join(root, "config.json"));
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}
+
+test("setStoredApiKey and getStoredApiKey persist and read the key", async () => {
+  await withTempConfigPath(async (configFilePath) => {
+    await setStoredApiKey("sk-test-123", { configFilePath });
+    const storedApiKey = await getStoredApiKey({ configFilePath });
+    assert.equal(storedApiKey, "sk-test-123");
+
+    const raw = JSON.parse(await readFile(configFilePath, "utf8")) as Record<string, string>;
+    assert.equal(raw.openaiApiKey, "sk-test-123");
+  });
+});
+
+test("clearStoredApiKey removes the key and reports state transitions", async () => {
+  await withTempConfigPath(async (configFilePath) => {
+    await setStoredApiKey("sk-test-123", { configFilePath });
+
+    assert.equal(await clearStoredApiKey({ configFilePath }), true);
+    assert.equal(await getStoredApiKey({ configFilePath }), undefined);
+    assert.equal(await clearStoredApiKey({ configFilePath }), false);
+  });
+});
+
+test("readPapyrusConfig rejects invalid JSON structures", async () => {
+  await withTempConfigPath(async (configFilePath) => {
+    await writeFile(configFilePath, "[]\n", "utf8");
+    await assert.rejects(
+      () => readPapyrusConfig({ configFilePath }),
+      /expected a JSON object/
+    );
+  });
+});
+
+test("maskApiKey masks short and long keys", () => {
+  assert.equal(maskApiKey("sk-short"), "s***t");
+  assert.equal(maskApiKey("sk-test-123456789"), "sk-t...6789");
+});