JCF Documentation

Matching

Last updated on Jan 06, 2021

I use the JCF tool to convert my bank’s transaction CSV files to ledger-CLI compatible files.

Never head of JCF? See the setup.

JCF is a tool that reads transactions from CSV files (e.g. bank and credit card website exports) and provides a series of prompts to guide you in splitting each with another account in your ledger. After, it exports a ledger-CLI compatible file that can be merged in to a master ledger.

  1. First, download a CSV from your institution. If you have no prior transactions from this account in your ledger, choose any amount of history (be aware invocations of JCF are one-shot and cannot be paused/continued). Otherwise, check the register to see where the export should start:

    # git clone https://github.com/brentwalther/ledger-scripts
# cd ledger-scripts

bash register "Ally 1234"

... prints out most recent transactions in Ally 1234 account.

  2. Adding a settings profile for the institution’s CSV format.

  3. Ensuring your master.accounts file has all the accounts you intend to use for matching.

After that, I convert a CSV file to a ledger file like this:

cd ~/Development/ledger-scripts
# Make sure you have your JCF workspace set in vars.sh!
bash match.sh ally,1234 ~/Downloads/input.csv ~/Downloads/output.ledger

After running the command, JCF will import all your existing account and transactions then present you with a series of match prompts like the following:

┌────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│Matched 10 of 28 transactions thus far.                                                                     │
├────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│Jan 29, 2020 - Torchy's Tacos                                                                               │
│    -$18.25    Liabilities:Credit Card:Chase                                                                │
│                                                                                                            │
│(1)  Expenses:Food/Drink:Restaurants                                                                        │
│(2)  Expenses:Food/Drink:Alcohol & Bars                                                                     │
│(3)  Leave unmatched.                                                                                       │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Enter an option number (1 of 3), type a character and hit tab to autocomplete from 52 options, or hit enter
to accept the default (1):

The options choices are determined by the existing transaction examples in your master ledger and improve over time as you get more examples. If you’re just starting out you may have to use the autocomplete functionality quite often (assuming you have your accounts set up!) but over time you may be able to simply continue hitting to accept the best guess because it is correct.

Assuming you didn’t escape via <Ctrl> + C, you’ll see the path to the exported ledger file as soon as you finish matching the transactions. It’ll look like:

Jan 06, 2021 9:03:40 PM net.brentwalther.jcf.CsvMatcher run
INFO: Wrote file: yes - /home/brentwalther/Downloads/output.ledger

Next, get on to merging it.