Metadata-Version: 2.4
Name: spendctl
Version: 0.2.2
Summary: Personal finance CLI built for AI workflows
Project-URL: Homepage, https://github.com/Jscoats/spendctl
Project-URL: Repository, https://github.com/Jscoats/spendctl
Project-URL: Issues, https://github.com/Jscoats/spendctl/issues
Project-URL: Changelog, https://github.com/Jscoats/spendctl/blob/main/CHANGELOG.md
Author: Jscoats
License-Expression: MIT
License-File: LICENSE
Keywords: budget,cli,finance,personal finance,sqlite,tracker
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Provides-Extra: dashboard
Requires-Dist: pandas>=2.0; extra == 'dashboard'
Requires-Dist: plotly>=5.20; extra == 'dashboard'
Requires-Dist: streamlit>=1.40; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# spendctl

[![CI](https://github.com/Jscoats/spendctl/actions/workflows/ci.yml/badge.svg)](https://github.com/Jscoats/spendctl/actions/workflows/ci.yml)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

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

```bash
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](https://ollama.com) installed (locally or on a homelab), spendctl can use it to analyze your finances:

```bash
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:

```bash
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:

```bash
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:

```bash
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

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

## License

MIT — see [LICENSE](LICENSE).
