Budget Tracker TUI

A fast, modern, and efficient Terminal User Interface (TUI) application for tracking your personal budget, built with Rust and Ratatui.

cargo install budget_tracker_tui

📚 Table of Contents

• 🖼️ Screenshots
• ✨ Features
• 🚀 Getting Started
• ⚡ Quick Start
• ⚙️ Settings & Configuration
• 📁 Data & CSV Format
• References

🖼️ Screenshots

Main transaction view with summary bar and help


Category summary with expandable/collapsible categories

Monthly summary with interactive chart and budget line


Budget View with yearly, monthly, and categorically focused data

CLICK FOR MORE SCREENSHOTS HERE

Multi-Month Line chart


Cumulative chart with budget line


Cumulative and multi month chart


Options Menu with Help / Keybindings Menu Open


Category/Sub-Category Fuzzy Search Enabled view


Category Catalog - Editable categories and custom category creation

✨ Features

• Intuitive Terminal UI: Manage your finances directly from your terminal with a clean, responsive interface (TUI).
• Transaction Management: Add, view, edit, and delete income and expenses.
• Recurring Transactions: Set up transactions that automatically recur — daily, weekly, bi-weekly, semi-monthly, semi-monthly (weekday adjusted), monthly, quarterly, or yearly — generated automatically up to today.
• Advanced Filtering: Filter transactions by date, description, category, type, and amount (including advanced multi-field filters).
• Smart Date Navigation: Use +/- to adjust dates by day, and Shift + Left/Right to jump by month in date fields.
• Categorization: Hierarchical categories and subcategories for all transactions, now managed in-app and stored in a local SQLite catalog.
• Fuzzy Search: Toggleable option to fuzzy search categories/subcategories for quick selection.
• Summaries & Charts: Visualize your spending/income by month and by category, with interactive charts and tables.
• Budget Tracking: Set a monthly target budget, assign per-category expense budgets, and review progress in the dedicated budget view.
• Data Persistence: Transactions and categories are stored together in a local SQLite database, with app preferences saved in a separate config file.
• Cross-Platform: Runs on Windows, macOS, and Linux.
• Keyboard-Driven: Fully operable with keyboard shortcuts for every action and mode. Press Ctrl+H for a help menu.
• Update Checker: Automatically checks for updates on startup and notifies you of new versions.
• CSV Import/Export: Bring transactions in from a CSV (duplicates skipped) or export them out anytime, with flexible date parsing and Excel compatibility.
• High Precision: Uses decimal arithmetic (no floating point errors) for accurate financial calculations.
• Built with Rust: Safety, speed, and reliability.

🚀 Getting Started

Install via Cargo / crates.io (Recommended)

The easiest way to install on Linux, macOS, or Windows (if you have Rust installed). One command, no cloning required:

cargo install budget_tracker_tui

After installation, the Budget_Tracker command is immediately available in your terminal.

Don't have Rust? Install it in seconds at rustup.rs — it includes cargo.

Optional tip: Set up a short alias for even quicker access:

# Add to your .bashrc / .zshrc / PowerShell profile
alias bt='Budget_Tracker'

Then just type bt to launch the app.

---

Windows Installer (No Rust Required)

If you are on Windows and prefer not to install Rust, you can download and run the latest installer directly from the Releases page — no toolchain needed.

Note: I do not have a Windows developer licence, so it will show as an unknown publisher.

• Download the latest Windows installer from the Releases page

---

Other Installation Options

Still working on adding support for direct downloads via some Linux package managers.

Build and run from source (recommended to just use crates.io):

# Clone the repository
git clone https://github.com/Feromond/budget_tracker_tui
cd budget_tracker_tui

# Build (use --release for an optimized build)
cargo build --release

# Run
./target/release/Budget_Tracker

Install globally from source:

cd budget_tracker_tui
cargo install --path .

⚡ Quick Start

1. Launch the app: Budget_Tracker (or bt if you set up the alias)
2. Add a transaction: Press a, fill in the fields, and press Enter to save.
3. Navigate: Use ↑/↓ to move between transactions, PageUp/PageDown to jump by pages, Ctrl+↑/Ctrl+↓ to jump to first/last transaction.
4. Sort transactions: Press 1-6 to sort by Date, Description, Category, Subcategory, Type, or Amount respectively.
5. Manage transactions: Press e to edit, d to delete, f to filter, r to manage recurring transactions.
6. View summaries: Press s for monthly summary, c for category summary, and b for the budget view.
7. Change settings: Press o to open settings — set the SQLite database path, manage categories, import/export transactions as CSV, set a target budget, and more.
8. Quit: Press q or Esc.
9. Help: Press Ctrl+H at any time to view the keybindings menu for the current mode.

⚙️ Settings & Configuration

• Database Path (primary storage):
  • Your transactions and category catalog are stored together in a local SQLite database (budget.db), configurable in-app (press o for settings).
  • 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 (e.g., C:\Users\<YourUsername>\AppData\Roaming\BudgetTracker\budget.db)
  • Cross-Device Sync: Point the database path at a cloud-synced folder (iCloud, Google Drive, Dropbox, OneDrive, etc.) to automatically sync your budget across multiple devices.
  • On first run with a new database, the app seeds it with the default category catalog.
• Import / Export Transactions (CSV):
  • From Settings, choose Import Transactions to merge a CSV into your database — new rows are added and exact duplicates are skipped — or Export Transactions to write all transactions to a CSV for backup or sharing.
• Migrating from an older version:
  • Earlier versions stored transactions in a transactions.csv file. On first launch the app automatically imports that file into the database and renames the original to transactions.csv.migrated-backup. Your data is preserved — nothing is deleted.
• Manage Categories:
  • From Settings, use Manage Categories to open the category catalog and add, edit, or delete categories/subcategories.
  • Expense categories can optionally store a per-category target budget for use in the budget view.
• Target Budget:
  • Set a monthly target budget in settings. This is used in the monthly summary and budget view.
• Hourly Rate:
  • (Optional) Set your hourly earning rate to toggle a view that shows transaction costs in "hours worked".
• Fuzzy Search:
  • Enable or disable the fuzzy search input for category selection (toggle in Settings menu o).
• Config File:
  • The application's settings are saved in a config.json file, which is stored in your OS's config directory:
    • Linux: ~/.config/BudgetTracker/config.json
    • macOS: ~/Library/Application Support/BudgetTracker/config.json
    • Windows: C:\Users\<YourUsername>\AppData\Roaming\BudgetTracker\config.json
  • This is separate from the database location, which lives in your OS's data directory (see above).

📁 Data & CSV Import/Export Format

• CSV Columns: date, description, amount, transaction_type, category, subcategory. Exports also 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.
• Date Format: Flexible! Accepts YYYY-MM-DD, YYYY/MM/DD, DD/MM/YYYY, or DD-MM-YYYY.
• Transaction Type: Income or Expense (case-insensitive, also accepts i/e)
• Category/Subcategory: Transaction rows should reference categories that exist in the SQLite category catalog. You can manage that catalog in-app from Settings.
• Import/Export: Prepare a CSV in Excel/LibreOffice or export from another tool (match the columns and use valid categories), then import it from Settings. Import merges into the database and skips exact duplicates; any generated recurring rows in the file are ignored and re-derived from their source. Export writes the full set you see in the app, including generated recurring occurrences.
• Data Safety: Transactions live in the SQLite database and are saved immediately as you add, edit, or delete them. CSV files are only written when you explicitly export (or as the one-time transactions.csv.migrated-backup created during migration).

References

Ratatui Rust