Overview
gbudget is a personal CLI budget application that lets you track income and expenses directly from the terminal. It optionally generates monthly markdown statements in your Obsidian vault, keeping your financial records alongside your notes.
Data Storage
All data is stored locally using SQLite. The database and config file locations vary by platform:
- Linux/Mac —
~/.local/share/gbudget/budget.db(data),~/.config/gbudget/config.json(config) - Windows —
%APPDATA%/gbudget/budget.db(data),%APPDATA%/gbudget/config.json(config)
Installation
Clone the repo and run gbudget directly, or install globally via pip install -e . for Linux/Mac. On Windows, add the cloned folder to your PATH and use gbudget.bat.
Commands
gbudget init— First-time setup. Creates config and database.gbudget add AMOUNT DESC [-c CAT] [-d DATE] [--pending]— Add a transaction. Negative amount = expense, positive = income.gbudget list [--month YYYY-MM] [-c CAT] [--status pending|cleared]— Show transactions in a table.gbudget summary [--month YYYY-MM] [--by-category]— Show total income, expenses, and net.gbudget edit ID [-a AMOUNT] [-d DESC] [-c CAT] [--type income|expense] [--status cleared]— Update specific fields of a transaction.gbudget delete ID— Permanently remove a transaction.gbudget clear ID [ID ...]— Move pending transactions to cleared.gbudget export [--month YYYY-MM]— Regenerate monthly markdown statement.gbudget config [--vault PATH]— View or update settings.gbudget recurring add/list/delete— Manage recurring bills and income templates.gbudget reset— Delete all transactions and recurring templates (config preserved).
Workflow
Start with gbudget init for one-time setup, then add transactions as you spend or earn. Use --pending for charges that haven't hit your bank yet. Define regular bills with gbudget recurring add — they auto-generate as pending at the start of each month. Once a month, reconcile by checking your bank statement and running gbudget clear on confirmed transactions.
If you enable vault statements with gbudget setup-statements --vault ~/notes, the markdown file in your Obsidian vault updates automatically whenever you add, edit, delete, or clear transactions. The file keeps cleared transactions in the main table and pending ones listed separately.