pdfnamer

pdfnamer is a CLI tool that renames and organizes PDF bills and statements by automatically extracting the company name, date, and document type from the PDF content. Using a config file you maintain, it matches each PDF to a known company via filename patterns or keyword scanning, extracts the statement date, and moves the file to a structured output path — keeping your downloads folder clean with zero manual effort.

Installation

npm install -g @frankledo/pdfnamer

Requires Node.js 22.13 or later. No other system dependencies are needed.

Quick start

1. Install

npm install -g @frankledo/pdfnamer

2. Generate a starter config

pdfnamer --init

This writes ~/.config/pdfnamer/config.json with an annotated example you can edit.

3. Run on a folder of PDFs

pdfnamer ~/Downloads

Use --dry-run to preview renames without moving any files:

pdfnamer --dry-run ~/Downloads

Configuration

The config file lives at ~/.config/pdfnamer/config.json by default. Pass --config <path> to use a different location.

Full annotated example

{
  "output_path": "~/Documents/Bills/{year}/{company}/{date} - {company}[ - {account}][ - {doctype}]",
  "date_format": "YYYY-MM-DD",
  "date_labels": ["Statement Date:", "Bill Date:", "Invoice Date:", "Closing Date:"],
  "companies": [
    {
      "name": "Riverside Electric",
      "filename_patterns": ["riverside_bill_*", "RiversideElectric_*"],
      "keywords": ["Riverside Electric Company", "riverside-electric.example.com"],
      "noAccountNumber": true,
      "subjects": [
        { "match": "Electric Bill", "alias": "Bill" }
      ]
    },
    {
      "name": "Oakwood Bank - Sapphire Visa - 1234",
      "keywords": ["Sapphire Visa", "oakwoodbank.example.com"],
      "keyword_search_chars": 8000,
      "noAccountNumber": true,
      "date_labels": ["Closing Date:", "Statement Date:"],
      "subjects": [
        { "match": "Statement", "alias": "Statement" }
      ]
    },
    {
      "name": "Oakwood Bank - Rewards Visa - 5678",
      "keywords": ["Rewards Visa", "oakwoodbank.example.com"],
      "keyword_search_chars": 8000,
      "noAccountNumber": true,
      "date_labels": ["Closing Date:", "Statement Date:"],
      "subjects": [
        { "match": "Statement", "alias": "Statement" }
      ]
    },
    {
      "name": "Oakwood Bank",
      "keywords": ["oakwoodbank.example.com", "Oakwood Bank"],
      "accounts": [
        { "number": "9012", "alias": "Checking" }
      ],
      "subjects": [
        { "match": "Account Statement", "alias": "Statement" }
      ]
    }
  ]
}

Top-level fields

Field	Default	Description
output_path	required	Template for the output file path. See tokens below.
date_format	YYYY-MM-DD	Format for {date} in the output path.
date_labels	["Statement Date:", ...]	Labels searched in every PDF when extracting the statement date. Can be overridden per company.
rename_in_place	false	When true, rename files in their current directory instead of moving them to output_path. The filename format is still controlled by the basename of output_path. Useful for receipts folders you want to keep in place but make searchable.
unmatched_prefix	false	When true, files that don't match any company entry are still renamed: a date prefix ({date} - ) is prepended to the original filename. Files that can't yield any date, or whose name already starts with a date, are left unchanged. Pairs well with rename_in_place.

Output path tokens

Token	Description
{year}	Four-digit year extracted from the statement date
{month}	Two-digit month (01–12)
{date}	Full date formatted per date_format
{company}	Company name from the matched config entry
{account}	Account alias from a matched accounts entry
{doctype}	Document type alias from a matched subjects entry

Wrap a token and its surrounding delimiter in [...] to make the whole segment optional — it is omitted entirely when the token is empty:

{date} - {company}[ - {account}][ - {doctype}]
{date}_{company}[_{account}][_{doctype}]
{year}/{company}/{date} - {company}[/{doctype}]

Companies that have no accounts entry will silently skip the [ - {account}] block; companies that do will include it. This works with any delimiter style.

Per-company fields

Field	Description
name	Display name used in the output path.
output_path	Override the global output_path for this company only.
filename_patterns	Glob patterns checked against the PDF filename (case-insensitive, supports *). Matched before keywords — no PDF parsing needed.
keywords	Strings to scan for in the PDF text when no filename pattern matches.
keyword_search_chars	How many characters from the start of the PDF text to search for keywords. Default 2000. Increase for documents where card-specific branding appears later in the file.
date_labels	Override the global date_labels for this company. Useful when a company uses non-standard date field names.
accounts	Array of { number, alias } objects. When a number is found in the PDF text the corresponding alias is used as {account}.
subjects	Array of { match, alias } objects. When match is found in the PDF text the alias is used as {doctype}. First match wins.
noAccountNumber	Set true to suppress account matching entirely (omits {account} token).

CLI flags

Flag	Description
-n, --dry-run	Preview renames without moving any files
-c, --config <path>	Use a custom config file instead of ~/.config/pdfnamer/config.json
--init	Write a starter config to ~/.config/pdfnamer/config.json and exit
--install-quickaction	Install a Finder Quick Action (macOS) so you can right-click PDFs to rename them. See Quick Action (macOS) for full setup steps.
--install-watcher [dir]	Install a launchd agent (macOS) that auto-files a folder whenever it changes. Defaults to ~/Downloads. See Folder watcher (macOS).
--uninstall-watcher	Remove the folder watcher (macOS).
-h, --help	Show usage information

How matching works

pdfnamer processes each PDF in two phases. Company order matters: the first matching entry wins. Place specific entries before catch-alls.

Company identification

1. Check each company's filename_patterns against the PDF filename (fast, no PDF parsing needed). First match wins.
2. If no pattern matches, extract the PDF text and scan for each company's keywords in order. First match wins.
3. If still no match, report UNMATCHED with a text snippet to help you add a new entry.

Ordering example: Two credit cards from the same bank share a generic bank keyword. Put the card-specific entries first; the generic bank entry acts as a catch-all:

{ "name": "Oakwood Bank - Sapphire Visa", "keywords": ["Sapphire Visa", "oakwoodbank.example.com"], "keyword_search_chars": 8000 },
{ "name": "Oakwood Bank - Rewards Visa",  "keywords": ["Rewards Visa",  "oakwoodbank.example.com"], "keyword_search_chars": 8000 },
{ "name": "Oakwood Bank",                 "keywords": ["oakwoodbank.example.com", "Oakwood Bank"] }

The catch-all only matches files that didn't already match a card-specific entry. Similarly, if two companies share a keyword, the one listed first always wins.

Date extraction

Dates are extracted in this order — the first successful result is used:

1. Search for each label in date_labels (case-insensitive). When found, parse the date in the following 60 characters.
2. Detect a date range anywhere in the document (MM/DD/YYYY - MM/DD/YYYY, MM/DD/YYYY to MM/DD/YYYY, MM/DD/YY-MM/DD/YY) and use the end date.
3. Fall back to the first parseable date in the document header (first 2000 characters).
4. Fall back to a date embedded in the filename itself.

Recognized date formats

• YYYY-MM-DD (ISO)
• Month DD, YYYY and Month DD , YYYY (e.g. January 1 , 2026)
• MM/DD/YYYY and MM-DD-YYYY
• MM/DD/YY and MM-DD-YY
• YYYYMMDDHHmmss embedded in filenames (e.g. utility download filenames)
• Bare YYYY (tax year — mapped to December 31 of that year)

Quick Action (macOS)

pdfnamer can install a Finder Quick Action so you can right-click any PDF and rename it without opening a terminal.

1. Install the Quick Action

pdfnamer --install-quickaction

This copies a Workflow file into ~/Library/Services/.

2. Enable it in System Settings

Go to System Settings → Privacy & Security → Extensions → Finder Extensions and check the box next to pdfnamer.

3. Use it

Right-click any PDF in Finder → Quick Actions → pdfnamer.

Note: The Quick Action uses your default config at ~/.config/pdfnamer/config.json. Run pdfnamer --init first if you haven't set one up yet.

Folder watcher (macOS)

pdfnamer can install a launchd agent that automatically files a folder every time its contents change — drop a statement in the folder and it's renamed and moved without running anything by hand.

Install

pdfnamer --install-watcher ~/Downloads

The folder argument is optional and defaults to ~/Downloads. This writes a LaunchAgent to ~/Library/LaunchAgents/com.pdfnamer.watcher.plist, loads it, and logs activity to ~/Library/Logs/pdfnamer.log. Matched PDFs are renamed and moved automatically (no preview); unmatched files are left in place.

Uninstall

pdfnamer --uninstall-watcher

One folder at a time: installing again with a different folder repoints the single watcher rather than adding a second one.

Pin a stable Node: the agent records the absolute path of the Node that ran the install. If that's a version-managed Node (nvm, fnm, volta, n), the path can disappear when you switch or remove versions, silently stopping the watcher. --install-watcher warns when it detects this — install pdfnamer under a stable Node (e.g. Homebrew) for a watcher that keeps working.

Note: The watcher uses your default config at ~/.config/pdfnamer/config.json.

Contributing

Bug reports and pull requests are welcome on GitHub.

License

MIT — see LICENSE.