firefly-reports
Generate 26 financial reports (PDF + Excel) from a Firefly III instance. Designed for individuals, freelancers and small businesses who want a complete annual financial overview.
Quick start
pip install firefly-iii-reports
firefly-reports \
--url https://your-firefly-instance.example.com \
--year 2025 \
--owner "Your Name" --out ./output
To run from source instead, clone the repo and use python -m firefly_reports.main in place of firefly-reports (dependencies: pip install -r firefly_reports/requirements.txt).
Use --year YYYY for a full calendar year (all reports), or --start/--end for a custom date range — in date-range mode the year-only reports (YoY, Historical Growth, Liquidity Forecast) are skipped.
The token can be provided via --token, the FIREFLY_TOKEN environment variable, a .env file, a firefly-reports.toml config file, or an interactive prompt.
Reports generated
Standard (always generated)
| # | Report | Description |
|---|---|---|
| 1 | Cash Flow Statement | Income/expense by category with monthly breakdown |
| 2 | Income vs Expense | Summary with savings rate and budget breakdown |
| 3 | Transaction Register | Chronological list with running balance |
| 4 | Net Worth | Assets grouped by account type |
| 5 | Account Statements | Per-account transaction statement |
| 6 | Tax Summary | Cash-basis income and deductible expenses |
| 7 | Expense Trend | Category × month expense matrix |
| 8 | Tagged Report | Transactions filtered by tag (--tags) |
| 9 | Budget vs Actual | Planned vs real spend with pace status |
| 10 | Bills & Subscriptions | Recurring payments with status |
| 11 | Savings Goals | Piggy bank progress |
| 12 | Liabilities | Debt summary with period movement |
| 13 | KPI Scorecard | Burn rate, cash runway, savings rate, HHI |
| 14 | Year-over-Year | Income and expense comparison vs prior year (--year mode only) |
| 15 | Cumulative Cash Flow | Monthly cumulative series |
| 16 | Income by Client | Income breakdown per client (revenue source) |
Strategic (non-legacy mode)
| # | Report | Description |
|---|---|---|
| 18 | Budget Performance Forecast | Month-end projection from current velocity |
| 19 | Category Ledger | Transactions grouped by category |
| 20 | Payee Ledger | Transactions grouped by payee |
| 21 | Linkage & Reimbursement Report | Linked pairs with link type and linked-amount % |
| 22 | All Tags Ledger | Transactions grouped by tag (--all-tags) |
| 23 | Historical Growth | Multi-year income/expense comparison (--years, --year mode only) |
| 24 | Liquidity Forecast | 6-month projected balance (--year mode only) |
| 25 | General Journal | Chronological double-entry register with protocol numbers and daily totals (Libro Giornale) |
| 26 | Summary | Firefly instance info (version, API, OS, PHP, user), global counts and period statistics |
Report 17 — Transaction Audit Log (
audit_log_<period>.pdf) is now generated only when--legacy-reportis active. The Summary report takes its slot in standard mode.
Demo (no Firefly III required)
python -m firefly_reports.demo --out ./output --year 2025 --lang en
Config file
firefly-reports init # interactive wizard — creates firefly-reports.toml
Documentation
Full documentation is on the GitHub Wiki:
- Installation & Quick Start
- Configuration — all CLI flags, TOML keys, env vars
- Reports Reference — all 26 reports
- Troubleshooting
- Architecture
Development
pip install -e ".[dev]"
pre-commit install
pytest tests/ -v
See CONTRIBUTING.md and the Developer Guide on the wiki.
License
GPL v3 — see LICENSE.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file firefly_iii_reports-1.0.2.tar.gz.
File metadata
- Download URL: firefly_iii_reports-1.0.2.tar.gz
- Upload date:
- Size: 118.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f15bb282cc99f67865c200d88783626b530b6725db019c6cb88882e053c799a4
|
|
| MD5 |
afe4d5296918090b8e326d09ef290bcb
|
|
| BLAKE2b-256 |
fe2ef4efbebd0836514a5b2e916118cfb044c82c9b4306323f4e27aad1b10495
|
Provenance
The following attestation bundles were made for firefly_iii_reports-1.0.2.tar.gz:
Publisher:
release.yml on fran33git/firefly-reports
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
firefly_iii_reports-1.0.2.tar.gz -
Subject digest:
f15bb282cc99f67865c200d88783626b530b6725db019c6cb88882e053c799a4 - Sigstore transparency entry: 2420362698
- Sigstore integration time:
-
Permalink:
fran33git/firefly-reports@4c3982c5856e57e3fe7844a8af53aada79ef5581 -
Branch / Tag:
refs/tags/v1.0.2 - Owner: https://github.com/fran33git
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@4c3982c5856e57e3fe7844a8af53aada79ef5581 -
Trigger Event:
push
-
Statement type:
File details
Details for the file firefly_iii_reports-1.0.2-py3-none-any.whl.
File metadata
- Download URL: firefly_iii_reports-1.0.2-py3-none-any.whl
- Upload date:
- Size: 100.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ded9089505ca70fa6335addf5588fae9b3b42c1281966dd0bfab3bd830a0dcb7
|
|
| MD5 |
78cd3fce2262be940d387a8ecb2c8ff1
|
|
| BLAKE2b-256 |
c6ee036f308883eeb29500c4a601c098fa16b4c7f227b1aed3e899576a19006d
|
Provenance
The following attestation bundles were made for firefly_iii_reports-1.0.2-py3-none-any.whl:
Publisher:
release.yml on fran33git/firefly-reports
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
firefly_iii_reports-1.0.2-py3-none-any.whl -
Subject digest:
ded9089505ca70fa6335addf5588fae9b3b42c1281966dd0bfab3bd830a0dcb7 - Sigstore transparency entry: 2420362764
- Sigstore integration time:
-
Permalink:
fran33git/firefly-reports@4c3982c5856e57e3fe7844a8af53aada79ef5581 -
Branch / Tag:
refs/tags/v1.0.2 - Owner: https://github.com/fran33git
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@4c3982c5856e57e3fe7844a8af53aada79ef5581 -
Trigger Event:
push
-
Statement type:
