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), cryptohash-sha256 (>=0.11 && <0.12), 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), unix (>=2.8 && <2.9), Win32 (>=2.14 && <2.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-16T07:52:41Z
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-16 [all 1 reports]

Readme for hledger-flow-0.20.1

[back to package description]

hledger-flow

What is it?

Keep every statement. Rebuild your journals from them.

hledger-flow is a command-line workflow for hledger, the plain-text accounting tool. hledger keeps your accounts in journals: human-readable text files you can open in any editor, in a format that hledger reads and that Ledger and other plain-text accounting tools largely share.

hledger-flow is opinionated about where files live. You save each statement, exactly as your bank issued it, in a folder for its owner, institution, account and year. hledger-flow import converts each one with your hledger rules, or a script for formats rules can't read, and links the journals through all-years.journal. The statements stay as permanent input, so every journal can be rebuilt from its source and every entry traced to the statement it came from.

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

Who should use this?

There are many ways to keep your finances with hledger, and hledger's workflows page describes them. Three of them handle bank statements in quite different ways:

  • hledger import. Your journal is the primary record. You classify, split and annotate entries by editing the journal, and a better rule changes future imports only. Overlapping downloads are fine: hledger skips entries it has already imported, as long as their dates and same-day order stay stable. How hledger import works
  • Read the CSV directly. The CSV files are the record and nothing is generated. You classify by editing the rules, and a better rule applies the next time hledger reads the file. Suits a few files you name yourself, as in hledger -f checking.csv bal. The hledger 1.99 previews can also include a CSV in a journal. Reading CSV with hledger
  • hledger-flow. The original statements are the primary record, and journals are rebuilt from them. You classify by editing rules files, and a better rule rebuilds every journal that uses it, in every year. A fixed folder for each owner, institution, account and year keeps years of statements maintainable. An account's statements must not overlap, or a purchase appears twice.

Choose hledger import if your journal is your primary record and you want to edit it by hand. Choose hledger-flow if you want to generate your journals from statements exactly as they came from the source, classify by editing rules, and keep years of files in a structure that stays maintainable and auditable.

Full-fledged hledger teaches this last approach with build scripts you can adapt. hledger-flow packages the folder conventions, import and standard reports as CLI commands. Full-fledged hledger’s principles and practices

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 Linux or macOS:

brew install ferntrail/tap/hledger-flow

Or download a release for Linux, macOS, or Windows, 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.