Clerk

A utility for automatically syncing transactions from Plaid API.

Features:

• Sync transaction data from Plaid to your local machine
• Integration with Plaid Link
• Keeps local data consistent with Plaid data as transactions are modified

2022-12 Disclaimer

This year Plaid stopped supporting legacy sign in options for several common institutions (maybe all?) on the development environment. As a result, integrations require full OAuth permissions in Plaid requiring additional authorization and approvals from both Plaid and various financial institutions.

As an individual, this tool may be far less useful depending on the instirutions you are interested in.

Motivation

Having a consistent and accurate source of transaction data makes tasks like budgeting, accounting, and taxes easier. I use this transaction stream to automatically generate beancount entries for Plain text accounting.

At the end of the day the data is yours and you can query the database using sqlite directly for building UIs, account monitoring, or all sorts of purposes. For some examples check out:

• clerk beancount importer
• clerk account alerting example

Installation

Building from source

# Binary found in ./target/release/clerk
cargo build --release

Prebuilt Binaries

Prebuilt binaries for Linux and MacOS (pre-M1) can be found for the latest release.

Usage

Configuration

clerk requires a configuration file.

# Providing a configuration file explicitly.
clerk -c clerk.toml accounts

If no configuration is explicitly given, clerk will search for a file called config.toml in directories based on the XDG user directory spec on Linux and the Standard Directories on MacOS.

Data is stored transparently as a single Json file, it's location is based on the same pair of specifications. Be mindful of where you store this file as it contains transaction history for linked accounts.

Link

Link is used to create an access token for a set of credentials linked to an institution. This is done by serving Plaid Link on your local machine to perform authentication.

# Link a new account to Plaid.
clerk link
# Refresh a linked accounts status, periodically required for some accounts
clerk link --update <LINK_ID>

# List all link items and their current status.
clerk link status

# Delete a link item from account links preventing future queries from retturning
# data for this link. This does not delete transaction of account data.

clerk link delete <ITEM_ID>

Transactions

Commands for interacting with transaction data for all tracked accounts.

# Syncs transactions for all tracked accounts with upstream data. The first sync
# may take a few seconds (it pulls up to 24 months of transaction history). Each
# consecutive sync will only pull the latest data and should take less time.
clerk txn sync

Accounts

Commands for displaying data about accounts that are currently tracked (i.e. accounts you have an active access token for).

# List all tracked accounts.
clerk account

# Display the current balance for tracked accounts. This command pulls the latest
# data and tends to be relatively slow.
clerk account balances

Caveats

This tool is meant to simplify the maintenance of a personal plaintext finance records, please consider where and how your data is stored (please don't run this on a public machine). Note that data is stored in a local sqlite database as plain text and makes no effort to encrypt or otherwise obfuscate your data.

This single database file can be encrypted for additional security using a file encryption tool like age.

Roadmap

• Automatic transaction deduping between linked accounts
• Expand on storage options (e.g. encryption / remote-storage)

Troubleshooting

I'm using clerk for the first time and getting data file doesn't exist errors.

If a database file doesn't already exist one won't be created automatically to prevent saving data in an unexpected place. You can either initialize and provide your own db file using sqlite or add ?mode=rwc to your db_file path.

db_file = "./clerk/clerk.db?mode=rwc"