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
• Smart Account Linking: Automatically match bank accounts to Firefly III accounts, with interactive and intelligent manual linking 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                    # Interactive mode - guided account selection
cargo run -p banks2ff -- accounts link create "Account Name"     # Smart mode - auto-detect source/destination
cargo run -p banks2ff -- accounts link create <source> <dest>    # Direct mode - for scripts

# Inspect transactions and cache
cargo run -p banks2ff -- transactions list                    # Interactive account selection
cargo run -p banks2ff -- transactions list "Account Name"     # By name/IBAN
cargo run -p banks2ff -- transactions list --details          # Show actual transactions
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 (with interactive and smart modes)
• transactions list [account] [--details] [--limit N] - Show transaction summary or details for an account (interactive selection if no account specified)
• transactions cache-status - Display cache status and statistics

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 accounts and provides intelligent linking between GoCardless and Firefly III
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

The account linking system automatically matches accounts by IBAN, but also provides interactive tools for manual linking when needed.

🔗 Smart Account Linking

Banks2FF provides multiple ways to link your bank accounts to Firefly III accounts:

Interactive Mode

cargo run -p banks2ff -- accounts link create

Shows you unlinked bank accounts and guides you through selecting destination accounts with human-readable names.

Smart Resolution

cargo run -p banks2ff -- accounts link create "Main Checking"

Automatically finds accounts by name, IBAN, or ID and shows appropriate linking options.

Direct Linking (for Scripts)

cargo run -p banks2ff -- accounts link create <source_id> <destination_id>

Perfect for automation - uses exact account IDs for reliable scripting.

Key Features

• Auto-Linking: Automatically matches accounts with identical IBANs during sync
• Manual Override: Create custom links when auto-matching isn't sufficient
• Constraint Enforcement: One bank account can only link to one Firefly account (prevents duplicates)
• Human-Friendly: Uses account names and masked IBANs for easy identification

📊 Transaction Inspection

Banks2FF provides flexible ways to inspect your transaction data without needing to access Firefly III directly:

Summary View (Default)

cargo run -p banks2ff -- transactions list

Shows an interactive menu of accounts with transaction data, then displays summary statistics including total count, date range, and last update.

Transaction Details

cargo run -p banks2ff -- transactions list --details --limit 50

Shows recent transactions with amounts, descriptions, and counterparties.

Account Selection

cargo run -p banks2ff -- transactions list "Main Checking"
cargo run -p banks2ff -- transactions list NL12ABCD0123456789

Find accounts by name, IBAN, or ID. Use no argument for interactive selection.

🔐 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 create for interactive linking
• Can't find account by name? Use accounts list to see all available accounts with their IDs and names
• Link creation failed? Each bank account can only link to one Firefly account - check existing links with accounts link list
• No transactions showing? Use transactions list to check if data has been cached; run sync first if needed
• Can't find account for transactions? Use transactions list without arguments for interactive account selection
• 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