Jacob Kiers
baac50c36a
- Enhanced CLI output with table formatting for better readability of account and transaction data - Added new commands to list accounts and view their sync status - Added new commands to inspect transaction information and cache status - Cleaned up internal code by removing unused trait methods and implementations - Updated documentation with examples of new CLI commands This improves the user experience with clearer CLI output and new inspection capabilities while maintaining code quality.
106 lines
4.5 KiB
Markdown
106 lines
4.5 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 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` - List all discovered accounts
|
|
- `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)*
|