Metadata-Version: 2.4
Name: treeline-money
Version: 0.1.7
Summary: Personal finance in your terminal
Author: Zack Schrag
License: MIT
Project-URL: Homepage, https://github.com/zack-schrag/treeline-money
Project-URL: Repository, https://github.com/zack-schrag/treeline-money
Project-URL: Issues, https://github.com/zack-schrag/treeline-money/issues
Keywords: personal-finance,cli,duckdb,sql,finance,banking,transactions,simplefin,budget,money
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: duckdb>=1.4.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: prompt-toolkit>=3.0.52
Requires-Dist: pydantic>=2.11.9
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: readchar>=4.2.1
Requires-Dist: rich>=14.1.0
Requires-Dist: typer>=0.19.2
Dynamic: license-file

# Treeline

**Personal finance analysis in your terminal**

Treeline gives you complete control over your financial data. Built for power users who want direct access to their data.

> **⚠️ Early Stage Software**: Treeline is in active development. While it's stable for personal use, expect potential breaking changes in future releases. Always back up your data.

If you've ever:
- Spent hours building a custom spreadsheet that could rival Mint
- Been frustrated with the lack of customization from existing finance tools
- Wished you build your own automations tailored to *your* financial life
- Wanted *full* control over your data

You're in the right place 😃

## Features
- **SQL Queries** - Direct DuckDB access to your financial data
- **SimpleFIN Sync** - Automatic bank synchronization via SimpleFIN
- **CSV Import** - Import transactions from any bank CSV export, with automatic deduplication
- **Local Database** - All data stored locally in DuckDB
- **Scriptable** - JSON output, CSV export, and support for input / output piping
- **Auto-Tagging** - Python-based rules to build custom logic for automatically categorizing transactions

## Quick Start

### Try Demo Mode (No Setup)

The fastest way to explore Treeline:

```bash
pip install treeline-money

# Load demo data
export TREELINE_DEMO_MODE=true
treeline sync

# Explore with demo data
treeline status
treeline query "SELECT * FROM transactions LIMIT 10"

# When you're done with demoing:
unset TREELINE_DEMO_MODE
```

See [docs/demo_mode.md](./docs/demo_mode.md) for details.

### Real Setup

```bash
# 1. Install
pip install treeline-money

# 2. Connect to SimpleFIN
treeline setup simplefin

# 3. Sync your data
treeline sync

# 4. Start exploring
treeline status
treeline query "SELECT * FROM transactions ORDER BY transaction_date DESC LIMIT 10"
```

### Tagging transactions
```bash
# Start interactive tagging mode
treeline tag

# Or tag directly from CLI
treeline tag apply --ids abc123,def456 groceries,food

# Or pipe IDs from query to apply tags in bulk
# Note: Use intermediate variable to avoid database lock conflicts
TX_IDS=$(treeline query "SELECT transaction_id FROM transactions WHERE description ILIKE '%QFC%'" --json | jq -r '.rows[][]')
echo "$TX_IDS" | treeline tag apply groceries
```

### Auto-tagging rules on sync or import
```bash
treeline new tagger large_purchases
```
This will create a new file in `~/.treeline/taggers/large_purchases.py`. Fill out the Python logic, then test by doing a backfill with optional `--dry-run` flag:
```bash
treeline backfill tags --dry-run --verbose
```
This will show the tags that would be applied, but makes no edits to the database. Remove the the `--dry-run` once you're confident in the logic.

## Database Schema

Query these tables with standard SQL:

### `transactions`
Main view for querying transaction data (joins transaction + account details):
- `transaction_id` - UUID of transaction
- `account_id` - UUID of account
- `amount` - Transaction amount (negative = spending, positive = income)
- `description` - Transaction description
- `transaction_date` - Date of transaction
- `posted_date` - Date transaction posted
- `tags` - Array of tags (e.g., `['groceries', 'food']`)
- `account_name` - Name of account (joined)
- `account_type` - Type of account (joined)
- `currency` - Currency code (joined)
- `institution_name` - Bank/institution name (joined)

### `accounts`
Account information:
- `account_id` - UUID of account
- `name` - Account name
- `nickname` - Optional nickname
- `account_type` - Account type (checking, savings, credit, etc.)
- `currency` - Currency code (default: USD)
- `balance` - Current balance
- `external_ids` - JSON of external IDs from integrations
- `institution_name` - Bank/institution name
- `institution_url` - Institution URL
- `institution_domain` - Institution domain
- `created_at` - Created timestamp
- `updated_at` - Last updated timestamp

### `balance_snapshots`
Historical balance data (joins balance + account details):
- `snapshot_id` - UUID of snapshot
- `account_id` - UUID of account
- `balance` - Balance at snapshot time
- `snapshot_time` - When snapshot was taken
- `account_name` - Name of account (joined)
- `institution_name` - Bank/institution name (joined)
- `created_at` - Created timestamp
- `updated_at` - Last updated timestamp

**Example queries:**

```bash
# Spending by tag
treeline query "SELECT tags, SUM(amount) as total FROM transactions WHERE amount < 0 GROUP BY tags ORDER BY total"

# Monthly spending trends
treeline query "SELECT strftime('%Y-%m', transaction_date) as month, SUM(amount) as total FROM transactions WHERE amount < 0 GROUP BY month ORDER BY month DESC"

# Account balances over time
treeline query "SELECT account_name, snapshot_time, balance FROM balance_snapshots ORDER BY snapshot_time DESC"

# Top 10 biggest purchases
treeline query "SELECT transaction_date, description, amount, account_name FROM transactions WHERE amount < 0 ORDER BY amount LIMIT 10"

# Transactions without tags
treeline query "SELECT transaction_date, description, amount FROM transactions WHERE tags = [] ORDER BY transaction_date DESC LIMIT 20"

# Export all transactions to CSV
treeline query "SELECT * FROM transactions" --format csv > all_transactions.csv
```

## What can you do with Treeline?
Some ideas to get you started:
- Build an interactive dashboard with Marimo or Streamlit (or whatever your favorite tool is)
- Have Claude Code analyze your data with natural language by letting it run Treeline CLI commands. Note: by default Claude won't know the DB schema. Point it to this README and it should be able to explore your data and analyze it.
- Automatically parse bank statements, format as CSV, then import into Treeline
- Train an ML model on your data to tag transactions, then use the ML model in a automatic tagger (see `treeline new tagger --help`)
- Setup a cron job to run `treeline sync` daily
- Setup a cron job to backup your data into Google Drive or Dropbox

## Getting Help

- **Bug reports & feature requests**: [GitHub Issues](https://github.com/zack-schrag/treeline-money/issues)
- **Questions & discussions**: [GitHub Discussions](https://github.com/zack-schrag/treeline-money/discussions)

When filing a bug report, please include:
- Your operating system and Python version
- The command you ran
- The full error message or unexpected behavior
- Steps to reproduce the issue
