firefly-iii

---
name: firefly-iii
description: Manage personal finances via Firefly III API. Use when user asks about budgets, transactions, accounts, categories, piggy banks, subscriptions, recurring transactions, or financial reports. Supports creating, listing, updating transactions; managing accounts and balances; setting budgets; tracking savings goals.
---

# Firefly III

Firefly III is a self-hosted personal finance manager. This skill provides API access for managing finances.

## Configuration

Required environment:
- `FIREFLY_URL`: Base URL (e.g., `https://budget.example.com`)
- `FIREFLY_TOKEN`: Personal Access Token (stored at `~/.firefly_token`)

Get token: Profile → OAuth → Personal Access Tokens → Create new token

## API Basics

```bash
TOKEN=$(cat ~/.firefly_token)
BASE="$FIREFLY_URL/api/v1"
curl -s "$BASE/endpoint" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"
```

## Core Endpoints

### Accounts
```bash
# List accounts
curl "$BASE/accounts?type=asset" # asset|expense|revenue|liability
# Create account
curl -X POST "$BASE/accounts" -d '{
  "name": "Bank Account",
  "type": "asset",
  "account_role": "defaultAsset",
  "currency_code": "EUR"
}'
```

Account types: `asset`, `expense`, `revenue`, `liability`
Asset roles: `defaultAsset`, `savingAsset`, `sharedAsset`, `ccAsset`

### Transactions
```bash
# List transactions
curl "$BASE/transactions?type=withdrawal&start=2026-01-01&end=2026-01-31"
# Create withdrawal (expense)
curl -X POST "$BASE/transactions" -d '{
  "transactions": [{
    "type": "withdrawal",
    "date": "2026-01-15",
    "amount": "50.00",
    "description": "Groceries",
    "source_name": "Bank Account",
    "destination_name": "Supermarket",
    "category_name": "Groceries"
  }]
}'
# Create deposit (income)
curl -X POST "$BASE/transactions" -d '{
  "transactions": [{
    "type": "deposit",
    "date": "2026-01-01",
    "amount": "3000.00",
    "description": "Salary",
    "source_n