Skip to content

README.md

Latest commit

 

History

History
190 lines (142 loc) · 10.3 KB

README.md

File metadata and controls

190 lines (142 loc) · 10.3 KB

Budget Tracker TUI

Budget Tracker Logo

Built With Ratatui

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

📚 Table of Contents

🖼️ Screenshots

main_view
Main transaction view with summary bar and help

cat_summary
Category summary with expandable/collapsible categories
summary_view
Monthly summary with interactive chart and budget line

budget_view
Budget View with yearly, monthly, and categorically focused data

SEE MORE SCREENSHOTS HERE <>

Click to see all monthly summary screenshots

summary_multi
Multi-Month Line chart

summary_cumu
Cumulative chart with budget line

summary_cum_multi
Cumulative and multi month chart

help_menu
Options Menu with Help / Keybindings Menu Open

fuzzy_find
Category/Sub-Category Fuzzy Search Enabled view

category_catalog
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 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: 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 are stored in a configurable CSV file, categories are stored in a local SQLite database, and app preferences 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

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.

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 (change the transactions CSV path, SQLite database path, target budget, and manage categories).
  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!
  • Database Path:
    • The category catalog is stored in a SQLite database file, configurable in-app from Settings.
    • By default, the database file is named budget.db and is placed alongside your current transactions CSV file.
    • On first run with a new database, the app seeds it with the default category catalog.
  • 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 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: Transaction rows should reference categories that exist in the SQLite category catalog. You can manage that catalog in-app from Settings.
  • Import/Export: You can edit the transaction CSV in Excel/LibreOffice or import from other tools (just match the columns and use valid categories). SQLite support currently backs category data; transaction storage remains CSV for now.
  • Data Safety: The app will not overwrite your transaction CSV unless you save a transaction, close the program, or change settings. Category edits are written to the SQLite database.

References

Ratatui Rust
⚡