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)

Strategic (non-legacy mode)

Report 17 — Transaction Audit Log (audit_log_<period>.pdf) is now generated only when --legacy-report is 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.