API Key Setup

There are two ways to configure your API key:

Method 1 — Directly in config.yaml (simple, portable):

ai:
  api_key: "sk-your-actual-key-here"

Method 2 — Via environment variable (secure, easy to switch providers):

ai:
  api_key: "${OPENAI_API_KEY}"

Then create a .env file next to your config.yaml:

OPENAI_API_KEY=sk-your-actual-key-here
ANTHROPIC_API_KEY=sk-ant-your-key-here

The ${VAR_NAME} syntax works in any string value in config.yaml. A .env file placed next to config.yaml is loaded automatically.

Tip: Method 2 lets you store all your API keys in .env and switch providers in config.yaml by just changing the ${VAR_NAME} reference. See .env.example for a template.

Recommended Setups

Text extraction (pdfplumber) always runs — it's free and instant. OCR and vision are independent add-ons you enable based on your needs.

Cloud AI + PaddleOCR (Best Accuracy)

PaddleOCR runs locally for free, cloud AI handles smart extraction. Great for mixed document types.

ai:
  provider: "openai"           # or anthropic, gemini, xai
  model: "gpt-5.4"
  api_key: "your-api-key"
pdf:
  ocr: true                    # PaddleOCR enhances scanned docs
  vision: false                # not needed — OCR covers it

Cost: ~$0.001/PDF. Requires: API key + PaddleOCR (~500 MB, installed via setup.ps1).

Cloud AI + Vision (No Local Setup)

No PaddleOCR needed — the LLM reads page images directly. Best for laptops or low-performance machines.

ai:
  provider: "gemini"           # or openai, anthropic, xai
  model: "gemini-3.1-flash-lite"
  api_key: "your-api-key"
pdf:
  ocr: false
  vision: true                 # send page images to LLM

Cost: ~$0.002/PDF. Requires: API key + vision-capable model.

Fully Offline (Max Privacy)

Everything runs on your machine. No data leaves your computer, no API keys, no cost.

ai:
  provider: "ollama"
  model: "qwen3:4b"            # fast, fits in 3 GB VRAM
  api_key: ""
pdf:
  ocr: true                    # PaddleOCR for scanned docs
  vision: false                # text models are faster

Cost: Free. Requires: Ollama + PaddleOCR.

Development Setup

Prerequisites: Python 3.11+, Git

```bash git clone https://github.com/ptmrio/autorename-pdf.git cd autorename-pdf python -m venv venv source venv/bin/activate # Linux/macOS

Building

python build.py                  # Build everything, sign all
python build.py --nosign         # Build everything, skip signing
python build.py --cli-only       # Build CLI EXE only (skip GUI + packaging)

Build pipeline: CLI EXE (PyInstaller) → Sign (Azure Trusted Signing) → Tauri GUI → Portable ZIP

Output (in Releases/): AutoRename-PDF-Portable-{version}.zip

Quick Start

1. Download the latest release ZIP 2. Extract and run setup.ps1 (right-click → "Run with PowerShell") 3. Configure — edit config.yaml with your AI provider and API key:

   ai:
     provider: "openai"       # or anthropic, gemini, xai, ollama
     api_key: "your-key"
   

setup.ps1 creates config.yaml from the template, adds context menu entries, and optionally installs PaddleOCR for offline OCR of scanned documents.

Usage

Configuration

Extraction Settings

• false = disabled (default for both)
• true = always run alongside text extraction
• "auto" = run only when text quality falls below threshold

All enabled sources are combined before sending to the AI — maximizing extraction accuracy.

Copy and edit config

cp config.yaml.example config.yaml

Edit config.yaml with your AI key and provider

venv\Scripts\activate # Windows

pip install -r requirements.txt pip install -r requirements-dev.txt # for testing cp config.yaml.example config.yaml ```

JSON output (for scripting / GUI integration)

autorename-pdf-cli.exe rename --output json "C:\path\to\folder" ```

<details> <summary><strong>Full CLI Reference</strong></summary>

Subcommands

Rename Options

Undo Options

Exit Codes

</details>

Common Questions

Does it work offline? Yes. Use Ollama (free, local AI) + PaddleOCR. No data leaves your machine, no API key needed. See Ollama Setup.

What types of PDFs does it handle? Any PDF: text-based (digital), scanned (OCR), or image-only (vision). All three extraction methods can run together.

How much does it cost? The tool is free and open source. Cloud AI providers charge ~$0.001 per PDF. Ollama is completely free.

Does it work on macOS or Linux? The CLI works cross-platform via Python. The GUI and context menu are Windows-only. See macOS / Linux.

<details> <summary><strong>Table of Contents</strong></summary>

• Configuration
• API Key Setup
• Recommended Setups
• Provider Models
• Extraction Settings
• Usage
• GUI
• Context Menu
• Command Line
• Company Name Harmonization
• Ollama Setup
• macOS / Linux
• Support the Project
• Developer Documentation

</details>