/ 
Finance-Tiller2QIF-1.10
/ README.md

NAME

tiller2qif

Finance::Tiller2QIF

DESCRIPTION

Convert Tiller CSV exports to QIF for import into Financial software like GnuCash, KMyMoney, Quicken, HomeBank, Money Manager Ex and many others.

SYNOPSIS

# Command-line
tiller2qif run --input export.csv --db tiller.sqlite3 \
               --output import.qif [--mapfile mapping.txt]

# Programmatic — see PROGRAMMATIC USE below
use Finance::Tiller2QIF::ReadCSV;
use Finance::Tiller2QIF::Map;
use Finance::Tiller2QIF::WriteQIF;

Finance::Tiller2QIF::ReadCSV::Ingest( 'export.csv', 'tiller.sqlite3' );
Finance::Tiller2QIF::Map::Map({ db_path => 'tiller.sqlite3', mapfile => 'mapping.txt' });
Finance::Tiller2QIF::WriteQIF::Emit( 'tiller.sqlite3', 'import.qif' );

OVERVIEW

Tiller Money (tillerapp.com) aggregates bank and credit-card transactions into a Google Sheet and lets you export a CSV. This module ingests that CSV into a SQLite database, optionally applies a category-mapping file to translate Tiller's auto-assigned categories to match your accounts/categories, then emits a QIF file ready for import.

The three phases can be run individually or together:

INSTALLATION

From CPAN

cpan Finance::Tiller2QIF
# or
cpanm Finance::Tiller2QIF

Perl Dependencies

Runtime: Cpanel::JSON::XS, DateTime::Format::Flexible, DBD::SQLite, DBI, Getopt::Long::Descriptive, Path::Tiny, Text::CSV

Testing: Capture::Tiny, Test2::V0, Test2::Bundle::More, Test2::Tools::Exception

On Debian/Ubuntu:

All of Tiller2QIF’s dependencies are available through package management if you need to install to system Perl on Debian 13 or Ubuntu 26.04 or later.

sudo apt install libpath-tiny-perl libtext-csv-perl libtest2-suite-perl libcapture-tiny-perl \
  libdbi-perl libdbd-sqlite3-perl libgetopt-long-descriptive-perl \
  libcpanel-json-xs-perl libdatetime-format-flexible-perl
sudo cpan install Finance::Tiller2QIF

On Windows

tiller2qif works with Strawberry Perl, after installing Strawberry Perl, install from CPAN.

CLI COMMANDS

The command word may be given either before or after the options; any other stray argument on the command line is an error.

OPTIONS

All options can be supplied on the command line or in a JSON config file. Use tiller2qif newconfig --config path/to/file.conf to generate a starter config file. A typical config file looks like:

{
  "input":      "~/Downloads/mytillerdump.csv",
  "output":     "/tmp/tillerout.qif",
  "db":         "~/.data/tiller2qif.sqlite3",
  "mapfile":    "~/.config/tiller.mapping",
  "viewer":       "console",
  "verbose":      false,
  "checkpoint":   false,
  "confirm":      false,
  "multipreview": false
}

Pass the config file with --config. Command-line options override config file values.

MAPPING FILE

The mapping file controls how Tiller categories are translated into destination account or category names and which transactions to suppress. Each non-comment line has the form:

[AccountFilter] field | pattern | destination

Lines beginning with # and blank lines are ignored. Rules are evaluated in order; the first matching rule wins and no further rules are checked for that transaction.

For double-entry programs such as GnuCash, destination is a full account name (e.g. Expenses:Groceries). For single-entry programs such as Quicken it is a category name.

The optional default line sets the fallback for transactions that match no rule. It must appear as the last non-comment line:

default | source

If the default line is omitted, unmatched transactions behave as default | source.

EXAMPLES

VS CODE EXTENSION

The repository includes a Visual Studio Code extension, vscode-tiller-map/, which highlights mapping files and preview files and completes destination account names from your chart of accounts. It is not published to the Marketplace, it can only be installed from a checkout of the repository.

With --viewer code and --multipreview the actions preview and run will open the preview and map file in vscode

Installation

git clone https://github.com/brainbuz/tiller2qif
cp -r tiller2qif/vscode-tiller-map ~/.vscode/extensions/
# or, to track the checkout:
ln -s "$PWD/tiller2qif/vscode-tiller-map" ~/.vscode/extensions/

Reload VS Code afterwards.

Syntax Highlighting

Files with .map and .mapping extensions are recognized as mappings, preview files have the t2qpv extension.

Completion Hinting

In addition to completion of Tiller2QIF keywords you can also configure your Chart of Accounts for Completion! The extension's settings tiller2qifMap.coaPath and tiller2qifMap.coaFormat control this. Currently the only available coaFormat is gnucash-csv.

Row Colors

tiller2qifMap.rowColors controls row backgrounds in both file types. rainbow, the default, gives rows a repeating series of subtle background colors; none turns backgrounds off. A preview transaction occupies two lines, both receive the same color.

Advanced Use

You can write SQL scripts or use an interactive sqlite3 client to make changes between steps. For example your Tiller sheet might have an account "Checking", while your table of accounts has "Assets::Current Assets::Bank::Checking". With custom SQL you can keep the short name in Tiller even though mapping rules can't rename accounts.

The --beforemap and --aftermap options allow SQL scripts to run immediately before and after the map phase without having to break the workflow into separate commands. This is the preferred way to preprocess or post-process transactions when using run, or map as a single step.

The preview command is meant to be run between map and emit. You may run the steps individually (ingest, map, preview, emit), or use the --confirm option to run preview before emit (including run). The preview table is wide, so --viewer is often more comfortable than the terminal; combined with --confirm it lets you read the pending transactions in an editor or pager and then answer the export prompt.

When using --confirm with --checkpoint, three choices Y=Yes N=No R=Revert are offered. No keeps the database state while not completing the export, Revert restores the database to the checkpoint in addition to aborting.

While other CSV export sources are not directly supported, you can write a script to remap the fields for ingestion or just import into the table, and then use the map and emit stages to complete your export. If translating other CSV sources be aware that Tiller currently only provides it's data in the US 'MM/DD/YYYY' format, this program can also accept dates in ISO 8601 'YYYY-MM-DD'. Data is written into the SQLite database using the ISO 8601 format.

PROGRAMMATIC USE

Finance::Tiller2QIF is primarily a CLI tool; the public functions exist to support the command dispatcher. Programmatic users will likely use this module as example code and call the sub-modules directly (Finance::Tiller2QIF::ReadCSV, Finance::Tiller2QIF::Map, Finance::Tiller2QIF::WriteQIF).

Note that all functions expect db_path as the database parameter. The CLI normalises the --db option to db_path internally; programmatic callers should use db_path directly.

AUTHOR

John Karr brainbuz@cpan.org

LICENSE

GPL version 3 or later.