hledger-flow: An hledger workflow focusing on automated statement import and classification.

[ console, finance, gpl, library, program ] [ Propose Tags ] [ Report a vulnerability ]
Versions [RSS] 0.11.0.0, 0.11.1.0, 0.11.1.1, 0.11.1.2, 0.11.2.0, 0.11.3.0, 0.12.0.0, 0.12.1.0, 0.12.2.0, 0.12.2.1, 0.12.3.0, 0.12.3.1, 0.12.4.0, 0.13.0.0, 0.13.1.0, 0.13.2.0, 0.14.0.0, 0.14.1.0, 0.14.2.0, 0.14.3.0, 0.14.4, 0.16.1, 0.16.3, 0.16.4, 0.17.0, 0.18.0, 0.19.0, 0.20.0, 0.20.1, 0.21.0
Change log ChangeLog.md
Dependencies aeson (>=2.2.5.1 && <2.3), ansi-terminal (>=1.1.5 && <1.2), async (>=2.2.6 && <2.3), base (>=4.20 && <4.22), bytestring (>=0.12.2.0 && <0.13), code-page (>=0.2.1 && <0.3), containers (>=0.7 && <0.8), directory (>=1.3.8.5 && <1.4), exceptions (>=0.10.9 && <0.11), filepath (>=1.5.4.0 && <1.6), gitrev (>=1.3.1 && <1.4), hledger-flow, http-client (>=0.7.19 && <0.8), http-client-tls (>=0.3.6.4 && <0.4), optparse-applicative (>=0.18.1.0 && <0.20), path (>=0.9.6 && <0.10), path-io (>=1.8.2 && <1.9), process (>=1.6.26.1 && <1.7), stm (>=2.5.3.1 && <2.6), text (>=2.1.3 && <2.2), time (>=1.12.2 && <1.13 || >=1.14 && <1.15) [details]
License GPL-3.0-only
Copyright 2023 Andreas Pauley
Author Andreas Pauley <hledger-flow@pauley.org.za>
Maintainer Andreas Pauley <hledger-flow@pauley.org.za>
Uploaded by apauley at 2026-11-13T19:41:52Z
Category Finance, Console
Home page https://github.com/apauley/hledger-flow#readme
Bug tracker https://github.com/apauley/hledger-flow/issues
Source repo head: git clone https://github.com/apauley/hledger-flow
Distributions
Executables hledger-flow
Downloads 9236 total (104 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Last success reported on 2026-11-13 [all 1 reports]

Readme for hledger-flow-0.20.0

[back to package description]

hledger-flow

What is it?

hledger-flow organises bank statements by owner, bank, account and year. It uses hledger and its CSV rules to generate one journal per statement, then includes those journals and your manual entries in all-years.journal. You keep the original statements so you can rebuild the imported entries when your rules change.

It grew out of scripts I wrote while using adept's Full-fledged Hledger.

Who should use this?

Choose hledger-flow if you keep non-overlapping statements and want to apply better rules to several years of transactions. It is especially useful when you manage several accounts or owners and want to review the changes to each statement's journal before committing them.

Choose plain hledger import if you want to append new transactions and then review, split or annotate them directly in your journal. Your edits survive the next import. This also suits rolling downloads such as “the last 90 days” from the same account. hledger remembers how far it got for each source, which works well when dates and the order of same-day transactions are stable. hledger-flow processes each statement independently, so overlapping files can count the same purchase twice. You can keep the original CSVs with either workflow. See hledger's import guide.

Overview of the Basic Workflow

  1. Save each statement under its account and year.
  2. Add an hledger rules file for the account or bank. For most bank CSVs, rules are all you need.
  3. Run hledger-flow import from the base directory. Use the generated all-years.journal as your LEDGER_FILE.
  4. Commit the statements, rules, manual journals and generated journals to version control so you can review the effect of later rule changes.

Example: reclassify purchases across three years

Suppose your 2023–2025 statements are already imported and committed. Purchases from City Rail currently appear under expenses:misc. You also recorded a one-off cash fare by hand in import/john/_manual_/2024/post-import.journal. Keep handwritten adjustments in a manual journal, since each full import rewrites the statement journals in 3-journal/.

Add this rule to import/mybank.rules, the rules file used by those statements:

if %description City Rail
  account2 expenses:transport

From the base directory, rebuild all three years and review the changes:

hledger-flow import
git diff -- import/
hledger -f all-years.journal print expenses:transport

The diff should show the rule and the matching purchases moving from expenses:misc to expenses:transport in each affected statement journal. The cash fare stays in the manual journal. If you booked it to expenses:transport, the last command shows it alongside the rebuilt entries.

How do I install it?

Install with Homebrew on macOS or Linux:

brew install ferntrail/tap/hledger-flow

Or download a release for Windows, macOS or Linux, or build from source. The quick start covers each option, how to verify a download, and your first import.

Documentation

The full documentation is at https://hledger-flow.github.io/:

Project Goals

My hledger files started to collect a bunch of supporting code that weren't really specific to my financial situation.

I want to extract and share as much as possible of that supporting code.

Adept's goals also resonated with me:

  • Tracking expenses should take as little time, effort and manual work as possible
  • Eventual consistency should be achievable: even if I can't record something precisely right now, maybe I would be able to do it later, so I should be able to leave things half-done and pick them up later
  • Ability to refactor is a must. I want to be able to go back and change the way I am doing things, with as little effort as possible and without fear of irrevocably breaking things.

Support

hledger-flow is supported by FernTrail B.V.

Contributing to hledger-flow

Have a look at the contribution guidelines.