BudgetLy
BudgetLy v2.0.0 — a personal finance toolkit for recording expenses, categorizing spending, checking balances, analyzing trends, forecasting budgets, and generating reports from the command line.
Why BudgetLy?
- Full-featured personal finance tracker with 12 specialized commands
- No external dependencies, accounts, or API keys needed — your data remains on disk
- All entries are timestamped and stored in plain-text log files
- Export to JSON, CSV, or TXT for analysis in spreadsheets or other tools
- Built-in search, statistics, and health-check utilities
- Works on any system with Bash
Commands
| Command |
Usage |
Description |
record |
budgetly record <input> |
Record a financial transaction or expense entry |
categorize |
budgetly categorize <input> |
Categorize a transaction (e.g., food, transport, rent) |
balance |
budgetly balance <input> |
Log or check account balance information |
trend |
budgetly trend <input> |
Log trend data for spending pattern analysis |
forecast |
budgetly forecast <input> |
Record a budget forecast or projection |
export-report |
budgetly export-report <input> |
Generate and log an export report entry |
budget-check |
budgetly budget-check <input> |
Check budget limits and log the result |
summary |
budgetly summary <input> |
Log a financial summary (daily, weekly, monthly) |
alert |
budgetly alert <input> |
Set or log a budget alert (overspend warnings, etc.) |
history |
budgetly history <input> |
Log or view financial history entries |
compare |
budgetly compare <input> |
Compare spending across periods or categories |
tax-note |
budgetly tax-note <input> |
Record tax-related notes and deductions |
stats |
budgetly stats |
Show summary statistics across all log files |
export |
budgetly export <fmt> |
Export all data (json, csv, or txt) |
search |
budgetly search <term> |
Search across all log files for a keyword |
recent |
budgetly recent |
Show the 20 most recent history entries |
status |
budgetly status |
Health check — version, entry count, disk usage |
help |
budgetly help |
Show the help message with all commands |
version |
budgetly version |
Print the current version |
All entry commands (record, categorize, balance, trend, forecast, export-report, budget-check, summary, alert, history, compare, tax-note) work the same way:
- With arguments: saves a timestamped entry to
<command>.log and logs to history.log
- Without arguments: displays the 20 most recent entries from that command's log
Data Storage
All data is stored in ~/.local/share/budgetly/:
record.log, categorize.log, balance.log, etc. — one log file per commandhistory.log — unified activity log across all commandsexport.json / export.csv / export.txt — generated export files
Each entry is stored as YYYY-MM-DD HH:MM|<value> (pipe-delimited timestamp and content).
Requirements
- Bash (with
set -euo pipefail)
- Standard Unix utilities:
date, wc, du, grep, head, tail, cat
- No external dependencies, no Python, no API keys
When to Use
- Daily expense logging — Use
budgetly record "Lunch at cafe ¥45" to maintain a running log of daily expenses and review them later with budgetly record (no args shows recent entries).
- Category-based spending analysis — Use
budgetly categorize "food: ¥2,300 this month" to organize expenses by category and then search with budgetly search "food" to analyze patterns.
- Monthly budget forecasting — Use
budgetly forecast "April budget: rent ¥3000, food ¥2500, transport ¥800" to plan ahead and compare actuals later with budgetly compare.
- Tax preparation — Use
budgetly tax-note "Home office deduction: ¥1,200/month, receipts in folder Q1-2026" to keep tax-related notes organized and export them with budgetly export csv.
- Spending alerts and limits — Use
budgetly alert "Entertainment budget exceeded: ¥1,500/¥1,000 limit" to log overspend warnings and review alerts with budgetly alert.
Examples
# Record daily expenses
budgetly record "Coffee ¥15, lunch ¥42, groceries ¥128"
budgetly record "Monthly rent ¥3,500"
# Categorize spending
budgetly categorize "transport: Uber ¥30, subway ¥8, gas ¥200"
budgetly categorize "subscriptions: Netflix ¥45, Spotify ¥15, iCloud ¥6"
# Check and log balance
budgetly balance "Checking account: ¥15,230 as of March 18"
# Analyze spending trends
budgetly trend "Food spending up 15% vs last month"
# Forecast next month
budgetly forecast "April projection: total ¥8,500 (down from ¥9,200 in March)"
# Set budget alerts
budgetly alert "Warning: dining out already at 80% of monthly limit"
# Log tax-related items
budgetly tax-note "Charitable donation ¥500 to Red Cross, receipt #RC-2026-0318"
# Compare periods
budgetly compare "Q1 vs Q4: food +12%, transport -8%, entertainment -20%"
# View summary statistics
budgetly stats
# Search for specific entries
budgetly search "groceries"
# Export everything to JSON
budgetly export json
# Check system status
budgetly status
# View recent activity
budgetly recent
Configuration
Data directory: ~/.local/share/budgetly/ (hardcoded, no environment variable override).
Output
All commands print results to stdout. Redirect output to a file if needed:
budgetly stats > my-finance-stats.txt
budgetly export csv
Note: This is an original, independent implementation by BytesAgain. Not affiliated with or derived from any third-party project.
Powered by BytesAgain | bytesagain.com | hello@bytesagain.com
1---2name: budgetly3description: Set category budgets, log expenses, and visualize spending limits. Use when tracking grocery costs, monitoring subscriptions, or forecasting spend.4---5
6# BudgetLy
7
8BudgetLy v2.0.0 — a personal finance toolkit for recording expenses, categorizing spending, checking balances, analyzing trends, forecasting budgets, and generating reports from the command line.
9
10## Why BudgetLy?
11
12- Full-featured personal finance tracker with 12 specialized commands
13- No external dependencies, accounts, or API keys needed — your data remains on disk
14- All entries are timestamped and stored in plain-text log files
15- Export to JSON, CSV, or TXT for analysis in spreadsheets or other tools
16- Built-in search, statistics, and health-check utilities
17- Works on any system with Bash
18
19## Commands
20
21| Command | Usage | Description |
22|---------|-------|-------------|
23| `record` | `budgetly record <input>` | Record a financial transaction or expense entry |
24| `categorize` | `budgetly categorize <input>` | Categorize a transaction (e.g., food, transport, rent) |
25| `balance` | `budgetly balance <input>` | Log or check account balance information |
26| `trend` | `budgetly trend <input>` | Log trend data for spending pattern analysis |
27| `forecast` | `budgetly forecast <input>` | Record a budget forecast or projection |
28| `export-report` | `budgetly export-report <input>` | Generate and log an export report entry |
29| `budget-check` | `budgetly budget-check <input>` | Check budget limits and log the result |
30| `summary` | `budgetly summary <input>` | Log a financial summary (daily, weekly, monthly) |
31| `alert` | `budgetly alert <input>` | Set or log a budget alert (overspend warnings, etc.) |
32| `history` | `budgetly history <input>` | Log or view financial history entries |
33| `compare` | `budgetly compare <input>` | Compare spending across periods or categories |
34| `tax-note` | `budgetly tax-note <input>` | Record tax-related notes and deductions |
35| `stats` | `budgetly stats` | Show summary statistics across all log files |
36| `export` | `budgetly export <fmt>` | Export all data (json, csv, or txt) |
37| `search` | `budgetly search <term>` | Search across all log files for a keyword |
38| `recent` | `budgetly recent` | Show the 20 most recent history entries |
39| `status` | `budgetly status` | Health check — version, entry count, disk usage |
40| `help` | `budgetly help` | Show the help message with all commands |
41| `version` | `budgetly version` | Print the current version |
42
43All entry commands (record, categorize, balance, trend, forecast, export-report, budget-check, summary, alert, history, compare, tax-note) work the same way:
44- **With arguments**: saves a timestamped entry to `<command>.log` and logs to `history.log`
45- **Without arguments**: displays the 20 most recent entries from that command's log
46
47## Data Storage
48
49All data is stored in `~/.local/share/budgetly/`:
50
51- `record.log`, `categorize.log`, `balance.log`, etc. — one log file per command
52- `history.log` — unified activity log across all commands
53- `export.json` / `export.csv` / `export.txt` — generated export files
54
55Each entry is stored as `YYYY-MM-DD HH:MM|<value>` (pipe-delimited timestamp and content).
56
57## Requirements
58
59- Bash (with `set -euo pipefail`)
60- Standard Unix utilities: `date`, `wc`, `du`, `grep`, `head`, `tail`, `cat`
61- No external dependencies, no Python, no API keys
62
63## When to Use
64
651. **Daily expense logging** — Use `budgetly record "Lunch at cafe ¥45"` to maintain a running log of daily expenses and review them later with `budgetly record` (no args shows recent entries).
662. **Category-based spending analysis** — Use `budgetly categorize "food: ¥2,300 this month"` to organize expenses by category and then search with `budgetly search "food"` to analyze patterns.
673. **Monthly budget forecasting** — Use `budgetly forecast "April budget: rent ¥3000, food ¥2500, transport ¥800"` to plan ahead and compare actuals later with `budgetly compare`.
684. **Tax preparation** — Use `budgetly tax-note "Home office deduction: ¥1,200/month, receipts in folder Q1-2026"` to keep tax-related notes organized and export them with `budgetly export csv`.
695. **Spending alerts and limits** — Use `budgetly alert "Entertainment budget exceeded: ¥1,500/¥1,000 limit"` to log overspend warnings and review alerts with `budgetly alert`.
70
71## Examples
72
73```bash
74# Record daily expenses
75budgetly record "Coffee ¥15, lunch ¥42, groceries ¥128"
76budgetly record "Monthly rent ¥3,500"
77
78# Categorize spending
79budgetly categorize "transport: Uber ¥30, subway ¥8, gas ¥200"
80budgetly categorize "subscriptions: Netflix ¥45, Spotify ¥15, iCloud ¥6"
81
82# Check and log balance
83budgetly balance "Checking account: ¥15,230 as of March 18"
84
85# Analyze spending trends
86budgetly trend "Food spending up 15% vs last month"
87
88# Forecast next month
89budgetly forecast "April projection: total ¥8,500 (down from ¥9,200 in March)"
90
91# Set budget alerts
92budgetly alert "Warning: dining out already at 80% of monthly limit"
93
94# Log tax-related items
95budgetly tax-note "Charitable donation ¥500 to Red Cross, receipt #RC-2026-0318"
96
97# Compare periods
98budgetly compare "Q1 vs Q4: food +12%, transport -8%, entertainment -20%"
99
100# View summary statistics
101budgetly stats
102
103# Search for specific entries
104budgetly search "groceries"
105
106# Export everything to JSON
107budgetly export json
108
109# Check system status
110budgetly status
111
112# View recent activity
113budgetly recent
114```
115
116## Configuration
117
118Data directory: `~/.local/share/budgetly/` (hardcoded, no environment variable override).
119
120## Output
121
122All commands print results to stdout. Redirect output to a file if needed:
123
124```bash
125budgetly stats > my-finance-stats.txt
126budgetly export csv
127```
128
129> **Note**: This is an original, independent implementation by BytesAgain. Not affiliated with or derived from any third-party project.
130
131---
132
133Powered by BytesAgain | bytesagain.com | hello@bytesagain.com
bytesagain