v2.0.0 · Python CLI · MIT License

Your finances.
Owned by you.
In your terminal.

A production-grade CLI for tracking income, expenses, and savings — powered by SQLAlchemy, Click, and Rich. No subscriptions. No cloud. Just your data.

Get Started → View Source
Live Demo
finance-tracker — zsh
$ finance-tracker add -t income -a 3500 -c "Monthly Salary" ✓ [INCOME] $3,500.00 · Monthly Salary $ finance-tracker add -t expense -a 240 -c "Groceries" -d "Weekly shop" ✓ [EXPENSE] $240.00 · Groceries · Weekly shop $ finance-tracker add -t savings -a 500 -c "Emergency Fund" ✓ [SAVINGS] $500.00 · Emergency Fund $ finance-tracker report --period month ╔══════════════════════════════════════════════╗ ║ 📊 Financial Summary · Month ║ ╠══════════════════════════════════════════════╣ ║ Total Income $3,500.00 ║ ║ Total Expenses $240.00 ║ ║ Total Savings $500.00 ║ ║ Net Balance $3,260.00 ║ ║ Savings Rate 14.3% ║ ╚══════════════════════════════════════════════╝ $
INCOME ↑ $3,500 EXPENSES ↓ $240 SAVINGS ⊛ $500 NET BALANCE $3,260 SAVINGS RATE 14.3% SQLite · SQLAlchemy · Click · Rich INCOME ↑ $3,500 EXPENSES ↓ $240 SAVINGS ⊛ $500 NET BALANCE $3,260 SAVINGS RATE 14.3% SQLite · SQLAlchemy · Click · Rich
01 — Features

Everything you need.
Nothing you don't.

Built on a clean, modular architecture — easy to extend, test, and trust.

01
Rich Terminal UI

Colour-coded tables, summaries, and category breakdowns powered by the Rich library. Your data is beautiful by default.

02
SQLAlchemy ORM

Rock-solid SQLite storage via SQLAlchemy 2.0. Full ACID transactions, safe session management, and zero data loss.

03
Pydantic Validation

Every transaction is validated by a Pydantic v2 schema before touching the database. Bad data never gets in.

04
Visual Reports

Generate a four-panel PNG report with summary bars, category donut, top spenders, and key metrics. One command.

05
Budget Alerts

Set a spending limit for any category and instantly see how you're tracking — with a progress bar and over-budget warnings.

06
CSV Export

Export your full transaction history to CSV in one command. Compatible with Excel, Google Sheets, and any analysis tool.

02 — Commands

8 commands.
Complete control.

Everything accessible from the terminal, with clear help text and sensible defaults.

finance-tracker init Core
$ finance-tracker init
Initialise the SQLite database. Safe to run multiple times.
finance-tracker add Core
$ finance-tracker add --type income|expense|savings --amount 1500.00 --category "Salary" --description "Optional note"
Record a new transaction with full validation.
finance-tracker list Core
$ finance-tracker list --type expense --category "food" --limit 20
List all transactions with optional type/category filters.
finance-tracker report Core
$ finance-tracker report --period today|week|month|year|all
Print a Rich summary table for any time window.
finance-tracker breakdown New
$ finance-tracker breakdown --type expense
Show spending by category with inline bar chart.
finance-tracker search New
$ finance-tracker search amazon
Full-text search across category and description fields.
finance-tracker budget New
$ finance-tracker budget Groceries 400 --period month
Check a category budget with progress bar + over-budget alert.
finance-tracker export New
$ finance-tracker export --output my_data.csv
Export all transactions to a CSV file.
03 — Installation

Running in under 60 seconds.

Python 3.9+ required. No system dependencies beyond pip.

1
Clone the repository
git clone https://github.com/Ahmad-Akram7/FINANCE-TRACKER.git cd FINANCE-TRACKER
2
Create a virtual environment
# macOS / Linux python3 -m venv venv source venv/bin/activate # Windows py -m venv venv venv\Scripts\activate
3
Install dependencies
pip install -r requirements.txt pip install -e . # Optional: matplotlib for visual reports pip install matplotlib
4
Initialise and run
finance-tracker init finance-tracker --help # Add your first transaction finance-tracker add -t income -a 3500 -c "Salary"
04 — Architecture

Built to last.
Designed to extend.

Clean separation of concerns — swap the CLI for a web API without touching the business logic.

🗃️
Layer 1
models/

SQLAlchemy ORM models and Pydantic v2 schemas. All data shapes live here.

🔌
Layer 2
database/

Engine setup, session factory, and context manager. One place for all DB config.

⚙️
Layer 3
core/

Pure business logic — CRUD, summaries, search, breakdown. Zero UI coupling.

💻
Layer 4
interfaces/

Click CLI and Rich display helpers. Swap for FastAPI or Django with no core changes.