116 lines
3.6 KiB
Markdown
116 lines
3.6 KiB
Markdown
# 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](https://python-poetry.org/):
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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:
|
||
```sh
|
||
poetry run python3 -m pfbudget eua your_bank
|
||
```
|
||
```sh
|
||
poetry run python3 -m pfbudget download --banks your_bank
|
||
```
|
||
- **Parse CSV:**
|
||
```sh
|
||
poetry run python3 -m pfbudget parse --bank your_bank export.csv
|
||
```
|
||
|
||
- **Automatic categorization:**
|
||
```sh
|
||
poetry run python3 -m pfbudget categorize auto
|
||
```
|
||
|
||
- **Interactive categorization:**
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
poetry run python3 -m pfbudget --help
|
||
```
|
||
|
||
or for a specific command:
|
||
|
||
```sh
|
||
poetry run python3 -m pfbudget <command> --help
|
||
```
|
||
|
||
---
|
||
|
||
**License:** GPL-3.0-or-later
|
||
**Author:** Luís Murta <luis@murta.dev>
|