Getting started

From download to your first archive.

Fifteen minutes the first time, most of it waiting for a bank's website. Every screenshot below is the real program on a folder of made-up installs, so the names and numbers are invented.

This guide is for the desktop app on Windows or macOS. To run PaperPull on a NAS or home server instead, see PaperPull Server and its setup page, SERVER.md.

1. Install 2. Open it 3. Open an account 4. Sign in 5. Try the newest few 6. Get new documents 7. Find the PDFs 8. Spreadsheets Next month Better names When it does not work

1. Install

Windows. Download PaperPull-<version>-setup.exe from the latest release and run it. It installs into your own user folder, so it needs no administrator password. The installer is code-signed, so Windows names its publisher, Bryan Rhee. While the certificate is new, Windows may still show a blue "Windows protected your PC" box the first time, since SmartScreen learns to trust a publisher from downloads over time. If it does, click More info, check that the publisher reads Bryan Rhee, then click Run anyway. The release page also lists each file's SHA-256, and the code-signing policy explains how the signing works. Do not turn off SmartScreen or antivirus for this or any installer.

macOS. There is one disk image for each kind of Mac. Open PaperPull-<version>-arm64.dmg on a Mac with Apple Silicon or PaperPull-<version>-x86_64.dmg on a Mac with an Intel processor, and drag PaperPull to Applications. About This Mac tells them apart, a Chip line for Apple Silicon and a Processor line for Intel. Both are signed and notarized, so there is no warning. You need Chrome, Edge, Brave, Vivaldi or Opera installed, since Safari cannot be driven the way PaperPull needs.

Linux. No package. Clone the repository and follow the README's quick start, which runs the same control panel from source.

Updating later is the same download, run over the old one. Your downloads, history and signed-in browser profiles are wherever you put them and are not touched.

2. Open it

Double-click PaperPull. A small window opens (a terminal on the Mac) and your web browser opens the control panel at http://127.0.0.1:8765. That address is your own computer. The panel is a page only your browser can reach, and the small window is what serves it, so leave both open while you use PaperPull.

The first time, the panel walks you through three short steps. It asks for a folder for your documents, then which providers you have accounts with, then the name on those accounts. The name never leaves your computer and can be left blank.

The second of three first-run steps, Choose providers. A search box and filters by kind sit above a grid of provider tiles with Amazon ticked, and a bar at the bottom reads 4 chosen, Amazon, Chase, Target, Verizon, beside Back and Continue. — Pick a folder, tick the providers you use, add your name, then click Set up. Each provider gets a folder of its own. Nothing is downloaded yet.

3. Open an account

The Accounts page lists every provider you set up, one row each, with where it stands and a button for its next step. Click a provider's name to open its page. The page has two numbered steps, Open sign-in window and Get new documents. Under the second, Which dates is All dates by default, which is what you want for a first run. Its latest documents and recent runs are listed beside them, and rarer actions are under More.

Chase's page in the panel. A green Up to date band, then Get your documents with step 1, Sign in to Chase and an Open sign-in window button, and step 2, Get new documents, with Which dates set to All dates, a Get new documents button and the links Try the newest few first and Only check what's there. Latest documents and Recent runs fill the right side. — One account's page. The two numbered steps are the whole workflow, in order.

Click Open sign-in window. A browser window opens on the provider's own sign-in page. It is your regular browser (Edge, Chrome, or whichever you have) but with a fresh profile that PaperPull keeps for this provider, so it knows none of your other logins. Sign in there the way you would on a new computer, answer the two-factor prompt, and leave that window open.

PaperPull never sees what you type there. It attaches to the window afterward and reads what you can see.

What the panel says after Open sign-in window. The browser window is the one to sign in to.

Password manager? That fresh profile starts with no extensions. Install yours into it once, from the extension store in that window, and it stays for every sign-in after. Nothing about the profile is shared with your everyday browser.

5. Try the newest few, the small test

Beside Get new documents, click Try the newest few first. PaperPull reads the provider's document list and downloads only the newest few, then lists what it saved. This is the moment to open one of the PDFs and check it is the right thing. Nothing further runs until you start it. Only check what's there, beside it, lists what the provider has and downloads nothing.

The panel after Try the newest few first on Chase, titled 5 new documents saved, Finished, no issues reported, with the five statement files listed and the technical details open below, starting with Discovery complete, Documents known 72, and two cards seen. — The newest few from a sample Chase archive. Seventy-two statements found, five saved, nothing to worry about.

6. Get new documents

Click Get new documents. The first time, this is the historical backfill, every account, every year and every page the provider offers. It pauses a few seconds between documents, the way a person would, so a big archive takes minutes rather than seconds. You can keep using your computer and look at the panel's other pages meanwhile. Leave the panel's tab open, since closing it stops the run. Anything already saved stays saved, and if a run stops partway, Continue picks up where it stopped.

The panel during Get new documents, titled Getting new documents from Chase, with Saving 16 of 72 above a progress bar, the latest saved file, a Stop button, and the technical details listing numbered lines, each with a date, the kind of document and Saved followed by the file name. — Get new documents, part way through. Each Saved line is one PDF landing in its folder.

7. Find the PDFs

Inside the folder you chose is one folder per provider, and inside each, the documents by kind. Every file is named <date> <provider> <account> <kind>.pdf, so it sorts by date and says what it is without opening it. Beside the PDFs is a Document Index.csv (or Order History.csv for a store) listing every one. Open folder, on each account's page, opens that provider's folder.

PaperPull/
  Chase Statements/
    Statements/
      2026-08-31 Chase Sapphire Monthly Statement.pdf
      2026-08-31 Chase Freedom Monthly Statement.pdf
      2026-07-31 Chase Sapphire Monthly Statement.pdf
      ...
    Chase Document Index.csv
    progress.json            what has been downloaded, the memory that makes reruns cheap
  Amazon Receipts/
    Online/
      2026-09-16 Amazon Electronics Receipt.pdf
      ...
    Amazon Order History.csv
    Amazon Receipt Index.csv

Move the PDFs anywhere you like, into a filing system, onto a NAS, into Paperless-ngx. progress.json is what remembers them, so a rerun does not fetch them again. Leave that file where it is.

To keep every document in one place, such as a folder Google Drive, Dropbox or OneDrive syncs, one Paperless-ngx watches or a share on a NAS, open Settings and give Documents folder one folder for every provider. Each provider and person gets a folder of their own inside it, named as their PaperPull folder is, and one added later gets theirs on its first run. When a run ends, the documents it saved and checked move there, in folders of their kind. Records, Manual Review, logs and browser profiles stay in your PaperPull folder, so the shared folder only ever gets documents. A provider or person can still have a folder of their own, set just below it. Saving the setting moves nothing you already have, and nothing is downloaded again.

8. The spreadsheets

The Spreadsheets page makes two files from what PaperPull already saved, so nothing is downloaded. Create purchases file gathers every receipt provider's line items into All Purchases.xlsx, one row per item, with an Orders sheet and your spending per provider per year. Create transactions file reads the transactions out of your statement PDFs into All Transactions.xlsx, checking each statement against its own printed balances. Either can be a CSV instead. Both land in your PaperPull folder, and Show in folder opens it.

The Spreadsheets page after both files are made. Purchases shows All Purchases.xlsx with 602 items in 245 orders and a table of line items per store, and Bank transactions shows All Transactions.xlsx with technical details ending in 470 transactions from 40 statements, 40 of which reconcile to the cent. — Both files made from the sample archive. The first transactions file for a big archive reads every PDF once and takes a few minutes. The next takes seconds.

Only providers that record line items feed the purchases workbook (the stores), and only statement PDFs that carry text feed the transactions workbook. The directory marks which is which.

Next month

Open PaperPull. The Accounts page gives each account one plain status, such as Overdue, New one likely, Possible gap, Stopped partway, Needs a look or Up to date, with a button for its next step. A possible gap is a month missing from the middle of a run. When more than one account may have something new, Get new for all runs each of them, one by one, and fetches only what is new. If a provider has signed you out, the round waits at that account. Sign in again there and try it once more, or skip to the next.

The Accounts page on the sample archive. A summary says 4 accounts may have something new, beside a Get new for all 4, one by one button. Under Needs a look, Navy Federal is Stopped partway with a Continue button, Target Needs a look with one receipt set aside, American Express is Overdue, Verizon is New one likely, and USAA has a Possible gap of two documents between Feb 28, 2025 and May 31, 2025. — Accounts on the sample archive. American Express is overdue for a run, and USAA has two months missing in 2025.

A second person

On a provider's page, More then Add another person makes a second account for the same provider, with its own folder next to yours, its own sign-in window and its own download history. Give it a short label, and their name as it appears on the documents if you like. Their account then has a row on the Accounts page and a page of its own. Open it, click Open sign-in window, and sign in as them.

The Add another person to Amazon dialog over Amazon's page, with esther as the short label for the account, Esther as their name, and the buttons Cancel and Add this person. — A second account on Amazon, about to get its own folder and its own sign-in window.

Better names for receipts

A store's receipt is named after what you bought. When PaperPull is unsure what to call one, a basket of unrelated things for instance, it saves it under its best guess and says so when the run ends. On that provider's page, click More, then Review names. It lists each receipt waiting, with its date, order number and items. Type a short summary for any you want to rename, such as Garden Hose, and click Rename. The file is renamed where it sits, and its rows in the receipt index and order history follow it. Leave a box blank to keep a name. It works the same on PaperPull Server.

The Review names from Target dialog over Target's page, saying 4 receipts are waiting for a better name. The first, 2026-09-02 Target Mixed Purchases Receipt.pdf with a garden hose, a hose nozzle and plant food, has Garden Hose and Nozzle typed in its box, and the others say Leave blank to keep this name. — Four receipts waiting for a better name, the first about to be renamed Garden Hose and Nozzle.

When it does not work

"Could not connect to your signed-in browser." The sign-in window was closed, or the sign-in timed out. Click Open sign-in window again, sign in, leave the window open, and try again.
The panel says the provider signed you out or wants a code. The run stops there, and everything it saved stays saved. Click Open sign-in window, sign in or enter the code in that window, then click Continue to pick up the rest. PaperPull never tries to get past a security check on its own.
A run finds 0 documents. The provider's site changed, or you are on a page the app does not expect. On the provider's page, click More, then Make a support report. It reads the provider's page and saves a file that holds counts and states and no text from your account, which is what a fix is built from. Attach the file whose name starts with survey- to a report. Record steps for support, in the same menu, watches while you click your way to a document, and records no typing.
A PDF went to Manual Review. It was saved but did not pass the check that it is the document it claims to be, and the account shows Needs a look. Open the PDF and look. It is usually a sign-in page the site served instead of the statement.
SmartScreen or a Mac warning. See Install. Never disable a security feature to get past it.

When you attach anything to a report, never include a password, a browser profile folder, a token, or an unredacted statement. The support report's survey- file is safe to attach because it holds no text from your account. A screenshot of a run's technical details is fine too.

Everything above, in more depth, is in the README. Questions go to Issues or support@paperpull.net.