spendctl 0.2.2

Personal finance CLI built for AI workflows

spendctl

A personal finance CLI built for AI workflows.

What it does

Track spending, income, debt, and net worth from your terminal. Every command supports --json output, making it straightforward to integrate with any AI assistant — Claude, GPT, local models via Ollama or LM Studio, or custom scripts. Your financial data stays in a local SQLite file. No APIs, no cloud sync, no accounts to create. An optional Streamlit dashboard is available for visual analysis when you want it.

Features

• Zero runtime dependencies for the core CLI
• --json output on every command for AI and script integration
• Works with any AI — local models (Ollama, LM Studio), Claude, GPT, or custom scripts
• Built-in Ollama integration for local AI analysis (spendctl ask)
• Interactive setup wizard (spendctl init) — auto-configures Claude Code, Codex CLI, Gemini CLI, and Aider
• 14 CLI commands: transactions, balances, budgets, debt tracking, and more
• 7-page Streamlit dashboard (optional)
• SQLite backend — portable, inspectable, no server needed
• Config-driven — your accounts, categories, and budgets defined in one file

Quick Start

pip install spendctl
spendctl init                                                    # Interactive setup wizard
spendctl add 2024-01-15 "Grocery store" 87.42 --category Groceries
spendctl balance                                                 # See all account balances
spendctl balance --json | jq .                                   # AI-friendly output
spendctl ask "How's my budget looking?"                          # Ask your local AI

Commands

Command	Description
spendctl init	Interactive setup wizard
spendctl add	Add a transaction
spendctl list	List and filter transactions
spendctl balance	Show account balances
spendctl spending	Spending breakdown by category
spendctl debt	Debt paydown progress
spendctl budget	Budget vs actual comparison
spendctl summary	Full monthly summary
spendctl subscriptions	Manage recurring charges
spendctl backup	Create a database backup
spendctl export-csv	Export transactions to CSV
spendctl dashboard	Launch the Streamlit dashboard
spendctl ask	Ask your local AI about your finances
spendctl config	View, edit, or reset configuration

How spendctl Compares

	spendctl	ledger / hledger	beancount + fava	budgetwarrior
Interface	CLI + Streamlit dashboard	CLI only	CLI + web UI	CLI only
Storage	SQLite	Plain text	Plain text	Custom binary
AI-friendly output	--json on every command	Limited	No	No
Setup	Interactive wizard	Edit text files	Edit text files	Manual
Dashboard	7-page Streamlit (optional)	None	Fava web UI	None
Accounting model	Single-entry	Double-entry	Double-entry	Single-entry
Runtime deps	Zero (core CLI)	Haskell/C++	Python	C++
Learning curve	Low	High	High	Medium

AI Integration

Terminal AI Assistants

During setup, spendctl init can auto-configure your terminal AI assistant to know about spendctl. Supported:

• Claude Code — adds to ~/.claude/CLAUDE.md
• Codex CLI — adds to ~/.codex/AGENTS.md
• Gemini CLI — adds to ~/.gemini/GEMINI.md
• Aider — generates context file and updates .aider.conf.yml

Local AI Analysis

If you have Ollama installed (locally or on a homelab), spendctl can use it to analyze your finances:

spendctl ask "How's my spending this month?"
spendctl ask "Am I on track with my debt payoff?"
spendctl ask "What should I cut from my budget?"

The init wizard auto-detects Ollama and walks you through model selection. Your data stays local — nothing leaves your machine.

JSON Output

Every command supports --json for structured output:

spendctl balance --json
spendctl spending --month 2024-01 --json
spendctl summary --json

This makes it easy to pipe financial data to any AI model or script.

Dashboard

Install with the optional dashboard dependencies:

pip install "spendctl[dashboard]"
spendctl dashboard

The dashboard runs at http://localhost:8501 and includes 7 pages:

• Overview — sparklines, net worth gauge, budget vs actual at a glance
• Spending — category pie and bar charts with budget alerts
• Debt — progress bars, payoff projections, interest savings calculator
• Transactions — filterable transaction table
• Subscriptions — active and canceled recurring charges
• Loans — student loan payoff tracking
• Report — printable monthly budget summary

Configuration

Run spendctl init to create your config file at ~/.config/spendctl/config.json. The wizard walks you through setting up accounts, categories, income sources, and budget targets.

After setup, use the config subcommand to manage your configuration:

spendctl config show     # Print current config as JSON
spendctl config edit     # Edit a section interactively
spendctl config reset    # Delete config and re-run the wizard

Development

git clone https://github.com/Jscoats/spendctl.git
cd spendctl
pip install -e ".[dev]"
pytest
ruff check src/ tests/

License

MIT — see LICENSE.