FinTrack

Personal Finance Tracker CLI - Budget planning and expense analysis tool.

Features

Budget Planning: Define income, deductions, fixed expenses, and savings goals
Transaction Import: Import transactions from CSV with idempotent processing
Interactive Dashboard: 5-tab HTML dashboard with Plotly charts and range sliders
Dark/Light Theme: Toggle dashboard theme in workspace configuration
All-Periods View: Single dashboard with period switcher dropdown
Savings Coverage: Track if available funds can cover savings gaps
Expense Analysis: Compare spending against budget with variance analysis
Flexible Periods: Support for day, week, month, quarter, year, or custom intervals

Installation

pip install fintrack-cli

Quick Start

# Create workspace
fintrack init my_finances
cd my_finances

# Create budget plan in plans/2024-12.yaml
# Import transactions from transactions/*.csv
fintrack import

# View status and generate dashboard
fintrack status
fintrack report

See Quick Start Guide for detailed steps.

Key Concepts

Gross Income
  - Deductions (taxes, social security)
= Net Income
  - Fixed Expenses (rent, utilities, subscriptions)
  - Savings Target
= Disposable Income (money you can actually spend)

Transaction Flags:

is_deduction: Pre-income deductions (taxes)
is_fixed: Fixed/recurring expenses (rent)
is_savings: Savings transfers

Commands

Command	Description
`fintrack init <name>`	Create new workspace
`fintrack validate`	Validate configuration
`fintrack import [path]`	Import CSV transactions
`fintrack budget`	Show budget projection
`fintrack status`	Quick spending overview
`fintrack analyze`	Full analysis with history
`fintrack report`	Generate HTML dashboard
`fintrack list <type>`	List transactions/plans/categories

Dashboard

fintrack report generates an interactive HTML dashboard with 5 tabs:

Overview - KPIs, Cash Reconciliation, Timeline charts
Income & Expenses - Sankey diagram, Category Treemap
Savings - Coverage Indicator, Savings vs Target
Budget - Budget vs Actual progress bars with variance display
Transactions - Filterable table with totals and CSV export

Dashboard Options

# Generate dashboard for current period
fintrack report

# Generate dashboard for specific period
fintrack report --period 2024-11

# Generate all-periods dashboard with period switcher
fintrack report --all

The --all flag creates a single HTML file with a dropdown to switch between all periods.

Dark Theme

Add theme: "dark" to your workspace.yaml:

name: my_finances
base_currency: EUR
interval: month
theme: dark  # Options: light (default), dark

Then regenerate the dashboard: fintrack report

See Dashboard Guide for details.

Documentation

CSV Format

date,amount,category,description,is_savings,is_deduction,is_fixed
2024-12-01,5000.00,salary,Monthly salary,,,
2024-12-01,-1000.00,tax,Income tax,,true,
2024-12-01,-800.00,housing,Rent,,,true
2024-12-10,-500.00,savings,Savings transfer,true,,
2024-12-15,-45.00,food,Groceries,,,

Notes:

All amounts in workspace base_currency
Positive = income, Negative = expense
Boolean flags: true/false or 1/0

Budget Plan Example

id: "december_2024"
valid_from: "2024-12-01"

gross_income: 5000.00

deductions:
  - name: "income_tax"
    amount: 1000.00

fixed_expenses:
  - name: "rent"
    amount: 800.00
    category: "housing"

savings_rate: 0.20
savings_base: "net_income"

category_budgets:
  - category: "food"
    amount: 400.00

Development

git clone https://github.com/alexeiveselov92/fintrack.git
cd fintrack
pip install -e ".[dev]"
pytest

License

MIT License - see LICENSE file.

Author

Alexei Veselov (@alexeiveselov92)

Metadata

Release files for fintrack-cli 0.3.23

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fintrack-cli 0.3.23
File	Size	Uploaded
fintrack_cli-0.3.23.tar.gz	150.5 kB	Dec 23, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for fintrack-cli 0.3.23
File	Interpreter	ABI	Platform	Reset
fintrack_cli-0.3.23-py3-none-any.whl 85.5 kB Dec 23, 2025	Python 3	none	any	Details

Total release size: 236.1 kB

Release files / fintrack_cli-0.3.23.tar.gz

Download URL	fintrack_cli-0.3.23.tar.gz
Size	150.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`9e02a4b31693737c7fd68435cf94e3db5596b06b739c36e0b52a15160017bdd2`
BLAKE2b-256 checksum How to use checksums	`5bf3727d82d64acdfc140e81a5dd88f12600732e46f17606968cf1d883cdb737`
Upload date	Dec 23, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.10.12`

Release files / fintrack_cli-0.3.23-py3-none-any.whl

Download URL	fintrack_cli-0.3.23-py3-none-any.whl
Size	85.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`1d16d0330bd23540a69f7ee0bcf23c3f439b53953af3a40e4dfec5cf97386a54`
BLAKE2b-256 checksum How to use checksums	`bdcc59930389a0a522564d1ed254fd03b741aa54fd025c0416e10d07f27bec1a`
Upload date	Dec 23, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.10.12`