Why Another Budget App?
There's no shortage of budgeting software. You've got YNAB, Actual Budget, spreadsheets, and a dozen mobile apps. They all do the same thing — track income and expenses — but they come with friction: opening a browser, logging in, clicking through forms, waiting for pages to load.
...I also hate GUIs (graphical user interfaces — the programs with drag and drop, buttons, images, etc.). Not to mention, being colourblind, you can't see half of what you're looking at.
I wanted something faster. Something that lives in the terminal, runs on any OS, and fits into the workflow I already have. I spend most of my day in a terminal anyway, so adding a transaction should be as quick as typing gbudget add -50 "groceries" -c Food.
The Concept
gbudget is a personal CLI budget application. It stores everything locally in SQLite — no cloud sync, no accounts, no API keys. You clone the repo, run gbudget init, and start adding transactions.
The amazing feature for me is the Obsidian vault integration. I keep all my notes in Obsidian, so having monthly markdown statements auto-generate inside my vault means my financial records sit alongside everything else. No separate app to check, no export/import dance.
The only problem I have now (not related to this app) is hosting such sensitive information on GitHub. I'll talk about my proposed solution using Gitea and my Raspberry Pi, with monthly encrypted uploads to Google Drive. Anyway...
Key Design Decisions
Pending vs Cleared
Most transactions hit your bank immediately. A coffee, a grocery run, a subscription payment — they're cleared within seconds. For those, you just add them normally.
But some charges take days: a credit card payment that's processing, a future-dated bill, a cheque deposit. Those go in as --pending and sit in a separate list. Once a month I reconcile against my bank statement and run gbudget clear 1 2 3 to mark them as confirmed. It mirrors the real banking workflow instead of forcing everything into "it's either spent or it's not."
Recurring Templates
Rent, Netflix, salary — predictable money in and out. I define them once with gbudget recurring add and they auto-generate as pending transactions at the start of each month. The CLI prompts me on the first run of the month, I confirm, and they appear. No manual re-entry.
Auto-Export to Obsidian
When vault statements are enabled, the markdown file at vault/files/money/YYYY-MM.md updates automatically on every add, edit, delete, or clear. Cleared transactions go in the main table, pending ones are listed separately. I don't need to remember to run export — it's always current.
Config Survives Reset
I wanted gbudget reset to be safe to run. It wipes all transactions and recurring templates but preserves your config — vault path, preferences, everything. If you have statement files in your vault, it asks before deleting those too.
Building It
The app is Python with SQLite and argparse for the CLI. The data model is straightforward: a transactions table (amount, description, category, date, status), a recurring_templates table, and a simple JSON config file.
The hardest part was getting the usability right. Early versions treated everything as pending, to be verified then cleared — which matches reality but not usability. I'm still working on recurring payments and how to display debts. I want these statements to not be bank-specific, and to represent my financial state entirely — debts unfortunately persist beyond monthly statements and I want to show EVERY transaction across banks.
Another tricky bit: recurring generation at month boundaries. If you define a recurring template mid-month, should it generate for the current month or the next? I landed on: templates generate at the start of each month when you first run any command. Mid-month adds don't trigger — you wait until the next month's prompt.
Not to mention, I'm not restricted to statement cycles banks and other systems have. I can make it an actual clean month representation. Bank fees for being overdrawn can just be added as a transaction. this is an aggregation tool for all income, outgoings in one statement/local database
What I want to add
- Add Streamlit — No idea how, but it would be nice to output a dashboard to a browser showing a snapshot of how one's finances are coming along. Whether spending habits are going up or down, debts being repaid or not. As much as I hate GUIs, it's nice to have a pretty graph once in a while.
- Usability improvements — I'm constantly thinking about how to display debts. It's such a good practice to account for interest rates on the monthly statements, even if with the respective debt(s) it just says the annual APR, for example. I'll iterate on that. Maths has never been my strongest skill, so I suspect this might lead to inaccuracies in the statement. Not to mention typical payment fees. All these edge cases need to be considered alongside how I use argparse for this.
The Code
The full source is on GitHub. The project page has a walkthrough of the commands and workflow.