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
| Command |
Description |
personal-bookkeeper record <input> |
Record a financial transaction (income, expense, transfer). Without args, shows recent record entries. |
personal-bookkeeper categorize <input> |
Categorize a transaction (food, rent, transport, entertainment). Without args, shows recent entries. |
personal-bookkeeper balance <input> |
Log a balance snapshot (account balance, net worth checkpoint). Without args, shows recent balance entries. |
personal-bookkeeper trend <input> |
Record a spending or income trend observation. Without args, shows recent trend entries. |
personal-bookkeeper forecast <input> |
Log a budget forecast or projection. Without args, shows recent forecast entries. |
personal-bookkeeper export-report <input> |
Save a report entry (monthly summary, quarterly review). Without args, shows recent export-report entries. |
personal-bookkeeper budget-check <input> |
Record a budget check (over/under budget notes). Without args, shows recent budget-check entries. |
personal-bookkeeper summary <input> |
Log a financial summary (weekly recap, category totals). Without args, shows recent summary entries. |
personal-bookkeeper alert <input> |
Record a financial alert (overspending, low balance, due date). Without args, shows recent alert entries. |
personal-bookkeeper history <input> |
Log a history note or view recent history entries. |
personal-bookkeeper compare <input> |
Record period-over-period comparisons (this month vs last). Without args, shows recent compare entries. |
personal-bookkeeper tax-note <input> |
Save tax-related notes (deductible expenses, filing reminders). Without args, shows recent tax-note entries. |
personal-bookkeeper stats |
Show summary statistics across all categories — entry counts per log file, total entries, and data size. |
personal-bookkeeper export <fmt> |
Export all data to a file. Supported formats: json, csv, txt. |
personal-bookkeeper search <term> |
Search across all log files for a keyword (case-insensitive). |
personal-bookkeeper recent |
Show the 20 most recent entries from the activity history log. |
personal-bookkeeper status |
Health check — version, data directory, total entries, disk usage, last activity. |
personal-bookkeeper help |
Display the full help message with all available commands. |
personal-bookkeeper version |
Print the current version (v2.0.0). |
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|<input> (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
- Daily expense tracking — Use
record every time you make a purchase, then categorize to tag it (food, transport, entertainment) for end-of-month analysis.
- 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.
- Tax season preparation — Use
tax-note throughout the year to flag deductible expenses, then export csv to hand your accountant a clean spreadsheet.
- Financial forecasting — Log
forecast entries with projected income and expenses for upcoming months, then trend to track whether actuals match your projections.
- 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 | hello@bytesagain.com
1---2name: personal-bookkeeper3description: Record double-entry bookkeeping for personal finances. Use when logging transactions, categorizing accounts, balancing ledgers, trending expenses.4---5# Personal Bookkeeper
6
7A 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.
8
9## Commands
10
11| Command | Description |
12|---------|-------------|
13| `personal-bookkeeper record <input>` | Record a financial transaction (income, expense, transfer). Without args, shows recent record entries. |
14| `personal-bookkeeper categorize <input>` | Categorize a transaction (food, rent, transport, entertainment). Without args, shows recent entries. |
15| `personal-bookkeeper balance <input>` | Log a balance snapshot (account balance, net worth checkpoint). Without args, shows recent balance entries. |
16| `personal-bookkeeper trend <input>` | Record a spending or income trend observation. Without args, shows recent trend entries. |
17| `personal-bookkeeper forecast <input>` | Log a budget forecast or projection. Without args, shows recent forecast entries. |
18| `personal-bookkeeper export-report <input>` | Save a report entry (monthly summary, quarterly review). Without args, shows recent export-report entries. |
19| `personal-bookkeeper budget-check <input>` | Record a budget check (over/under budget notes). Without args, shows recent budget-check entries. |
20| `personal-bookkeeper summary <input>` | Log a financial summary (weekly recap, category totals). Without args, shows recent summary entries. |
21| `personal-bookkeeper alert <input>` | Record a financial alert (overspending, low balance, due date). Without args, shows recent alert entries. |
22| `personal-bookkeeper history <input>` | Log a history note or view recent history entries. |
23| `personal-bookkeeper compare <input>` | Record period-over-period comparisons (this month vs last). Without args, shows recent compare entries. |
24| `personal-bookkeeper tax-note <input>` | Save tax-related notes (deductible expenses, filing reminders). Without args, shows recent tax-note entries. |
25| `personal-bookkeeper stats` | Show summary statistics across all categories — entry counts per log file, total entries, and data size. |
26| `personal-bookkeeper export <fmt>` | Export all data to a file. Supported formats: `json`, `csv`, `txt`. |
27| `personal-bookkeeper search <term>` | Search across all log files for a keyword (case-insensitive). |
28| `personal-bookkeeper recent` | Show the 20 most recent entries from the activity history log. |
29| `personal-bookkeeper status` | Health check — version, data directory, total entries, disk usage, last activity. |
30| `personal-bookkeeper help` | Display the full help message with all available commands. |
31| `personal-bookkeeper version` | Print the current version (v2.0.0). |
32
33## Data Storage
34
35All data is stored as plain-text log files in `~/.local/share/personal-bookkeeper/`:
36
37- Each command writes to its own log file (e.g. `record.log`, `categorize.log`, `tax-note.log`)
38- Every action is also recorded in `history.log` with a timestamp
39- Entries use the format `YYYY-MM-DD HH:MM|<input>` (pipe-delimited)
40- Export produces files at `~/.local/share/personal-bookkeeper/export.{json,csv,txt}`
41- No database required — all data is grep-friendly and human-readable
42
43## Requirements
44
45- **Bash 4+** (uses `set -euo pipefail`)
46- **Standard Unix utilities**: `date`, `wc`, `du`, `head`, `tail`, `grep`, `cat`, `cut`
47- **No external dependencies** — pure bash, no Python, no API keys
48- Works on **Linux** and **macOS**
49
50## When to Use
51
521. **Daily expense tracking** — Use `record` every time you make a purchase, then `categorize` to tag it (food, transport, entertainment) for end-of-month analysis.
532. **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.
543. **Tax season preparation** — Use `tax-note` throughout the year to flag deductible expenses, then `export csv` to hand your accountant a clean spreadsheet.
554. **Financial forecasting** — Log `forecast` entries with projected income and expenses for upcoming months, then `trend` to track whether actuals match your projections.
565. **Freelancer income management** — `record` each invoice payment, `balance` to snapshot your account after deposits, and `alert` to flag overdue invoices or low cash reserves.
57
58## Examples
59
60```bash
61# Record a grocery expense
62personal-bookkeeper record "Groceries at Costco -¥358.50"
63
64# Categorize a transaction
65personal-bookkeeper categorize "Costco receipt -> food/groceries"
66
67# Check if you're on budget this month
68personal-bookkeeper budget-check "March budget: spent ¥4200 of ¥5000 limit"
69
70# Add a tax-deductible note
71personal-bookkeeper tax-note "Home office internet bill ¥199/mo — deductible"
72
73# Export everything to CSV for spreadsheet review
74personal-bookkeeper export csv
75```
76
77---
78
79Powered by BytesAgain | bytesagain.com | hello@bytesagain.com
bytesagain