gnucash2firefly/README.md

# GnuCash to Firefly III Migration Tool

This tool helps you migrate your financial data from GnuCash to Firefly III automatically using the piecash library for robust GnuCash file parsing.

## What it does

- **Connects to your GnuCash SQLite database** using piecash library for reliable parsing
- **Creates corresponding accounts in Firefly III** with proper hierarchical names and account types
- **Migrates transactions** between accounts with dates, amounts, and descriptions
- **Handles multiple currencies** by enabling them in Firefly III first
- **Provides safety features** like test limits and accounts-only migration

## What gets migrated

### Accounts
- All account types (assets, liabilities, expenses, income) with proper type mapping
- **Full hierarchical account names** (e.g., "Assets:Current Assets:Checking Account")
- Account descriptions and account numbers
- Currency information
- Placeholder accounts are skipped as they're organizational only

### Transactions
- Simple 2-split transactions with dates, amounts, descriptions
- Transaction memos/notes
- Multi-currency support
- Complex split transactions are logged but skipped for manual review

## Requirements

```bash
pip install -r requirements.txt
```

Or manually:
```bash
pip install requests python-dateutil piecash
```

## Setup

1. **Get your Firefly III API token**
   - Log into your Firefly III instance
   - Go to Options → Profile → OAuth → Personal Access Tokens
   - Create a new token and copy it

2. **Set your API token** (choose one method):
   
   **Option A: Environment variable**
   ```bash
   export FIREFLY_TOKEN="your_actual_token_here"
   ```
   
   **Option B: Command line argument**
   ```bash
   python g2f.py --firefly-token "your_actual_token_here" [other options]
   ```

3. **Export your GnuCash data to SQLite format**
   - In GnuCash: File → Export → Export Accounts
   - Choose SQLite format and save the .gnucash file

## Usage


### Migrate accounts only (useful for initial setup):
```bash
python g2f.py \
  --gnucash-db "path/to/your/file.gnucash" \
  --firefly-url "https://your-firefly-instance.com" \
  --accounts-only
```

### Test with a few transactions:
```bash
python g2f.py \
  --gnucash-db "path/to/your/file.gnucash" \
  --firefly-url "https://your-firefly-instance.com" \
  --test-limit 5
```

### Full migration:
```bash
python g2f.py \
  --gnucash-db "path/to/your/file.gnucash" \
  --firefly-url "https://your-firefly-instance.com"
```

## Command Line Options

- `--gnucash-db` - Path to your GnuCash SQLite database file (required)
- `--firefly-url` - Your Firefly III base URL (required)  
- `--firefly-token` - API token (optional if using FIREFLY_TOKEN environment variable)
- `--test-limit` - Limit number of transactions for testing (optional)
- `--accounts-only` - Only migrate accounts, skip transactions

## Safety Features

- **Test limits**: Use `--test-limit` to migrate only a few transactions first
- **Accounts-only mode**: Use `--accounts-only` to set up account structure first
- **Detailed logging**: All actions are logged with timestamps
- **Error handling**: Failed operations are logged and don't stop the entire migration
- **Hierarchical account names**: Full GnuCash account paths preserve your organization

## Account Type Mapping

GnuCash types are mapped to Firefly III types as follows:

| GnuCash Type | Firefly III Type |
|--------------|------------------|
| ASSET, BANK, CASH, CHECKING, SAVINGS, INVESTMENT, STOCK | asset |
| LIABILITY, CREDIT, CREDITCARD, LOAN | liability |
| EXPENSE | expense |
| INCOME | revenue |
| EQUITY, RECEIVABLE | asset |
| PAYABLE | liability |

## Account Hierarchy

GnuCash's hierarchical account structure is preserved by using full account paths as names in Firefly III:

- GnuCash: `Assets` → `Current Assets` → `Checking Account`
- Firefly III: `Assets:Current Assets:Checking Account`

This maintains your account organization while working within Firefly III's flat account structure.

## Important Notes

- **Always backup your Firefly III data** before running a migration
- **Test with accounts-only first** using `--accounts-only` to verify account structure
- **Then test with a small subset** using `--test-limit`
- **Complex transactions** (more than 2 splits) are logged but not migrated - review these manually
- **Placeholder accounts** are skipped as they're organizational only

## Troubleshooting

1. **"Failed to connect to GnuCash database"**
   - Make sure the file path is correct
   - Ensure the file is in SQLite format (exported from GnuCash)
   - Check that piecash can read your GnuCash version

2. **"Failed to connect to Firefly III"**
   - Check your Firefly III URL is correct and accessible
   - Verify your API token is valid
   - Ensure FIREFLY_TOKEN environment variable is set or use --firefly-token

3. **"Missing account mapping for transaction"**
   - Some accounts may have failed to create in Firefly III
   - Check the logs for account creation errors
   - Run with --accounts-only first to debug account issues

## Example Output

```
2024-01-01 10:00:00 - INFO - Connected to GnuCash database: data.gnucash
2024-01-01 10:00:01 - INFO - Successfully connected to Firefly III API
2024-01-01 10:00:02 - INFO - Found 45 accounts in GnuCash
2024-01-01 10:00:03 - INFO - Enabled currency: USD
2024-01-01 10:00:04 - INFO - Created account: Assets:Current Assets:Checking Account -> 123
2024-01-01 10:00:05 - INFO - Successfully created 42 accounts
2024-01-01 10:00:06 - INFO - Found 1250 transactions in GnuCash
2024-01-01 10:00:15 - INFO - Successfully created 1180 out of 1250 transactions
2024-01-01 10:00:15 - INFO - Migration completed! Migrated 42 accounts and 1180 transactions
```

## Migration Workflow

1. **Create accounts**: `python g2f.py --gnucash-db file.gnucash --firefly-url URL --accounts-only`
2. **Migrate sample**: `python g2f.py --gnucash-db file.gnucash --firefly-url URL --test-limit 10`
3. **Full migration**: `python g2f.py --gnucash-db file.gnucash --firefly-url URL`