User Guide

July 13, 2026 · View on GitHub

The companion to the README, with the longer explanations that don't belong there. You rarely need this while using the app, since the help bar at the bottom of every view shows the relevant keys and Ctrl+H opens the full keybindings menu for whatever mode you're in.

The main view

The transaction list is where you land on launch, with a summary bar up top.

  • ↑/↓ move between transactions, PageUp/PageDown jump by page, Ctrl+↑/Ctrl+↓ jump to the first/last transaction
  • 1-6 (or F1-F6) sort by Date, Description, Category, Subcategory, Type, or Amount; press again to reverse
  • a adds a transaction, e edits the selected one, d deletes it (with a y/n confirmation), Ctrl+C copies it
  • f opens the quick filter, Ctrl+F the advanced filter
  • r opens recurring settings for the selected transaction
  • s, c, and b open the monthly summary, category summary, and budget views
  • o opens settings
  • q or Esc clears any active filter, or quits the app when no filter is active

Adding and editing transactions

Tab/Shift+Tab or ↑/↓ move between fields and Enter saves. In the date field, + (or =) moves the date forward a day, - moves it back, and Shift+←/Shift+→ jump by month. Category and subcategory fields offer a selection list (with fuzzy search if you've enabled it in settings), and ←/→ toggle the income/expense type.

Filtering

The quick filter (f) matches as you type across your transactions. Enter closes the input and keeps the filter applied; Esc or Ctrl+R clears it.

The advanced filter (Ctrl+F) filters on multiple fields at once: date range, description, category, type, and amount. Tab or ↑/↓ move between fields, Enter applies, Esc cancels, and Ctrl+R resets everything.

Recurring transactions

Select a transaction and press r to make it recurring. Available frequencies:

  • Daily
  • Weekly
  • Bi-weekly
  • Semi-monthly (1st and 15th)
  • Semi-monthly, weekday adjusted (shifted off weekends)
  • Monthly
  • Quarterly
  • Yearly

Occurrences are generated automatically from the start date up to today, and an optional end date stops the series. Generated occurrences stay linked to their source transaction. Edit or delete the source to affect the series.

Summary views

Monthly summary (s) shows income, expenses, and net per month with an interactive chart. ↑/↓ move between months, ←/→ (or [/]) move between years. m toggles a multi-month line chart, and c toggles cumulative mode, which also draws the target budget line from settings.

Category summary (c) breaks down each month by category. Enter expands or collapses a month, PageUp/PageDown move between months, ←/→ between years.

Budget view (b) compares spending against your monthly target and any per-category budgets. ↑/↓ move between categories, ←/→ between months, Shift+←/Shift+→ between years. Press c to open the category catalog and adjust per-category budgets without leaving the view.

The category catalog

The catalog holds your categories and subcategories. Open it from Settings (Manage Categories) or with c from the budget view. q/Esc returns to whichever view you came from.

  • ↑/↓ move between entries, PageUp/PageDown jump by page, Ctrl+↑/Ctrl+↓ jump to the first/last entry
  • f filters the catalog as you type; Enter keeps the filter applied, Esc or Ctrl+R clears it
  • a adds a category, e or Enter edits the selected one, d deletes it
  • Expense categories can optionally hold a per-category target budget, used by the budget view

Settings

Press o to open settings. The menu is grouped into sections:

Data Management

  • Database Path: where the SQLite database lives (see Data storage below).
  • Manage Categories: opens the category catalog.
  • Import Transactions (CSV): merges a CSV file into your database; new rows are added, exact duplicates are skipped.
  • Export Transactions (CSV): writes all transactions to a CSV file for backup or use elsewhere.

Monthly Summary View

  • Target Budget: your monthly spending goal, drawn as a line in the monthly summary's cumulative mode and used by the budget view.

Transaction View

  • Hourly Rate: optionally enter your hourly earning rate; a Show Costs in Hours toggle then appears that displays amounts as hours worked.

Input Preferences

  • Fuzzy Search Categories: enables fuzzy matching when picking categories and subcategories.

General Preferences

  • Hide Help Bar: hides the bottom help bar if you want the extra screen space (Ctrl+H still works).

Data storage

Transactions and categories are stored together in a local SQLite database (budget.db). On first run with a new database, it's seeded with the default category catalog. Default locations:

  • Linux: $XDG_DATA_HOME/BudgetTracker/budget.db (usually ~/.local/share/BudgetTracker/budget.db)
  • macOS: ~/Library/Application Support/BudgetTracker/budget.db
  • Windows: %APPDATA%\BudgetTracker\budget.db

The path is configurable in settings. Point it at a folder synced by iCloud, Google Drive, Dropbox, OneDrive, or similar to sync your budget across devices.

App preferences live separately in a config.json in your OS config directory:

  • Linux: ~/.config/BudgetTracker/config.json
  • macOS: ~/Library/Application Support/BudgetTracker/config.json
  • Windows: %APPDATA%\BudgetTracker\config.json

Changes are written to the database immediately as you add, edit, or delete, so there's no separate save step. CSV files are only written when you explicitly export.

Migrating from older versions

Versions before 1.4.0 stored transactions in a transactions.csv file. On first launch, the app imports that file into the database automatically and renames the original to transactions.csv.migrated-backup. Nothing is deleted.

CSV format

Import and export use these columns:

date, description, amount, transaction_type, category, subcategory
  • Date: accepts YYYY-MM-DD, YYYY/MM/DD, DD/MM/YYYY, or DD-MM-YYYY
  • Transaction type: Income or Expense, case-insensitive; i/e also work
  • Category/Subcategory: should reference categories that exist in the category catalog (manageable in settings)

Exports additionally include the recurring columns (is_recurring, recurrence_frequency, recurrence_end_date, is_generated_from_recurring). These are optional on import and default to a non-recurring transaction; generated recurring rows in a file are ignored on import and re-derived from their source transaction instead.

Importing merges into the database and skips exact duplicates, so re-importing the same file is safe. Exporting writes the full set you see in the app, including generated recurring occurrences.