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

```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                    # 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

```bash
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

```bash
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)

```bash
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)

```bash
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

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

Shows recent transactions with amounts, descriptions, and counterparties.

### Account Selection

```bash
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](docs/architecture.md)*