Personal Finance
Scope & Safety
- Operate on exported bank or credit-card CSVs in a read-only manner by default; no automatic uploads, API calls, or write-backs occur unless an explicit
--outputpath is provided. - Mask account numbers in all CLI outputs by replacing digits except the final four to keep PII safe for every command.
- Work offline; all logic lives inside
personal-finance.sh,config/category-rules.json, and the included sample CSV.
Primary Operations
All commands live in personal-finance.sh at the skill root. Invoke with:
./personal-finance.sh <command> [--csv <path>] [--config <path>] [--output <path>] [--period <period>]
1. validate
Checks that the CSV contains the required fields (date, description, amount, account_number) and that every amount is numeric. Use this before processing new exports to avoid schema drift.
./personal-finance.sh validate --csv sample-data/sample-transactions.csv
2. summarize
Aggregates income (positive amount) and expenses (negative amount) by period. Supports month, quarter, or year (default month). Outputs totals and net flows.
./personal-finance.sh summarize --period month --csv sample-data/sample-transactions.csv
3. categorize
Uses the local rules file (config/category-rules.json) to map descriptions to categories through keyword matching. Prints each transaction with masked accounts and assigned categories. Pass --output to emit a new CSV; otherwise, it stays read-only.
./personal-finance.sh categorize --csv sample-data/sample-transactions.csv --output /tmp/categorized.csv
4. report
Builds insight summaries: top merchants and categories by spend, plus transaction counts. It reuses the same rules file so it can work offline and stay consistent with categorize.
./personal-finance.sh report --csv sample-data/sample-transactions.csv
Configuration & Samples
config/category-rules.json: keyword-to-category rules thatcategorizeandreportshare.sample-data/sample-transactions.csv: minimal CSV (date, description, merchant, category, amount, account_number) for smoke tests and onboarding.
Keep both files in the skill folder. Adjust the JSON rules for your own merchant vocabulary; the script reloads them each run and never calls external services.