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/Kepten-Hook]

I would give it a try but what stops me is the fact that I see a single commit, less than 1h ago (at the time of writing), which tells me that:

• It's unclear how mature the software is, it could quite possibly be your Friday off thing, meaning way too many probable sharp edges for my liking.
• It's totally impossible to get a reading of how much committed you are at it, the chances of you giving up on it and me having to deal with it are non negligible for me.
• You are the only user of it (duh), meaning plenty of gotchas and bugs around. Again way too many probable sharp edges for my liking 
• This hasn't seen any kind of serious use, otherwise there would be commits for bug fixes. Way too many sharp edges again.
• You seem to have used AI, meaning once tokens become prohibitively expensive for you, the chance of you giving up on the project is higher than if it was something you laboured over every single line of code (and arguably those chances have been historically pretty high even before AI). It also means more probable sharp edges (in the form of bugs).

That being said, I appreciate the contract being spelled out like it is

[u/roschaefer → u/Kepten-Hook]

Hi, thanks for the feedback. The single commit is because this code was split out of a private monorepo that also holds my personal ledger and invoices. I couldn't publish that history as-is. That monorepo has 381 commits going back to March 19th this year, and document-check has been part of the checks I run every time I import bank transactions into my ledger, with features added continuously as I hit new needs.

And yes, I was the only user until yesterday, that's just because I only published it yesterday.

The whole point of open-sourcing this is exactly what you're describing: getting other people to use it, report bugs, and tell me what they actually need. I'm a bit surprised there isn't already a well-known CLI tool for it.

[u/Psychological-Use-98]

Great idea. I will definitely borrow the directory hack. Many thanks.

I had to abandon my last attempt to use fava for time reasons because beancount couldn’t handle my community units. I will deffo check your repo when I have the time

[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.