Skip to content

Latest commit

 

History

History
363 lines (241 loc) · 13 KB

README.md

File metadata and controls

363 lines (241 loc) · 13 KB
Raw

Documentation

Table of Contents

Overview

Mintable

Mintable simplifies managing your finances, for free, without ads, and without tracking your information. Here's how it works:

  1. You connect your accounts and a spreadsheet to Mintable.
  2. Mintable integrates with your financial institutions to automatically populate transactions into the leftmost columns in your spreadsheet.
  3. You can add whatever formulas, charts, or calculations you want to the right of your transactions (just like a normal spreadsheet). We also have templates to get you started.

Installation

Creating a Fresh Installation

  1. Sign up for Plaid's Free Plan. The free plan is limited to 100 banking institutions which should be more than enough for personal use. After applying and verifying your email it usually takes a day or two for them to approve your account.

  2. Install the global mintable command line utility:

    npm install -g mintable

  3. Set up the integration with your banks and a spreadsheet using the setup wizard:

    mintable setup

  4. Update your account balances/transactions:

    mintable fetch

Mintable CLI

Migrating from v1.x.x

⚠️ Warning: Plaid introduced a breaking change in July 2020 which deprecates the Public Key component from the authentication process. Once you upgrade to v2.x.x and disable your Public Key, you will no longer be able to continue using your v1.x.x installation. Proceed with caution.

  1. Disable the Public Key in your Plaid Dashboard (read ⚠️ above!)

  2. Install the new v2.x.x mintable command line utility:

    npm install -g mintable

  3. Migrate your config to the new format:

    mintable migrate --old-config-file /path/to/your/old/mintable.config.json

  4. Update your account balances/transactions:

    mintable fetch

Note: After successful migration you can delete everything in your v1.x.x mintable folder. You may want to keep a copy of your mintable.config.json for posterity.

Importing Account Balances & Transactions

Automatically – in the cloud – via Plaid

You can run:

mintable plaid-setup

to enter the Plaid setup wizard. This will allow you to automatically fetch updated account balances/transactions from your banking institutions every time mintable fetch is run.

After you have the base Plaid integration working, you can run:

mintable account-setup

to enter the account setup wizard to add, update, or remove accounts.

Account Setup

This will launch a local web server (necessary to authenticate with Plaid's servers) for you to connect your banks.

To add a new account, click the blue Link A New Account button. To re-authenticate with an existing account, click the blue Update button next to the account name in the table.

Note: Plaid is the default import integration and these steps are not necessary if you've already run mintable setup.

Automatically via Teller

You can run:

mintable teller-setup

to enter the Teller setup wizard. This will ask for things like the certificate, private key, and application ID provided when you sign up for Teller.

After you have the base Teller integration working, you can run:

mintable teller-account-setup

to enter the account setup wizard to add or remove accounts.

This will launch a local web server (necessary to authenticate with Teller's servers) for you to connect your banks.

To add a new account, click the blue Link A New Account button.

Note: Access to an account may expire. In that case, you should run mintable teller-account-setup to re-add the accounts with expired access.

After set up is complete, you will import updated account balances/transactions from your banking institutions every time mintable fetch is run.

Manually – on your local machine – via CSV bank statements

You can run:

mintable csv-import-setup

to enter the CSV import setup wizard. This will allow you to manually import files or globs (path/to/my/folder/transactions/*.csv) every time mintable fetch is run.

You'll need to define a transformer to map properties in your source CSV spreadsheet to valid Mintable transaction properties, and a valid date format.

We have a number of templates available for popular financial institutions to get you started:

These templates can be added into the accounts section of your mintable.jsonc configuration file.

Note: CSV Imports do not support account balances.

Exporting Account Balances & Transactions

In the cloud – via Google Sheets

You can run:

mintable google-setup

to enter the Google Sheets setup wizard. This will allow you to automatically update a sheet with your transactions/account balances every time mintable fetch is run.

Note: Google Sheets is the default export integration and this step is not necessary if you've already run mintable setup.

On your local machine – via CSV files

You can run:

mintable csv-export-setup

to enter the CSV export setup wizard. This will allow you to manually export a CSV containing your transactions/account balances every time mintable fetch is run.

Updating Transactions/Accounts

Manually – in your local machine's terminal

After you have connected a banking institution, you can run:

mintable fetch

to automate updates to your spreadsheet.

Automatically – in your Mac's Menu Bar – via BitBar

You can put Mintable in your Mac's menu bar, and have it run automatically every hour using our BitBar Plugin.

BitBar

  1. Install BitBar on your Mac.
  2. Set your plugin folder.
  3. Create a new file in mintable.1h.zsh in your plugin folder.
  4. Copy & paste this into the file you just created and save.
  5. Open BitBar > Preferences > Refresh All to update your spreadsheet.

Note: The plugin above is pending approval and this install process should be much easier moving forward.

Automatically – in your local machine's terminal – via cron

You can run Mintable automatically within your terminal using cron:

cron

echo "0 * * * * export PATH="/usr/local/bin:$PATH" && mintable fetch" > ~/mintable.cron
crontab ~/mintable.cron

The first step creates a new file ~/mintable.cron which contains an interval and the command you want to run. The second step registers that file with crontab, the command-line executable which actually schedules the job with your operating system.

The default refresh interval is 1 hour – you can use Crontab Guru to define your own interval.

You can remove this schedule by running:

crontab -r

Note: The instructions above assume your global mintable CLI lives in /usr/local/bin, but if your installation path is different (run which mintable) you should use that instead.

Automatically – in the cloud – via GitHub Actions

You can use GitHub Actions to run Mintable automatically in the cloud:

GitHub Actions

  1. Fork this repo.

  2. Go to your repo's Actions > Click I understand my workflows, go ahead and enable them

  3. Go to your repo's Settings > Secrets and add a New Secret.

  4. Name the secret MINTABLE_CONFIG, and copy and paste the full contents of your ~/mintable.jsonc file into the body of the secret.

  5. In your repo's ./.github/workflows/fetch.yml, uncomment the following block and commit the changes:

        # schedule:
    #   - cron:  '0 * * * *'

In the Actions tab of your repo, the Fetch workflow will now update your sheet periodically. The default refresh interval is 1 hour – you can use Crontab Guru to define your own interval.

Note: The minimum interval supported by GitHub Actions is every 5 minutes.

Transaction Rules

Transaction filter Rules

Transaction filter rules allow you to exclude transactions from your spreadsheet based on a set of conditions.

For example, if you wanted to exclude any cross-account transfers, you might add the following to your transactions.rules config:

"rules": [
    {
        "conditions": [
            {
                "property": "name",
                "pattern": "(transfer|xfer|trnsfr)",
                "flags": "ig"
            }
        ],
        "type": "filter"
    }
]

Transaction override Rules

Transaction override rules allow you to override auto-populated fields based on a set of conditions, search for a pattern, and replace it with another pattern.

You might want to do this to standardize values between financial institutions (XFER -> Transfer), or tune things to suit your particular budgeting needs (described below).

For example, let's say you want to know how much you are spending on coffee each month, but Plaid/your bank categorizes your favorite shops as Restaurants – Fast Food. You might add the following to your transactions.rules config:

"rules": [
    {
        "conditions": [
            {
                "property": "name",
                "pattern": "(dunkin|starbucks|peets|philz)",
                "flags": "ig"
            }
        ],
        "type": "override",
        "property": "category",
        "findPattern": "Fast Food",
        "replacePattern": "Coffee Shops",
        "flags": "i"
    }
]

When you run mintable fetch the next time, the category would be Restaurants – Coffee Shops.

Development

To get started:

git clone https://github.com/kevinschaich/mintable
cd mintable

npm install
npm run build
npm link

The global mintable command will now point to your local version (/lib/scripts/cli.js). To start compilation in watch mode:

npm run watch

To publish a new version, increment version in package.json and run:

git add package.json
git commit -m 'vX.X.X'
git push

rm -rf lib/
npm run build
npm publish

To revert to the production release of mintable, run:

npm unlink
npm install -g mintable

Contributing

Before posting please check if your issue has already been reported. We'll gladly accept PRs, feature requests, or bugs via Issues.