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

# 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