banks2ff/README.md

# 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)*