KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #ai-agent #developer-tools #claude-code #codex #deepseek-harness #ai-agents #react #mcp #rust

reckon

★ 435 Open GitHub ↗

Flexibly import bank account CSV files into Ledger for command-line accounting

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Reckon

![Build Status](https://github.com/cantino/reckon/workflows/Build%20Status/badge.svg)

Reckon automagically converts CSV files for use with the command-line accounting tool [Ledger](http://www.ledger-cli.org/).  It also helps you to select the correct accounts associated with the CSV data using Bayesian machine learning.

## Installation

Assuming you have Ruby and [Rubygems](http://rubygems.org/pages/download) installed on your system, simply run

gem install --user reckon

## Example Usage

First, login to your bank and export your transaction data as a CSV file.

To see how the CSV parses:

reckon -f bank.csv -p

If your CSV file has a header on the first line, include `--contains-header`.

To convert to ledger format and label everything, do:

reckon -f bank.csv -o output.dat

To have reckon learn from an existing ledger file, provide it with -l:

reckon -f bank.csv -l 2010.dat -o output.dat

Learn more:

> reckon -h

Usage: Reckon.rb [options]

-f, --file FILE                  The CSV file to parse
    -a, --account NAME               The Ledger Account this file is for
    -v, --[no-]verbose               Run verbosely
    -i, --inverse                    Use the negative of each amount
    -p, --print-table                Print out the parsed CSV in table form
    -o, --output-file FILE           The ledger file to append to
    -l, --learn-from FILE            An existing ledger file to learn accounts from
        --ignore-columns 1,2,5
                                     Columns to ignore, starts from 1
        --money-column 2
                                     Column number of the money column, starts from 1
        --money-columns 2,3
                                     Column number of the money columns, starts from 1 (1 or 2 columns)
        --raw-money
                                     Don't format money column (for stocks)
        --sort DATE|DESC|AMT
                                     Sort file by date, description, or amount
        --date-column 3
                                     Column number of the date column, starts from 1
        --contains-header [N]
                                     Skip N header rows - default 1
        --csv-separator ','
                                     CSV separator (default ',')
        --comma-separates-cents
                                     Use comma to separate cents ($100,50 vs. $100.50)
        --encoding 'UTF-8'
                                     Specify an encoding for the CSV file
    -c, --currency '$'               Currency symbol to use - default $ (ex £, EUR)
        --date-format FORMAT
                                     CSV file date format (see `date` for format)
        --ledger-date-format FORMAT
                                     Ledger date format (see `date` for format)
    -u, --unattended                 Don't ask questions and guess all the accounts automatically. Use with --learn-from or --account-tokens options.
    -t, --account-tokens FILE        YAML file with manually-assigned tokens for each account (see README)
        --table-output-file FILE
        --default-into-account NAME
                                     Default into account
        --default-outof-account NAME
                                     Default 'out of' account
        --fail-on-unknown-account
                                     Fail on unmatched transactions.
        --suffixed
                                     Append currency symbol as a suffix.
        --ledger-format FORMAT
                                     Output/Learn format: BEANCOUNT or LEDGER. Default: LEDGER
    -h, --help                       Show this message
        --version                    Show version

If you find CSV files that it can't parse, send me examples or pull requests!

## Unattended mode

You can run reckon in a non-interactive mode.
To guess the accounts reckon can use an existing ledger file or a token file with keywords.

`reckon --unattended -a Checking -l 2010.dat -f bank.csv -o ledger.dat`

`reckon --unattended -a Checking --account-tokens tokens.yaml -f bank.csv -o ledger.dat`

In unattended mode, you can use STDIN to read your csv data, by specifying `-` as the argument to `-f`.

`csv_file_generator | reckon --unattended -a Checking -l 2010.dat -o ledger.dat -f -`

### Account Tokens

The account tokens file provides a way to teach reckon about what tokens are associated with an account.  As an example, this `tokens.yaml` file:

Expenses:
      Bank:
        - 'ING Direct Deposit'

Would tokenize to 'ING', 'Direct' and 'Deposit'.  The matcher would then suggest matches to transactions that included those tokens. (ex 'Chase Direct Deposit')

Here's an example of `tokens.yaml`:

```
config:
    similarity_threshold: 2  # range 0-10

Income:
  Salary:
    - 'LÖN'
    - 'Salary'
Expenses:
  Bank:
    - 'Comission'
    - 'MasterCard'
  Rent:
    - '0011223344' # Landlord bank number
  Hosting:
    - /hosting/i # This regexp will catch descriptions such as WebHosting or filehosting
'[Internal:Transfer]': # Virtual account
  - '4433221100' # Your own account number
```

Reckon will use `Income:Unknown` or `Expenses:Unknown` if it can't match a transaction to an account.

The config key is a special key used to set configuration when running in unattended mode. The only config variable is similarity_threshold (currently).

You can override these names with the `--default_outof_account` and `--default_into_account` options.

### Substring Match

If, in the above example, you'd prefer to match any transaction that contains the string 'ING Direct Deposit' you have to use a regex:

Expenses:
      Bank:
        - /ING Direct Deposit/

## Contributing

We encourage you to contribute to Reckon! Here is some information to help you.

### Patches/Pull Requests Process

1. Fork the project.
2. Make your feature addition or bug fix.
3. Add tests for it. This is important so I don't break it in a future version unintentionally.
4. Commit, do not mess with rakefile, version, or history.
   - (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
5. Send me a pull request. Bonus points for topic branches.

### Integration Tests

Reckon has integration test located in `spec/integration`.  These are integration and regression tests for reckon.

Run all the tests:

./spec/integration/test.sh

Run a single test

./spec/integration/test.sh chase/account_tokens_and_regex

#### Add a new integration test

Each test has it's own directory, which you can add any files you want, but the following files are required:

- `test_args` - arguments to add to the reckon command to test against, can specify `--unattended`, `-f input.csv`, etc
- `output.ledger` - the expected ledger file output

If the result of running reckon with `test_args` does not match `output.ledger`, then the test fails.

Most tests will specify `--unattended`, otherwise reckon prompts for keyboard input.

The convention is to use `input.csv` as the input file, and `tokens.yml` as the tokens file, but it is not required.

## Copyright

Thanks to @BlackEdder for many contributions!

Currently maintained by @benprew. Thank you!

reckon

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README