Personal Bookkeeper

A command-line finance toolkit for individuals and freelancers. Personal Bookkeeper provides 12 dedicated commands for recording transactions, categorizing expenses, checking balances, tracking trends, forecasting budgets, generating reports, and managing tax notes — all backed by simple timestamped log files.

Commands

Data Storage

All data is stored as plain-text log files in ~/.local/share/personal-bookkeeper/:

• Each command writes to its own log file (e.g. record.log, categorize.log, tax-note.log)
• Every action is also recorded in history.log with a timestamp
• Entries use the format YYYY-MM-DD HH:MM|\x3Cinput> (pipe-delimited)
• Export produces files at ~/.local/share/personal-bookkeeper/export.{json,csv,txt}
• No database required — all data is grep-friendly and human-readable

Requirements

• Bash 4+ (uses set -euo pipefail)
• Standard Unix utilities: date, wc, du, head, tail, grep, cat, cut
• No external dependencies — pure bash, no Python, no API keys
• Works on Linux and macOS

When to Use

1. Daily expense tracking — Use record every time you make a purchase, then categorize to tag it (food, transport, entertainment) for end-of-month analysis.
2. Monthly budget reviews — Run budget-check to note whether you're over or under budget, summary to log category totals, and compare to see this month vs. last.
3. Tax season preparation — Use tax-note throughout the year to flag deductible expenses, then export csv to hand your accountant a clean spreadsheet.
4. Financial forecasting — Log forecast entries with projected income and expenses for upcoming months, then trend to track whether actuals match your projections.
5. Freelancer income management — record each invoice payment, balance to snapshot your account after deposits, and alert to flag overdue invoices or low cash reserves.

Examples

# Record a grocery expense
personal-bookkeeper record "Groceries at Costco -¥358.50"

# Categorize a transaction
personal-bookkeeper categorize "Costco receipt -> food/groceries"

# Check if you're on budget this month
personal-bookkeeper budget-check "March budget: spent ¥4200 of ¥5000 limit"

# Add a tax-deductible note
personal-bookkeeper tax-note "Home office internet bill ¥199/mo — deductible"

# Export everything to CSV for spreadsheet review
personal-bookkeeper export csv

Powered by BytesAgain | bytesagain.com | [email protected]