Firefly III Client Skill

Purpose

A production-ready client for Firefly III personal finance management, allowing for programmatic access to transactions, accounts, recurring rules, and automation.

Security Considerations

See SECURITY.md for information on token safety, environment variables, and network security when using this skill.

Setup

1. Ensure Firefly III is running and you have an OAuth Personal Access Token.
2. Set the following environment variables:

```bash

FIREFLY_URL=http://your-instance-url

FIREFLY_TOKEN=your_personal_access_token

```

1. Install dependencies:

```bash

pip install requests

```

CLI Reference

The api.py script serves as a generic wrapper for the Firefly III REST API.

• python3 api.py request [-d ]

Examples

• List Accounts:

python3 api.py request GET api/v1/accounts

• Create Transaction:

python3 api.py request POST api/v1/transactions -d '{"amount": "10.00", "description": "Coffee", "source_id": 1, "destination_id": 2, "date": "2026-04-06", "type": "withdrawal"}'

• Create Recurring Transaction:

python3 api.py request POST api/v1/recurrences -d '{"type": "withdrawal", "title": "Example", "first_date": "2026-04-30", "repeat_freq": "monthly", "nr_of_repetitions": 12, "repetitions": [{"type": "monthly", "moment": "30"}], "transactions": [{"description": "Item", "amount": "100.00", "source_id": 1, "destination_id": 2}]}'

• Create Rule:

python3 api.py request POST api/v1/rules -d '{"title": "Example Rule", "trigger": "destination_account_is", "value": "Netflix", "action": "link_to_bill", "action_value": "Netflix Bill"}'