README.md

# Banks2FF

A robust command-line tool to synchronize bank transactions from GoCardless (formerly Nordigen) to Firefly III.

## ✨ Key Benefits

- **Automatic Transaction Sync**: Keep your Firefly III finances up-to-date with your bank accounts
- **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

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

### Usage
```bash
# Sync all accounts (automatic date range)
cargo run -p banks2ff

# Preview changes without saving
cargo run -p banks2ff -- --dry-run

# Sync specific date range
cargo run -p banks2ff -- --start 2023-01-01 --end 2023-01-31
```

## 📋 What It Does

Banks2FF automatically:
1. Connects to your bank accounts via GoCardless
2. Finds matching accounts in your Firefly III instance
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

## 🔧 Troubleshooting

- **Account not syncing?** Check that the IBAN matches between GoCardless and Firefly III
- **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)*
Implement logic 2025-11-19 21:18:37 +00:00			`# Banks2FF`

			`A robust command-line tool to synchronize bank transactions from GoCardless (formerly Nordigen) to Firefly III.`

Handle expired agreements and rewrite README - Implement robust End User Agreement expiry detection and handling - Add graceful error recovery for failed accounts - Rewrite README.md to focus on user benefits - Add documentation guidelines to AGENTS.md 2025-11-21 17:04:31 +01:00			`## ✨ Key Benefits`

			`- Automatic Transaction Sync: Keep your Firefly III finances up-to-date with your bank accounts`
			`- 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`

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

			`### Usage`
Implement logic 2025-11-19 21:18:37 +00:00			```bash
Handle expired agreements and rewrite README - Implement robust End User Agreement expiry detection and handling - Add graceful error recovery for failed accounts - Rewrite README.md to focus on user benefits - Add documentation guidelines to AGENTS.md 2025-11-21 17:04:31 +01:00			`# Sync all accounts (automatic date range)`
Implement logic 2025-11-19 21:18:37 +00:00			`cargo run -p banks2ff`

Handle expired agreements and rewrite README - Implement robust End User Agreement expiry detection and handling - Add graceful error recovery for failed accounts - Rewrite README.md to focus on user benefits - Add documentation guidelines to AGENTS.md 2025-11-21 17:04:31 +01:00			`# Preview changes without saving`
Implement logic 2025-11-19 21:18:37 +00:00			`cargo run -p banks2ff -- --dry-run`

Handle expired agreements and rewrite README - Implement robust End User Agreement expiry detection and handling - Add graceful error recovery for failed accounts - Rewrite README.md to focus on user benefits - Add documentation guidelines to AGENTS.md 2025-11-21 17:04:31 +01:00			`# Sync specific date range`
Implement logic 2025-11-19 21:18:37 +00:00			`cargo run -p banks2ff -- --start 2023-01-01 --end 2023-01-31`
			```

Handle expired agreements and rewrite README - Implement robust End User Agreement expiry detection and handling - Add graceful error recovery for failed accounts - Rewrite README.md to focus on user benefits - Add documentation guidelines to AGENTS.md 2025-11-21 17:04:31 +01:00			`## 📋 What It Does`

			`Banks2FF automatically:`
			`1. Connects to your bank accounts via GoCardless`
			`2. Finds matching accounts in your Firefly III instance`
			`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`

			`## 🔧 Troubleshooting`

			`- Account not syncing? Check that the IBAN matches between GoCardless and Firefly III`
			`- Missing transactions? The tool syncs from the last transaction date forward`
			`- Rate limited? The tool automatically handles API limits and retries appropriately`

			`---`
Implement logic 2025-11-19 21:18:37 +00:00
Handle expired agreements and rewrite README - Implement robust End User Agreement expiry detection and handling - Add graceful error recovery for failed accounts - Rewrite README.md to focus on user benefits - Add documentation guidelines to AGENTS.md 2025-11-21 17:04:31 +01:00			`For technical details, see [docs/architecture.md](docs/architecture.md)`