Jacob Kiers
c3d74fa6ae
The accounts lists are now shown per source and/or destination, and include the name. Furthermore they are sorted alphabetically by name, because that is how humans think.
108 lines
4.7 KiB
Markdown
108 lines
4.7 KiB
Markdown
# Banks2FF
|
|
|
|
A robust command-line tool to synchronize bank transactions between various sources and destinations. Currently supports GoCardless (formerly Nordigen) to Firefly III, with extensible architecture for additional sources and destinations.
|
|
|
|
## ✨ Key Benefits
|
|
|
|
- **Automatic Transaction Sync**: Keep your Firefly III finances up-to-date with your bank accounts
|
|
- **Intelligent Caching**: Reduces GoCardless API calls by up to 99% through encrypted local storage
|
|
- **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
|
|
- **Flexible Account Linking**: Automatically match bank accounts to Firefly III accounts, with manual override options
|
|
|
|
## 🚀 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
|
|
- `BANKS2FF_CACHE_KEY`: Required encryption key for secure transaction caching
|
|
|
|
### Usage
|
|
```bash
|
|
# Sync all accounts (automatic date range)
|
|
cargo run -p banks2ff -- sync gocardless firefly
|
|
|
|
# Preview changes without saving
|
|
cargo run -p banks2ff -- --dry-run sync gocardless firefly
|
|
|
|
# Sync specific date range
|
|
cargo run -p banks2ff -- sync gocardless firefly --start 2023-01-01 --end 2023-01-31
|
|
|
|
# List available sources and destinations
|
|
cargo run -p banks2ff -- sources
|
|
cargo run -p banks2ff -- destinations
|
|
|
|
# Inspect accounts
|
|
cargo run -p banks2ff -- accounts list
|
|
cargo run -p banks2ff -- accounts list gocardless # Only GoCardless accounts
|
|
cargo run -p banks2ff -- accounts list firefly # Only Firefly III accounts
|
|
cargo run -p banks2ff -- accounts status
|
|
|
|
# Manage account links
|
|
cargo run -p banks2ff -- accounts link list
|
|
cargo run -p banks2ff -- accounts link create <source_account> <dest_account>
|
|
|
|
# Inspect transactions and cache
|
|
cargo run -p banks2ff -- transactions list <account_id>
|
|
cargo run -p banks2ff -- transactions cache-status
|
|
```
|
|
|
|
## 🖥️ CLI Structure
|
|
|
|
Banks2FF uses a structured command-line interface with the following commands:
|
|
|
|
- `sync <SOURCE> <DESTINATION>` - Synchronize transactions between source and destination
|
|
- `sources` - List all available source types
|
|
- `destinations` - List all available destination types
|
|
- `accounts list [gocardless|firefly]` - List all discovered accounts (optionally filter by adapter type)
|
|
- `accounts status` - Show sync status for all accounts
|
|
- `accounts link` - Manage account links between sources and destinations
|
|
- `transactions list <account_id>` - Show transaction information for a specific account
|
|
- `transactions cache-status` - Display cache status and statistics
|
|
- `transactions clear-cache` - Clear transaction cache (implementation pending)
|
|
|
|
Use `cargo run -p banks2ff -- --help` for detailed command information.
|
|
|
|
## 📋 What It Does
|
|
|
|
Banks2FF automatically:
|
|
1. Connects to your bank accounts via GoCardless
|
|
2. Discovers and links accounts between GoCardless and Firefly III (with auto-matching and manual options)
|
|
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
|
|
|
|
## 🔐 Secure Transaction Caching
|
|
|
|
Banks2FF automatically caches your transaction data to make future syncs much faster:
|
|
|
|
- **Faster Syncs**: Reuses previously downloaded data instead of re-fetching from the bank
|
|
- **API Efficiency**: Dramatically reduces the number of calls made to GoCardless
|
|
- **Secure Storage**: Your financial data is safely encrypted on your local machine
|
|
- **Automatic Management**: The cache works transparently in the background
|
|
|
|
The cache requires `BANKS2FF_CACHE_KEY` to be set in your `.env` file for secure encryption (see `env.example` for key generation instructions).
|
|
|
|
## 🔧 Troubleshooting
|
|
|
|
- **Unknown source/destination?** Use `sources` and `destinations` commands to see what's available
|
|
- **Account not syncing?** Check that the IBAN matches between GoCardless and Firefly III, or use `accounts link` to create manual links
|
|
- **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)*
|