tiller-sheets-export 0.1.0

Unofficial tool to fetch Tiller financial data from Google Sheets as Arrow, DuckDB, or Parquet

tiller-sheets-export

Unofficial tool to fetch Tiller financial data from Google Sheets as Arrow, DuckDB, or Parquet.

Note: This is an unofficial project and is not affiliated with, endorsed by, or connected to Tiller HQ.

Auth

This tool uses Application Default Credentials. You will need a Google Cloud project with the Sheets API enabled.

# 1. Login to Google Cloud
gcloud auth login

# 2. Setup credentials with Sheets scope
gcloud auth application-default login --scopes=https://www.googleapis.com/auth/spreadsheets.readonly

# 3. Set your project (replace <PROJECT_ID> with your actual GCP project ID)
gcloud auth application-default set-quota-project <PROJECT_ID>
gcloud services enable sheets.googleapis.com --project=<PROJECT_ID>

Alternatively, set GOOGLE_APPLICATION_CREDENTIALS to the path of a service account JSON key.

Installation

CLI Installation

Linux/macOS permanent install with uvx.sh (installs uv + tiller-sheets-export):

curl -LsSf uvx.sh/tiller-sheets-export/install.sh | sh
tiller-sheets-export "https://docs.google.com/spreadsheets/d/YOUR_ID/edit"

Or, if you have uv already installed:

uvx tiller-sheets-export "https://docs.google.com/spreadsheets/d/YOUR_ID/edit"

Library Installation

uv add tiller-sheets-export

CLI Usage

tiller-sheets-export "https://docs.google.com/spreadsheets/d/YOUR_ID/edit"

This generates data/processed/transactions.parquet and data/processed/categories.parquet.

Library Usage

from tiller_sheets_export import TillerData

data = TillerData.fetch(spreadsheet_url="https://docs.google.com/spreadsheets/d/YOUR_ID/edit")

# To Arrow
data.transactions.to_arrow()
data.categories.to_arrow()

# To DuckDB
data.transactions.to_duckdb()
data.categories.to_duckdb()

# To pandas
data.transactions.to_arrow().to_pandas()

Query with DuckDB

import duckdb

con = duckdb.connect()
transactions = data.transactions.to_duckdb(con=con)
categories = data.categories.to_duckdb(con=con)

con.sql("""
    SELECT t.date, t.description, t.amount, c.group, c.type
    FROM transactions t
    LEFT JOIN categories c ON t.category = c.category
    ORDER BY t.date DESC
""").show()

Google Colab

from google.colab import auth
auth.authenticate_user()

!pip install tiller-sheets-export

from tiller_sheets_export import TillerData

data = TillerData.fetch(spreadsheet_url="https://docs.google.com/spreadsheets/d/YOUR_ID/edit")
data.transactions.to_arrow().to_pandas()

Schema

Transactions

See Tiller's documentation for column descriptions.

Column	Type
date	date
description	string
category	string
amount	decimal(19,2)
account	string
account_number	string
institution	string
month	date
week	date
transaction_id	string
account_id	string
check_number	string
full_description	string
date_added	timestamp
import_tag	string
merchant_name	string
category_hint	string
note	string
tags	list<string>
categorized_date	timestamp
statement	string
metadata	string

Categories

Column	Type
category	string
group	string
type	string
hide_from_reports	bool
tags	list<string>

Data Quality

Automatic validation logs warnings for type mismatches, missing categories, and empty critical fields. Invalid values are coerced to NULL.

Other Tiller Projects

• https://github.com/peterkeen/ledger_tiller_export - Tool to export transactions from Tiller into Ledger.
• https://github.com/basnijholt/tiller-streamlit - Streamlit dashboard for Tiller data.
• https://github.com/jackstein21/tiller-mcp-server/tree/main - MCP server exposing Tiller data.
• https://github.com/clomok/finance-visualizer/ - Browser-based visual data explorer.