Jacob Kiers
74d362b412
- Implement robust End User Agreement expiry detection and handling - Add graceful error recovery for failed accounts - Rewrite README.md to focus on user benefits - Add documentation guidelines to AGENTS.md
59 lines
2.0 KiB
Markdown
59 lines
2.0 KiB
Markdown
# Banks2FF
|
|
|
|
A robust command-line tool to synchronize bank transactions from GoCardless (formerly Nordigen) to Firefly III.
|
|
|
|
## ✨ Key Benefits
|
|
|
|
- **Automatic Transaction Sync**: Keep your Firefly III finances up-to-date with your bank accounts
|
|
- **Multi-Currency Support**: Handles international transactions and foreign currencies correctly
|
|
- **Smart Duplicate Detection**: Avoids double-counting transactions automatically
|
|
- **Reliable Operation**: Continues working even when some accounts need attention
|
|
- **Safe Preview Mode**: Test changes before applying them to your finances
|
|
- **Rate Limit Aware**: Works within API limits to ensure consistent access
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
- Rust (latest stable)
|
|
- GoCardless Bank Account Data account
|
|
- Running Firefly III instance
|
|
|
|
### Setup
|
|
1. Copy environment template: `cp env.example .env`
|
|
2. Fill in your credentials in `.env`:
|
|
- `GOCARDLESS_ID`: Your GoCardless Secret ID
|
|
- `GOCARDLESS_KEY`: Your GoCardless Secret Key
|
|
- `FIREFLY_III_URL`: Your Firefly instance URL
|
|
- `FIREFLY_III_API_KEY`: Your Personal Access Token
|
|
|
|
### Usage
|
|
```bash
|
|
# Sync all accounts (automatic date range)
|
|
cargo run -p banks2ff
|
|
|
|
# Preview changes without saving
|
|
cargo run -p banks2ff -- --dry-run
|
|
|
|
# Sync specific date range
|
|
cargo run -p banks2ff -- --start 2023-01-01 --end 2023-01-31
|
|
```
|
|
|
|
## 📋 What It Does
|
|
|
|
Banks2FF automatically:
|
|
1. Connects to your bank accounts via GoCardless
|
|
2. Finds matching accounts in your Firefly III instance
|
|
3. Downloads new transactions since your last sync
|
|
4. Adds them to Firefly III (avoiding duplicates)
|
|
5. Handles errors gracefully - keeps working even if some accounts have issues
|
|
|
|
## 🔧 Troubleshooting
|
|
|
|
- **Account not syncing?** Check that the IBAN matches between GoCardless and Firefly III
|
|
- **Missing transactions?** The tool syncs from the last transaction date forward
|
|
- **Rate limited?** The tool automatically handles API limits and retries appropriately
|
|
|
|
---
|
|
|
|
*For technical details, see [docs/architecture.md](docs/architecture.md)*
|