A fast, modern, and efficient Terminal User Interface (TUI) application for tracking your personal budget, built with Rust and Ratatui.
- 🖼️ Screenshots
- ✨ Features
- 🚀 Getting Started
- ⚡ Quick Start
- ⚙️ Settings & Configuration
- 📁 Data & CSV Format
- References
Main transaction view with summary bar and help
Category summary with expandable/collapsible categories
Monthly summary with interactive chart and budget line
Click to see all monthly summary screenshots
Multi-Month Line chart
Cumulative chart with budget line
Cumulative and multi month chart
- 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).
- Categorization: Built-in, hierarchical categories and subcategories for all transactions.
- 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.
- Robust CSV Support: Flexible date parsing, easy import/export, and Excel compatibility.
- Built with Rust: Safety, speed, and reliability.
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!
- Rust (includes
cargo)
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_TrackerInstall 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.
- Launch the app:
Budget_Tracker(orbtif you set up the alias) - Add a transaction: Press
a, fill in the fields, and pressEnterto save. - Navigate: Use
↑/↓to move,eto edit,dto delete,fto filter,rto manage recurring transactions. - View summaries: Press
sfor monthly summary,cfor category summary. - Change settings: Press
oto open settings (change data file path, set target budget). - Quit: Press
qorEsc.
- Data File Path:
- The path to your
transactions.csvfile is configurable in-app (pressofor 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)
- The path to your
- Target Budget:
- Set a monthly target budget in settings. This will show a budget line in summary charts.
- Config File:
- The application's settings are saved in a
config.jsonfile, 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
- Linux:
- This is separate from the data file location, which is in your OS's data directory (see above).
- The application's settings are saved in a
- CSV Columns:
date, description, amount, transaction_type, category, subcategory - Date Format: Flexible! Accepts
YYYY-MM-DD,YYYY/MM/DD,DD/MM/YYYY, orDD-MM-YYYY. - Transaction Type:
IncomeorExpense(case-insensitive, also acceptsi/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.