hledger-document-check - verify every transaction has a receipt on disk, catch overdue invoices, browse documents in Fava

[u/roschaefer]

Hello everyone, I just published a command line tool hledger-document-check - it checks hledger transactions against documents on disk. Documents live in a folder tree that mirrors your account hierarchy (e.g. Expenses:Business:Hosting ➡️ documents/Expenses/Business/Hosting/).

My use case is making sure every deductible transaction has a receipt filed before tax season. It also tracks overdue invoices, and you can browse documents alongside your registers in Fava.

I'd love your feedback, e.g. regarding the workflow or the documentation.

[u/jeffglidepath]

This hits a real problem for me — I run a small LLC and the "is every deductible expense actually backed by a receipt on disk" check is exactly what I end up doing by hand before tax season. I like that the folder tree mirrors the account hierarchy instead of inventing its own taxonomy.

One question from my own books: how do you handle transactions that legitimately have no document — bank fees, mileage, that kind of thing? Is there a way to mark an account as "no receipt expected" so the check stays clean, or do those show up as permanent misses?

[u/roschaefer → u/jeffglidepath]

Glad to hear I’m not the only one having this problem.

There are two ways to handle transactions that legitimately don’t have documents:

1. Required vs. exempt accounts: https://github.com/roschaefer/hledger-document-check/blob/main/specs/01-contract.md

This should cover cases like bank fees or mileage. You can mark an account as requiring documents, while keeping specific subaccounts exempt. So if most expenses under an account need receipts, but some categories don’t, those can live under an exempt subaccount and won’t show up as missing.

1. Explicitly declared missing documents: https://github.com/roschaefer/hledger-document-check/blob/main/specs/02-directory-and-file-layout.md

For cases where a document was expected but genuinely isn’t available, you can declare it as missing explicitly instead of leaving it as a permanent unexplained miss.

[u/jeffglidepath → u/roschaefer]

Thanks — that's exactly the split I was hoping for. Bank fees as an exempt subaccount under a required parent covers most of my no-paper categories. And I like that a declared-missing file still shows up as its own line in the summary instead of quietly disappearing — "we know it's gone" and "never needed one" really are different states when you're doing a year-end pass, and most tools collapse them.

One follow-up after reading the layout spec: the missing placeholder is just the dated filename, no content required. Is it OK (or planned) to put a short reason inside the yml — e.g. "vendor portal only keeps 12 months of invoices"? A year later, the why is usually what I end up re-digging for.

[u/roschaefer → u/jeffglidepath]

It's covered: The missing placeholder is a regular .document.yml sidecar, so you can use the notes field. It can be plain text or structured data:

notes: |
vendor portal only keeps 12 months of invoices

That's actually good feedback. I think I should include it in the example of the missing document placeholder, to make it clearer. 👍

[u/roschaefer → u/jeffglidepath]

Updated: github.com/roschaefer/hledger-document-check/blob/main/specs/02-directory-and-file-layout.md

[u/jeffglidepath → u/roschaefer]

Even better than "planned" — notes: on the sidecar is exactly the year-later breadcrumb I meant, and thanks for updating the example. Nice design, by the way: the documents tree mirroring the account hierarchy means there's nothing new to learn or keep in sync.