Personal Finance Budget (pfbudget)

A budgeting tool for those who want full control and transparency over their finances.

Features

• Bank Data Ingestion:
  • Download transactions directly from banks via a PSD2 aggregator (using the GoCardless API).
  • Or, parse CSV bank extracts using configurable YAML-based parsers (parsers.yaml).
• Database Storage:
  • All transactions and categorization rules are stored in a PostgreSQL database.
• Rules-Based Categorization:
  • Automatically categorize transactions using rules stored in the database.
  • Interactive mode for manual categorization of remaining transactions.

Note: Graphical reporting is currently broken. For now, you can run SQL queries directly on the database for custom reports.

Quick Start

1. Install dependencies

This project uses Poetry:

poetry install

2. Configure

• Database: Set up a PostgreSQL database and configure your connection through a .env file.
• GoCardless credentials: Create an account with GoCardless (previously Nordigen) and save them on the .env file.
• Bank Parsers: For CSV parsing, edit parsers.yaml to match your bank’s CSV format. If the CSV is more complex than the basic rules can handle, you can enable additional_parser: true and implement a parser class in pfbudget/extract/parsers.py. The Bank1 is an example implementation.

3. Run

You can run the app as a module:

poetry run python3 -m pfbudget [options]

Example workflows

• Download from bank aggregator: First step is to accept an End User Agreement with the bank in question to get access to your own data:

  poetry run python3 -m pfbudget eua your_bank

  poetry run python3 -m pfbudget download --banks your_bank

• Parse CSV:

  poetry run python3 -m pfbudget parse --bank your_bank export.csv

• Automatic categorization:

  poetry run python3 -m pfbudget categorize auto

• Interactive categorization:

  poetry run python3 -m pfbudget categorize manual

Available Commands

The CLI supports a variety of operations. Here are the main commands:

• export: Export transactions to a specified file and format.
• import: Import transactions from a specified file and format.
• parse: Parse transactions from CSV files (with optional bank and credit card arguments).
• categorize
  • auto: Automatically categorize transactions using rules.
  • manual: Manually categorize uncategorized transactions.
• bank
  • add, del, mod: Manage bank definitions.
  • psd2: Manage PSD2 bank connections.
  • export, import: Export/import bank definitions.
• token: Manage PSD2 access tokens.
• eua: Manage PSD2 requisition IDs.
• download: Download transactions from banks via PSD2 API.
• banks: List available banks in a country.
• category
  • add, remove, update, schedule: Manage categories.
  • rule: Manage categorization rules (add, remove, modify, export, import).
  • group: Manage category groups (add, remove, export, import).
  • export, import: Export/import categories.
• tag
  • add, remove: Manage tags.
  • rule: Manage tag rules (add, remove, modify, export, import).
• link
  • forge, dismantle: Link or unlink transactions.

Each command may have additional options and subcommands. For details, run:

poetry run python3 -m pfbudget --help

or for a specific command:

poetry run python3 -m pfbudget <command> --help

---

License: GPL-3.0-or-later Author: Luís Murta [email protected]