Metadata-Version: 2.4
Name: spendctl
Version: 0.1.0
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
- 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

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

## 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:

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

```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).
