spendctl 0.1.0

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
• Interactive setup wizard (spendctl init)
• 13 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

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 config	View, edit, or reset configuration

AI Integration

Every command supports --json for structured output:

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

This makes spendctl easy to integrate with any AI assistant. A local model can read your finances, add transactions, and provide insights — all through the CLI. Your data never leaves your machine.

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.