Process bank transaction CSV exports (Nordea, ICA), auto-categorize transactions using configurable rules, manage transaction links, and generate analytical database views.
Process bank transaction CSV exports, auto-categorize transactions using configurable rules, manage transaction links, and generate analytical SQLite database views.
Quick Start
Run the CLI tool from your terminal pointing to your database path:
Destructive commands require interactive confirmation [y/N] when run in a terminal (TTY). If you are running these commands in automated scripts or non-interactive shells, you must pass the --yes or -y flag to bypass the prompt; otherwise, the command will abort with an error.
Display subscription stats dashboard or detail reports for matching subscriptions
`estimate-period [--days ] [--level <0
1
`set-estimate-level <0
1
Configuring Salary Periods
By default, the salary period boundary is fixed to the 25th of the month. You can customize this grouping behavior using the salary configuration commands.
Available Modes:
calendar: Group transactions by calendar months (1st to the last day).
fixed: Group transactions by a static day of the month (e.g., the 25th). Transactions on or after this day are grouped into the next month's period.
salary: Group transactions by automatically detecting the primary salary deposit date in each month (the transaction under the salary category with the largest positive amount).
CLI Configuration Commands:
bash
# View current configuration
python cli.py salary-config
# Change mode to salary (automatic payday detection)
python cli.py set-salary-mode salary
# Set the category name used to search for paydays (default is "Salary")
python cli.py set-salary-category "Salary"
# Change mode to a fixed day of the month (e.g. 27th)
python cli.py set-salary-mode fixed
python cli.py set-salary-day 27
[!WARNING]
If you choose the fixed day mode, be aware that bank deposits and transactions can shift early or late due to weekends and holidays.
Ensure your fixed day is configured early or late enough so that fluctuations in actual payday do not cause two salary deposits to fall into the same period (which would result in one month showing double income and the next showing zero income).
Alternatively, use the salary mode, which automatically detects the actual deposit transaction dates and shifts the boundaries dynamically.
Querying Statistics by Salary Period
All statistics and breakdown commands support the --period-type parameter:
calendar — Force standard calendar month boundaries.
salary — Force salary period boundaries (using the active salary-config settings).
default — Dynamically resolve to your active salary-config mode:
If mode is calendar, defaults to calendar months.
If mode is fixed or salary, defaults to salary periods.
For example, to query your housing category spending using the active salary period:
If you do not specify a --period-type flag, it will automatically default to the setting configured via set-salary-mode.
Tracking Recurring Payments & Subscriptions
This tool supports advanced, automated tracking and lifecycle management of recurring payments (e.g. Netflix, Spotify, broadband, utility bills) and income (e.g. Salary).
Core Concepts
Recurring Payments Table (recurring_payments)
Defines the rules, intervals, expected days, amount ranges, and lifespans for each recurring item.
Subscription Lifecycle & Runs
Resumed subscriptions (after cancellation) are tracked as separate runs/rows in recurring_payments.
Resumption: If a transaction matches a pattern of a cancelled subscription (after its end_date), it automatically spawns a new run/configuration for the resumption.
Auto-Closing: Active configurations that are missing expected payments are automatically closed (end_date is set to the last matched payment date) when running discover-recurring or passing the --close flag to import / categorize.
Flexible Date Intervals
Supports strict date/day checking with a configured tolerance window:
Monthly: Expected day of month (e.g. 25th, last day -1).
Weekly: Expected weekday.
Yearly: Expected month and day.
Days: Custom interval (e.g. every 90 days).
Tolerance: Tolerates shifts due to weekends/holidays (default 4 days).
Common Workflows
1. Auto-Discover Recurring Candidates
Scan transaction history to auto-identify recurring items (such as monthly subscriptions or utility bills) and automatically save them:
bash
# Preview candidates without writing to the database
python cli.py discover-recurring --dry-run
# Run auto-discovery and save configurations
python cli.py discover-recurring
# Active subscriptions monthly cost summary and expected next dates
python cli.py stats-recurring
# Detailed subscription history across active/cancelled runs and transaction lists
python cli.py stats-recurring "Disney Plus"
Common Workflows
Handling Shared-Expense Reimbursements
If you make a shared purchase (e.g., from the Gemensamt account, 50% ownership) and get reimbursed by an external person (e.g., via Swish to your Personligt account, 100% ownership) and subsequently transfer the payback to the shared account:
Reimburse the shared expense: Link the reimbursement transaction (the Swish inflow) directly to the original expense transaction (the shared purchase):
Effect: The Swish transaction is fully neutralized to 0.00 adjusted amount, and the credit to the expense transaction is automatically scaled by the shared account's ownership ratio (e.g., 50%), reducing your net cost correctly.
Note: The credit is scaled by the target account's ownership ratio (e.g., 50%) because the benefit of the payback is shared between the joint account owners.
Link the account transfer: Link the outflow from your main account to the inflow on your joint account as an internal transfer:
bash
python cli.py --db data/finance.db link <transfer_out_id> <transfer_in_id> --type internal_transfer
Effect: Both sides of the transfer are neutralized to 0.00, ensuring no false income or outflows are recorded.
Note: This step is skipped if the transfer has already been auto-linked.
To auto-route only positive inflows (like Swish reimbursements) to a category (e.g., ID 9) while leaving negative outflows uncategorized, add a rule with a minimum amount filter:
(Once linked, the adjusted amount drops to 0.00 and the transaction disappears from both lists).
How to Think About Reimbursements & Composite Transactions
When working with transaction links, it is crucial to distinguish between the raw bank ledger amount (actual cash flow) and the effective category/budgetary amount (represented by the adjusted_amount column).
The Core Principle
Reimbursements are not new income; they are a return of capital.
If an expense is reimbursed, the net expense is zero.
The incoming reimbursement money is not labor/investment income; it simply offsets the expense.
If you don't link them, your gross income and gross expenses will both be overstated by the reimbursement amount, distorting your reports.
Composite Transactions (e.g. Reimbursement Baked into Salary)
Often, a reimbursement is not a standalone transaction (like a Swish payment), but is packaged/baked into a larger composite transaction, such as a salary payment.
For example, if your employer pays you a single amount of 50,000 SEK, which contains:
45,000 SEK of actual labor income
5,000 SEK of expense reimbursement for a credit card charge
To avoid distorting both income and expenses, you must split this composite transaction. In this system, you do this using transaction links with fractional ratios.
Link Ratio Calculation Modes
The link command provides three modes to simplify this:
Source Ratio (--ratio <float>) - Default
Calculates the ratio relative to the source (from_id) transaction. Use when you want to allocate a direct fraction of the source.
Destination Ratio (--ratio-to <float>)
Calculates the ratio relative to the destination (to_id) transaction.
For example, to fully reimburse/zero out the First Card expense of -5,000 SEK from your salary, use:
bash
python cli.py link <salary_txn_id> <expense_txn_id> --type reimbursement --ratio-to 1.0
This automatically calculates the exact ratio ($5000 / 50000 = 0.10$). It reduces the salary's adjusted_amount to 45,000 SEK (reflecting your true labor income) and increases the credit card expense's adjusted_amount to 0.00 SEK (reflecting your true net expense).
Exact Cash (--amount <float>)
Specify the exact cash amount in SEK being reimbursed.
For example, to link exactly 5,000 SEK:
bash
python cli.py link <salary_txn_id> <expense_txn_id> --type reimbursement --amount 5000
Dry-run Previews
Always run with the --dry-run flag first to preview the downstream adjusted_amount effects before committing changes to the database:
bash
python cli.py link <from_id> <to_id> --type reimbursement --ratio-to 1.0 --dry-run
Tracking External Accounts
You can track capital transfers from your tracked accounts to untracked external accounts (such as savings or stock brokerage accounts).
Auto-linking:
When transactions are categorized (via categorize or manual overrides), if they match a transfer category linked to an external account, an external_transfer link is created automatically.
Manual Linking:
For one-off transfers, you can link a transaction directly to an external account:
bash
python cli.py link <transaction_id> --type external_transfer --to-account "Avanza Brokerage"
Querying Statistics:
Use the stats-transfers command to view net capital movements per external account:
For analytical reporting (e.g. dashboards, Grafana), the following views are registered in the database:
v_effective_transactions — Joins transactions with accounts to factor in ownership ratios and transfer link adjustments. Includes adjusted_amount, unsplit_amount, and raw_amount columns.
v_monthly_summary — Calculates net income/expenses by month (includes unsplit and gross aggregations).
v_category_monthly — Calculates monthly spending by category (includes unsplit and gross aggregations).
v_daily_spending_moving_average — 30-day moving average of daily spending.
v_category_monthly_averages — Average monthly spending by category.
v_salary_period_summary — Expense/income summary grouped by salary periods (using the active salary config: fixed or salary).
v_breakout_categories — Groups monthly spending into high-level categories (Groceries, Loans, Housing, Leisure, Car, etc.).
v_uncategorized_groups — Groups uncategorized transactions by normalized Swish/Card payment descriptions to identify potential new rules.
Querying Unmatched Reimbursements via CLI
Unmatched reimbursements (pending paybacks or refunds) are incoming transactions on tracked accounts that have not yet been neutralized by a transaction link. They can be queried and filtered using the CLI:
Workflow:
Query the transactions depending on the categorization workflow in use:
If using Uncategorized / Flat List (Option A):
bash
