BudgetLy

BudgetLy v2.0.0 — 一款面向个人财务的命令行工具包，支持记录支出、分类消费、查询余额、分析趋势、预算预测以及生成报告。

为何选择 BudgetLy？

• 功能完备的个人财务追踪器，内置 12 个专用命令
• 无需外部依赖、账户或 API 密钥——所有数据完全本地存储
• 所有条目均带时间戳，并以纯文本日志文件形式保存
• 支持导出为 JSON、CSV 或 TXT 格式，便于在电子表格或其他工具中进一步分析
• 内置搜索、统计与健康检查等实用工具
• 可在任何安装 Bash 的系统上运行

命令列表

所有条目类命令（record、categorize、balance、trend、forecast、export-report、budget-check、summary、alert、history、compare、tax-note）行为一致：

• 带参数调用时：将带时间戳的条目写入 .log，同时追加至 history.log
• 不带参数调用时：显示该命令对应日志文件中最近的 20 条记录

数据存储

所有数据均存放在 ~/.local/share/budgetly/ 目录下：

• record.log、categorize.log、balance.log 等——每个命令对应一个独立日志文件
• history.log——统一记录所有命令的操作历史
• export.json / export.csv / export.txt——导出生成的文件

每条记录格式为 YYYY-MM-DD HH:MM|（时间戳与内容以竖线分隔）。

运行要求

• Bash（需启用 set -euo pipefail）
• 标准 Unix 工具： date、wc、du、grep、head、tail、cat
• 无外部依赖，不依赖 Python，无需 API 密钥

典型使用场景

1. 日常支出记录——使用 budgetly record "Lunch at cafe ¥45" 持续记录每日开销；后续可通过不带参数的 budgetly record 查看最近记录。
2. 按类别分析消费——使用 budgetly categorize "food: ¥2,300 this month" 对支出进行归类，再通过 budgetly search "food" 快速检索并分析模式。
3. 月度预算预测——使用 budgetly forecast "April budget: rent ¥3000, food ¥2500, transport ¥800" 提前规划预算，并在后续使用 budgetly compare 对比实际支出。
4. 税务申报准备——使用 budgetly tax-note "Home office deduction: ¥1,200/month, receipts in folder Q1-2026" 统一管理税务备注，再通过 budgetly export csv 导出供报税使用。
5. 消费提醒与限额管控——使用 budgetly alert "Entertainment budget exceeded: ¥1,500/¥1,000 limit" 记录超支警告，并通过 budgetly alert 集中查看所有提醒。

使用示例

# 记录每日支出
budgetly record "Coffee ¥15, lunch ¥42, groceries ¥128"
budgetly record "Monthly rent ¥3,500"

# 分类消费
budgetly categorize "transport: Uber ¥30, subway ¥8, gas ¥200"
budgetly categorize "subscriptions: Netflix ¥45, Spotify ¥15, iCloud ¥6"

# 查询并记录余额
budgetly balance "Checking account: ¥15,230 as of March 18"

# 分析消费趋势
budgetly trend "Food spending up 15% vs last month"

# 预测下月预算
budgetly forecast "April projection: total ¥8,500 (down from ¥9,200 in March)"

# 设置预算提醒
budgetly alert "Warning: dining out already at 80% of monthly limit"

# 记录税务相关事项
budgetly tax-note "Charitable donation ¥500 to Red Cross, receipt #RC-2026-0318"

# 对比不同周期
budgetly compare "Q1 vs Q4: food +12%, transport -8%, entertainment -20%"

# 查看汇总统计
budgetly stats

# 搜索特定条目
budgetly search "groceries"

# 导出全部数据为 JSON
budgetly export json

# 检查系统状态
budgetly status

# 查看最近活动
budgetly recent

配置说明

数据目录为：~/.local/share/budgetly/（硬编码路径，不支持通过环境变量覆盖）。

输出方式

所有命令结果均输出至 stdout。如需保存至文件，可使用重定向：

budgetly stats > my-finance-stats.txt
budgetly export csv

说明：本项目为 BytesAgain 独立开发的原创实现，未与任何第三方项目关联，亦非基于其他项目的衍生版本。

由 BytesAgain 提供支持 | bytesagain.com | hello@bytesagain.com