expensor

expensor

Expensor is a utility to find expense related emails from my bank and add those expenses to a Google Sheet for expense tracking. The Google Sheet then feeds a Grafana dashboard. Expensor relies on config based rules which can work for almost everyone.

I've documented why exactly expensor works for me on my blog. If you find these reasons just, you might find it useful too. The rules are dead simple regex extractions which are fast (as far as reading emails go) and can be updated/modified pretty easily.

How does it work?

Expensor is designed to

1. Periodically check my inbox
2. Run the queries defined in my rules to find emails of interest
3. Extract transaction details like the amount, merchant name, date of transaction.
4. Write them to a Google Sheet.
5. Repeat

Installation

Pre-built Binaries

Download the latest release for your platform from the releases page.

Docker

Pull the latest Docker image from GitHub Container Registry:

docker pull ghcr.io/arionmiles/expensor:latest

From Source

Requires Go 1.25.5 or later:

go install github.com/ArionMiles/expensor/cmd/expensor@latest

Setup

1. Configure Google Cloud Project

   • Follow the Gmail API Quickstart Guide
   • Download the OAuth credentials JSON file
   • Enable both Gmail API and Google Sheets API for your project

2. Place Credentials File Save your OAuth credentials JSON file to:

   data/client_secret.json
   

3. Run Setup

   expensor setup
   

   This will guide you through OAuth authentication and save the token to data/token.json.

4. Set Environment Variables

   # Required: Sheet name/tab within the spreadsheet
   export GSHEETS_NAME="Sheet1"
   
   # One of these is required:
   export GSHEETS_ID="your-existing-spreadsheet-id"  # Use existing sheet
   # OR
   export GSHEETS_TITLE="Expense Report"  # Create new sheet with this title
   

5. Run Expensor

   expensor run
   

Running with Docker

Create a docker-compose.yml file:

version: '3.8'
services:
  expensor:
    image: ghcr.io/arionmiles/expensor:latest
    environment:
      - GSHEETS_ID=${GSHEETS_ID}
      - GSHEETS_NAME=${GSHEETS_NAME}
    volumes:
      - ./data:/app/data  # Mount data directory for credentials and token
    restart: unless-stopped

Create a .env file with your configuration:

GSHEETS_ID=your-spreadsheet-id
GSHEETS_NAME=Sheet1

Place your files in the data/ directory:

• data/client_secret.json - Your Google OAuth credentials
• data/token.json - OAuth token (generated by running expensor setup)

Run with:

docker-compose up -d

Important: You must run expensor setup once (either locally or in the container) to generate the OAuth token before the app will work.

Configuration

Required Files

Environment Variables

Development

This project uses Task for automation.

Setup Development Environment

# Install Task (if not already installed)
brew install go-task/tap/go-task  # macOS
# or
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin

# Install development tools
task install-tools

Common Tasks

# Format code
task fmt

# Run linter (local config)
task lint

# Run tests
task test

# Run tests with coverage
task test:cover

# Build binary
task build:binary

# Build Docker image
task build:docker

# Run all CI checks
task ci

Expensor doesn't support/recognize transactions from my bank

Open an issue with the email body content and I will take a look, and possibly add the rules into expensor so those are supported.