Fingrab

A CLI for exporting financial data from various banks.

Currently supports: Monzo, and Starling.

Table of Contents

• Disclaimer
• Installation
  • Install via Go
  • From Source
  • Using Docker
• Usage
  • Obtaining API Tokens
    • Monzo
    • Starling
  • Exporting Transactions
    • Monzo
    • Starling
• Contributing
  • New Format
• License

Disclaimer

This project is not affiliated with or endorsed by Starling Bank or Monzo. It is an unofficial, independent, open-source implementation using their public APIs.

Installation

Install via Go

1. Ensure you have Go 1.24 or later installed.
2. Install the clu:

   go install github.com/HallyG/fingrab@latest

From Source

1. Ensure you have Go 1.24 or later installed.
2. Clone the repository:

   git clone https://github.com/hallyg/fingrab.git
   cd fingrab

3. Build the project:

   make build

Using Docker

1. Ensure you have Docker installed.
2. Build the docker image:

   make docker/build

Usage

Obtaining API Tokens

Monzo

1. Go to Monzo Developer Portal.
2. Log in to your Monzo developer account.
3. Open the Monzo App and allow API Playground access to your account.
4. Use the displayed access token.

Starling

1. Go to Starling Developer Portal.
2. Log in to your Starling developer account.
3. Create a new personal access token.
4. Use the generated access token.

Exporting Transactions

Monzo

# API Auth with cli flag
fingrab monzo transactions --token <monzo-api-token> --start 2025-03-01 --end 2025-03-31

# API Auth with env var
export MONZO_TOKEN=<monzo-api-token>
fingrab monzo transactions --start 2025-03-01 --end 2025-03-31

# API Auth with OAuth2 env var
export MONZO_CLIENT_ID=<monzo-client-id>
export MONZO_CLIENT_SECRET=<monzo-client-secret>
fingrab monzo transactions --start 2025-03-01 --end 2025-03-31

# Exporting to Moneydance format
fingrab monzo transactions --token <monzo-api-token> --start 2025-03-01 --end 2025-03-31 --format moneydance

# Verbose logging
fingrab monzo transactions --token <monzo-api-token> --start 2025-03-01 --end 2025-03-31 --verbose

# Logging without colour
fingrab monzo transactions --token <monzo-api-token> --start 2025-03-01 --end 2025-03-31 --verbose --no-colour

Starling

# API Auth with cli flag
fingrab starling transactions --token <starling-api-token> --start 2025-03-01 --end 2025-03-31

# API Auth with env var
export STARLING_TOKEN=<starling-api-token>
fingrab starling transactions --start 2025-03-01 --end 2025-03-31

# API Auth with OAuth2 env var
export STARLING_CLIENT_ID=<starling-client-id>
export STARLING_CLIENT_SECRET=<starling-client-secret>
fingrab starling transactions --start 2025-03-01 --end 2025-03-31

# Exporting to Moneydance format
fingrab starling transactions --token <starling-api-token> --start 2025-03-01 --end 2025-03-31 --format moneydance

# Verbose logging
fingrab starling transactions --token <starling-api-token> --start 2025-03-01 --end 2025-03-31 --verbose

# Logging without colour
fingrab starling transactions --token <starling-api-token> --start 2025-03-01 --end 2025-03-31 --verbose --no-colour

Contributing

New Format

To add a new format for exporting financial data, follow these steps:

1. Navigate to the internal/format.
2. Create a new Go file for your format (e.g. exampleformat.go).
3. Add a new format by implementing the Formatter interface defined in format.go. For example:

package format

import (
	"io"

	"github.com/HallyG/fingrab/internal/domain"
)

const FormatTypeExample FormatType = "newformat"

type ExampleFormatter struct {
	w io.Writer
}

func NewExampleFormatter(w io.Writer) *ExampleFormatter {
	return &ExampleFormatter{w: w}
}

func (e *ExampleFormatter) WriteHeader() error {
	_, err := e.w.Write([]byte("header content\n"))
	return err
}

func (e *ExampleFormatter) WriteTransaction(transaction *domain.Transaction) error {
	_, err := e.w.Write([]byte("transaction content\n"))
	return err
}

func (e *ExampleFormatter) Flush() error {
	return nil
}

func init() {
	Register(FormatTypeExample, func(w io.Writer) Formatter {
		return NewExampleFormatter(w)
	})
}

4. Ensure the init function registers the new format with a unique FormatType.

License

This project is licensed under the MIT License. See the LICENSE file for details.