expense-cli

A fast, privacy-first terminal expense tracker that imports your bank statements and helps you understand your spending.

The Problem

Most budgeting apps require you to sync your bank account (security risk) or manually enter every transaction. Bank statements come as CSVs with cryptic merchant names and no categories.

Features

• Import bank CSVs — Supports common formats from major banks
• Auto-categorize — Uses keyword matching + learned patterns to categorize transactions
• Budget tracking — Set monthly budgets per category, get warnings when close to limits
• Spending trends — See month-over-month changes, top merchants, category breakdowns
• Privacy-first — All data stays local in a SQLite database. No cloud, no sync
• Fast — Built in Python with Rich for beautiful terminal output

Installation

pip install -e .

Or install from PyPI:

pip install expense-cli

Quick Start

# Import a bank statement
expense import statement.csv

# View this month's spending
expense summary

# See spending by category
expense categories

# Set a budget
expense budget set food 500

# Check budget status
expense budget status

# Search transactions
expense search "uber"

# Show trends over time
expense trends --months 6

CSV Format

expense-cli auto-detects common CSV formats. If your bank isn't supported, create a simple mapping:

expense config add-bank "MyBank" --date-col 0 --desc-col 1 --amount-col 3 --date-format "%m/%d/%Y"

Category Rules

Customize auto-categorization:

# Add a rule: transactions containing "spotify" → entertainment
expense rule add "spotify" entertainment

# List rules
expense rules

Data Storage

All data is stored in ~/.expense-cli/data.db (SQLite). Export anytime:

expense export --format csv > my_expenses.csv
expense export --format json > my_expenses.json

License

MIT