fingrab

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 export monzo --token <monzo-api-token> --start 2025-03-01 --end 2025-03-31

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

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

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

Starling

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

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

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

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

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)
	})
}

1. 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.