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.

Categories

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.