gabrielkoerich Beancount Analytics
Generate fast financial summaries from a Beancount ledger, including:
- last month report
- last 12 months trend
- top expense categories
- direct question style queries
Requirements
# Using pip
pip install beancount
# Using uv
uv install beancount
Commands
| Command | Usage |
|---|---|
| Last month | python3 scripts/report.py --ledger /path/main.bean --period last-month |
| Last 12 months | python3 scripts/report.py --ledger /path/main.bean --period last-12-months |
| Top expenses | python3 scripts/report.py --ledger /path/main.bean --period last-month --top 10 |
| JSON output | python3 scripts/report.py --ledger /path/main.bean --period last-12-months --json |
| Ask directly | python3 scripts/ask.py --ledger /path/main.bean --question "How much did I spend last month?" |
Periods
last-month: previous calendar monthlast-12-months: trailing 12 calendar months including current monthmonth:YYYY-MM: specific month
Data Model
The scripts read Beancount transactions and aggregate postings where account starts with:
Income:Expenses:
Output includes:
- total income
- total expenses
- net savings (
income - expenses) - top expense categories
Suggested Workflow
- Run
report.pyforlast-monthfor an executive snapshot. - Run
report.pyforlast-12-monthsto inspect consistency and trend. - Use
ask.pyfor direct ad-hoc questions. - If you need custom SQL-like analysis, run
bean-querydirectly from your finance repo.
Examples
python3 scripts/report.py --ledger /path/to/ledger/main.bean --period last-month
python3 scripts/report.py --ledger /path/to/ledger/main.bean --period last-12-months
python3 scripts/ask.py --ledger /path/to/ledger/main.bean --question "Show top expenses last month"