Budget Tracker TUI

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

📚 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

SEE MORE SCREENSHOTS HERE <>

✨ 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 Transaction: Setup transactions that automatically recur at select frequencies.
• 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: Built-in, hierarchical categories and subcategories for all transactions.
• 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 and see your progress (including a budget line in summary charts).
• Data Persistence: All data is stored locally in a configurable CSV file. Settings are saved in a 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.
• Robust CSV Support: Flexible date parsing, easy import/export, 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

Windows Installer (Recommended for Windows Users)

If you are on Windows, you can download and run the latest installer for a quick and easy setup. This is the simplest way to get started on Windows—no Rust or Cargo required!
(NOTE: I do not have a windows developer licence so it will be an unknown publisher)

• Download the latest Windows installer from the Releases page

Prerequisites (for manual/cargo install)

• Rust (includes cargo)

Installation & Running

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

Build and Run Manually:

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

# Build the project (use --release for optimized build)
cargo build --release

# Run the executable
./target/release/Budget_Tracker

Install Globally with Cargo (Recommended for Linux/macOS):

# Navigate to the project directory
cd budget_tracker_tui

# Install the binary to Cargo's bin directory
cargo install --path .

After installation, the Budget_Tracker command should be available in your terminal directly.

Optional Tip: For even quicker access, set up a shell alias:

# Example for bash/zsh (add to your .bashrc or .zshrc)
alias bt='Budget_Tracker'

Then, you can just type bt to launch the app.

⚡ 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 (use PageUp/PageDown to jump between months in category view).
7. Change settings: Press o to open settings (change data file path, set target budget).
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

• Data File Path:
  • The path to your transactions.csv file is configurable in-app (press o for settings).
  • Default locations: - Linux: $XDG_DATA_HOME/BudgetTracker/transactions.csv (usually ~/.local/share/BudgetTracker/transactions.csv) - macOS: ~/Library/Application Support/BudgetTracker/transactions.csv - Windows: %APPDATA%\BudgetTracker\transactions.csv (e.g.,
    C:\Users\<YourUsername>\AppData\Roaming\BudgetTracker\transactions.csv)
  • Cross-Device Sync: You can set your data file path to a cloud-synced folder (iCloud, Google Drive, Dropbox, OneDrive, etc.) to automatically sync your budget data across multiple devices. Just point the data file path to a location within your cloud storage folder!
• Target Budget:
  • Set a monthly target budget in settings. This will show a budget line in summary charts.
• 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 data file location, which is in your OS's data directory (see above).

📁 Data & CSV Format

• CSV Columns: date, description, amount, transaction_type, category, subcategory
• 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: Must match the built-in set of categories and subcategories provided by the application. Custom or arbitrary categories are not currently supported.
• Import/Export: You can edit the CSV in Excel/LibreOffice or import from other tools (just match the columns and use valid categories).
• Data Safety: The app will not overwrite your CSV unless you save a transaction, close the program, or change settings.

References

Ratatui
Rust