file-renamer

CLI to scan a folder of receipts/invoices (PDFs and images), extract structured data using AI, and rename files to a consistent pattern.

What it does

• Detects file type (PDF or image)
• Sends the raw file directly to Gemini (no local OCR), extracts: dateISO, issuer, totalAmount, currency, docType
• Renames to: YYYY-MM-DD__ISSUER.ext
• Handles name collisions by appending -001, -002, ...

Requirements

• Node 20+
• pnpm 10+
• Google Generative AI key in GOOGLE_GENERATIVE_AI_API_KEY

Install

pnpm install

No local OCR components required.

Usage

Set your API key, then run:

GOOGLE_GENERATIVE_AI_API_KEY=AIza... pnpm start -- --help

Common flows:

# Dry-run, current directory
GOOGLE_GENERATIVE_AI_API_KEY=AIza... pnpm start -- -n

# Process a folder recursively (no changes, just preview)
GOOGLE_GENERATIVE_AI_API_KEY=AIza... pnpm start -- ~/Downloads/receipts -r -n

# Actually rename, only PDFs and JPGs
GOOGLE_GENERATIVE_AI_API_KEY=AIza... pnpm start -- ~/Downloads/receipts -r --include-ext pdf jpg

# Write renamed files into a separate directory
GOOGLE_GENERATIVE_AI_API_KEY=AIza... pnpm start -- ~/Downloads/receipts -r --out-dir ~/Desktop/renamed

# Increase concurrency
GOOGLE_GENERATIVE_AI_API_KEY=AIza... pnpm start -- ~/Downloads/receipts -r --concurrency 8

# Fail fast on first error
GOOGLE_GENERATIVE_AI_API_KEY=AIza... pnpm start -- ~/Downloads/receipts --fail-on-error

You can also link the CLI globally if you prefer:

pnpm link -g
GOOGLE_GENERATIVE_AI_API_KEY=AIza... file-renamer ~/Downloads/receipts -r -n

Options

file-renamer [dir]

Arguments:
  dir                     Directory to process (default: ".")

Options:
  -r, --recursive         Process directories recursively (default: false)
  -n, --dry-run           Do not rename, only show planned actions (default: false)
  --fail-on-error         Exit non-zero on first failure (default: false)
  --include-ext <ext...>  Only process listed extensions (e.g., pdf jpg png)
  --exclude-ext <ext...>  Exclude listed extensions
  --concurrency <n>       Concurrent files processed (default: 3)
  --out-dir <dir>         Write renamed files into this directory (defaults to same dir)
  -h, --help              display help for command

How it works (brief)

• Type sniffing via file-type
• OCR/text extraction
  • PDF text via pdf-parse
  • Image OCR via tesseract.js
• AI extraction using AI SDK + Google Gemini (gemini-2.5-flash) and a Zod schema for structured output
• Filename builder
  • YYYY-MM-DD__ISSUER.ext
  • Issuer sanitized to be filesystem-safe and trimmed to 30 chars
  • Collisions resolved by appending -001, -002, ...

Notes & limits

• OCR quality varies; low-quality scans may need manual review
• LLM extraction is best-effort; it normalizes date to yyyy-mm-dd and shortens issuer names
• AI calls are remote (OpenAI). OCR is local.

License

ISC