Add money: statement-driven personal finance tracker
A data directory holds one folder per account. Statements dropped into those folders are parsed into a rebuildable SQLite index, categorised by ordered glob rules in rules.toml, and browsed or hand-tagged in a Bubble Tea TUI. Movements between the user's own accounts are marked as transfers by the same rules and excluded from spending totals. Manual tags and transfer marks are stored separately from the rule-derived ones and always win, so editing rules.toml and re-running retag never destroys hand edits. Parsers are pluggable. Three are ported from the Python extractors they replace -- nlb and traderepublic read PDFs via pdftotext -layout, revolut reads the CSV export -- alongside a configurable-column CSV parser and a cmd parser that shells out to an external script. Both ports fix two latent bugs in the originals: the sign character class rejected the typographic minus U+2212 that some PDF fonts emit, and NLB's hardcoded continuation indent broke when pdftotext compressed runs of spaces, so the threshold is now measured from the description column. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -0,0 +1,229 @@
|
||||
# money
|
||||
|
||||
A personal finance tracker built around bank statements rather than manual entry.
|
||||
|
||||
You keep a **data directory with one folder per account**, drop statement exports
|
||||
into those folders, and run `money import`. Transactions are extracted, tagged by
|
||||
glob rules you write, and movements between your own accounts are marked as
|
||||
transfers so they never count as spending.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
~/money/ # the data root ($MONEY_ROOT, or --root)
|
||||
rules.toml # tag + transfer rules, in order
|
||||
.money/index.db # SQLite index (rebuildable; safe to delete*)
|
||||
checking/
|
||||
account.toml # currency + how to parse this bank's exports
|
||||
2026-01.csv
|
||||
2026-02.csv
|
||||
savings/
|
||||
account.toml
|
||||
2026-01.csv
|
||||
```
|
||||
|
||||
\* Deleting the index loses manual tags and manual transfer marks, which live
|
||||
only there. Everything else is re-derived from the statements.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
money # open the TUI (default)
|
||||
money import # extract new transactions from every statement
|
||||
money import --force # re-parse statements even if unchanged
|
||||
money retag # re-apply rules.toml to everything already imported
|
||||
money ls --untagged # what still needs a tag
|
||||
money ls --wide # also show type, counterparty and reported balance
|
||||
money ls --account checking --month 2026-01
|
||||
money report --month 2026-01 # spending by tag
|
||||
money accounts # balances
|
||||
money parsers # available statement parsers
|
||||
```
|
||||
|
||||
### TUI keys
|
||||
|
||||
| Key | Action |
|
||||
| --- | --- |
|
||||
| `1` `2` `3` / `tab` | accounts · transactions · report |
|
||||
| `enter` | open the selected account (accounts view) |
|
||||
| `t` | set the tag on the selected transaction |
|
||||
| `x` | toggle transfer on the selected transaction |
|
||||
| `c` | clear manual overrides, falling back to the rules |
|
||||
| `/` | filter by description |
|
||||
| `u` | show only untagged transactions |
|
||||
| `a` | clear the account filter |
|
||||
| `i` | import · `r` re-apply rules · `q` quit |
|
||||
|
||||
## rules.toml
|
||||
|
||||
Rules are evaluated in file order and the **first match wins**, so put transfer
|
||||
rules above general tag rules. Patterns are globs (`*` and `?`) matched
|
||||
case-insensitively, with whitespace collapsed.
|
||||
|
||||
A rule matches on `match` (the description), `counterparty` (the other side's
|
||||
account number) and `type` (the bank's own classification). Setting several is
|
||||
an "and": all must match.
|
||||
|
||||
```toml
|
||||
[[rule]]
|
||||
tag = "groceries"
|
||||
match = "*LIDL*"
|
||||
|
||||
[[rule]]
|
||||
tag = "salary"
|
||||
match = "*ACME PAYROLL*"
|
||||
|
||||
# Money moved between your own accounts. Both legs need a rule.
|
||||
[[rule]]
|
||||
match = "*TO SAVINGS*"
|
||||
transfer = true
|
||||
tag = "transfer"
|
||||
|
||||
[[rule]]
|
||||
match = "*FROM CHECKING*"
|
||||
transfer = true
|
||||
tag = "transfer"
|
||||
|
||||
# Transfers are often only identifiable by the counterparty IBAN, whatever
|
||||
# the description happens to say.
|
||||
[[rule]]
|
||||
counterparty = "SI56*"
|
||||
transfer = true
|
||||
tag = "transfer"
|
||||
|
||||
# A rule can be limited to one account, and can require several patterns.
|
||||
[[rule]]
|
||||
account = "checking"
|
||||
tag = "rent"
|
||||
match = "*STANDING ORDER 4471*"
|
||||
|
||||
[[rule]]
|
||||
type = "CARD_PAYMENT"
|
||||
match = "*LIDL*"
|
||||
tag = "groceries"
|
||||
```
|
||||
|
||||
Editing rules never touches tags you set by hand: rule verdicts and manual
|
||||
overrides are stored separately, and the manual one always wins. `money retag`
|
||||
is therefore safe to run whenever you change the file.
|
||||
|
||||
## account.toml
|
||||
|
||||
Every account folder needs one. `currency` and `parser` are required.
|
||||
|
||||
```toml
|
||||
name = "Main Checking"
|
||||
currency = "EUR"
|
||||
parser = "csv"
|
||||
# minor_digits = 2 # decimal places for this currency
|
||||
# include = ["*.csv"] # only treat matching files as statements
|
||||
```
|
||||
|
||||
### `parser = "csv"`
|
||||
|
||||
Column positions are 0-based.
|
||||
|
||||
```toml
|
||||
[csv]
|
||||
delimiter = "," # default ","
|
||||
skip_rows = 1 # header rows to drop
|
||||
date = { col = 0, layout = "02.01.2006" } # Go reference layout
|
||||
description = { col = 3 }
|
||||
amount = { col = 4, decimal = ",", thousands = "." }
|
||||
# invert = true # if outflows are written as positive
|
||||
```
|
||||
|
||||
For statements with separate debit and credit columns, replace `amount`:
|
||||
|
||||
```toml
|
||||
debit = { col = 4 } # both written as positive numbers
|
||||
credit = { col = 5 }
|
||||
```
|
||||
|
||||
Amount parsing is deliberately tolerant: `1.234,56`, `-45.20`, `45,20-`,
|
||||
`(45.20)` and `45.20 EUR` all work.
|
||||
|
||||
### Bank-specific parsers
|
||||
|
||||
Three are built in, ported from the original Python extractors. They need no
|
||||
`[csv]` block — the layout is baked in.
|
||||
|
||||
| `parser` | Statement | Notes |
|
||||
| --- | --- | --- |
|
||||
| `nlb` | NLB izpisek PDF | Wrapped descriptions and the counterparty IBAN are folded in from continuation lines. |
|
||||
| `traderepublic` | Trade Republic PDF | Handles both the single-line and the stacked layout by measuring column positions. |
|
||||
| `revolut` | `account-statement*.csv` | Skips non-COMPLETED rows, folds the fee into the amount. |
|
||||
|
||||
```toml
|
||||
name = "Trade Republic"
|
||||
currency = "EUR"
|
||||
parser = "traderepublic"
|
||||
```
|
||||
|
||||
The two PDF parsers shell out to `pdftotext -layout` (poppler-utils), exactly
|
||||
as the Python versions did; its layout reconstruction is what makes the
|
||||
column-based parsing work.
|
||||
|
||||
**Revolut and multiple currencies.** One export can hold several currencies,
|
||||
but an account here has exactly one. Rows in other currencies are skipped and
|
||||
reported at import. To keep them, give that currency its own account folder
|
||||
with its own `currency` and `minor_digits` (JPY wants `minor_digits = 0`) and
|
||||
put a copy or symlink of the export in it.
|
||||
|
||||
### `parser = "cmd"`
|
||||
|
||||
Runs an external extractor and reads normalised CSV (`date,description,amount`)
|
||||
from its stdout. This is how PDF statements and any existing Python extractor
|
||||
are handled without porting them first.
|
||||
|
||||
```toml
|
||||
parser = "cmd"
|
||||
[cmd]
|
||||
argv = ["python3", "../extract_bankx.py", "{{file}}"]
|
||||
skip_rows = 1 # if the script prints a header
|
||||
# layout = "2006-01-02" # date format the script emits (default)
|
||||
```
|
||||
|
||||
`{{file}}` is replaced with the statement's path, and the command runs with the
|
||||
account folder as its working directory, so relative script paths work.
|
||||
|
||||
## Adding a native parser
|
||||
|
||||
When a Python extractor is ported to Go, drop it in `internal/parser` and
|
||||
register it — no other package changes:
|
||||
|
||||
```go
|
||||
func init() {
|
||||
parser.Register("bankx", func(acc *config.Account) (parser.Parser, error) {
|
||||
return &bankXParser{digits: acc.Digits()}, nil
|
||||
})
|
||||
}
|
||||
|
||||
func (p *bankXParser) Parse(path string, acc *config.Account) ([]parser.RawTxn, error) {
|
||||
// ... return date (YYYY-MM-DD), description, and signed minor units
|
||||
}
|
||||
```
|
||||
|
||||
It becomes usable by setting `parser = "bankx"` in an account.toml. Use
|
||||
`parser.ParseAmount` for the decimal handling rather than rolling your own.
|
||||
|
||||
## Balance checks
|
||||
|
||||
Statements that report a running balance are verified on import: each balance
|
||||
must equal the previous one plus the transaction amount, the same check all
|
||||
three original scripts made. A break means a row was missed or misparsed, and
|
||||
is reported as a warning without stopping the import.
|
||||
|
||||
## Deduplication
|
||||
|
||||
Each transaction gets a fingerprint from its date, amount, normalised
|
||||
description, and its ordinal among identical lines in the same statement. So
|
||||
two identical purchases on one day are both kept, while re-importing an
|
||||
overlapping statement adds nothing. Unchanged files are skipped by checksum
|
||||
before parsing.
|
||||
|
||||
## Development
|
||||
|
||||
```
|
||||
go build ./... && go test ./...
|
||||
```
|
||||
Reference in New Issue
Block a user