lunchtui

Table of Contents

• Features
• Installation
• Usage
• CLI Commands
• Configuration
• Screenshots
• Contributing
• License
• Acknowledgments

Features

• Account Balances - View all your account balances at a glance
• Transaction Management - Browse and search through your transactions
• Recurring Expenses - Monitor your subscription and recurring payments
• Budget Tracking - Monitor your spending against budgets with real-time progress
• Categorization - Easily categorize transactions with intuitive interface
• Transaction Status - Mark transactions as cleared or uncleared

Installation

Option 1: Homebrew (macOS)

brew tap rshep3087/lunchtui
brew install --cask lunchtui

Option 2: Download Pre-built Binary

Download the latest release from the releases page and extract the binary to a location in your PATH.

Option 3: Install with Go

go install github.com/Rshep3087/lunchtui@latest

Option 4: Build from Source

git clone https://github.com/Rshep3087/lunchtui.git
cd lunchtui
go build -o lunchtui

Usage

Quick Start

# Set your API token
export LUNCHMONEY_API_TOKEN="your-api-token-here"

# Launch lunchtui
lunchtui

Navigation

Once lunchtui is running, use these keyboard shortcuts to navigate:

Examples

# Use a specific API token
lunchtui --token="your-token-here"

# Show debits as negative values
lunchtui --debits-as-negative

# Use a custom configuration file
lunchtui --config /path/to/my-config.toml

# Enable debug logging
lunchtui --debug

# Combine options (flags override config file)
lunchtui --token="your-token" --debits-as-negative --debug

CLI Commands

In addition to the interactive TUI interface, lunchtui provides powerful CLI commands for automation and scripting.

Available Commands

Transaction Management

Insert a new transaction directly from the command line.

Usage:

lunchtui transaction insert --payee "Coffee Shop" --amount "4.50" [options]

# Basic transaction
lunchtui transaction insert --payee "Grocery Store" --amount "45.67"

# Transaction with category and notes
lunchtui transaction insert --payee "Gas Station" --amount "35.00" --category 123 --notes "Weekly fill-up"

# Income transaction (negative amount)
lunchtui transaction insert --payee "Freelance Work" --amount "-500.00" --status cleared

# Transaction with tags
lunchtui transaction insert --payee "Restaurant" --amount "25.50" --tags 1 --tags 2

Categories Management

List all categories with their IDs and details.

Usage:

# List categories in table format
lunchtui categories list

# List categories in JSON format
lunchtui categories list --output json

Accounts Management

List all accounts (both assets and Plaid accounts) with their IDs and details.

Usage:

lunchtui accounts list [options]

Global Flags

All commands support these global flags:

• --token - Lunch Money API token (can use LUNCHMONEY_API_TOKEN env var)
• --debits-as-negative - Show debits as negative numbers
• --debug - Enable debug logging

Getting Help

Use the --help flag with any command to see detailed usage information:

# General help
lunchtui --help

# Command-specific help
lunchtui transaction --help
lunchtui categories list --help

Configuration

Configuration File Support

Lunchtui supports TOML configuration files to set default values for commonly used options. This eliminates the need to specify flags repeatedly.

Configuration file locations (in order of precedence):

• Current directory: lunchtui.toml
• User config: ~/.config/lunchtui/config.toml
• User home: ~/.lunchtui.toml
• System-wide: /etc/lunchtui/config.toml

Example configuration file:

# lunchtui.toml
debug = true
token = "your-api-token-here"
debits_as_negative = false

You can also specify a custom config file with --config path/to/config.toml.

For complete configuration documentation, see CONFIG.md

API Token Setup

1. Log into your Lunch Money account
2. Navigate to Settings → Developers
3. Create a new API token
4. Set the token via configuration file or environment variable:

# Option 1: Configuration file
echo 'token = "your-api-token-here"' > lunchtui.toml

# Option 2: Environment variable - will override setting in lunchtui.toml
export LUNCHMONEY_API_TOKEN="your-api-token-here"

# Option 3: Command-line flag - will override config file and env var settings
lunchtui --token="your-api-token-here" user

API Base URL Configuration (Optional)

By default, lunchtui uses the Lunch Money API endpoint configured in the library. If you need to use a different API endpoint (e.g., for testing or custom deployments), you can configure it:

# Option 1: Configuration file
echo 'api_base_url = "https://api.lunchmoney.dev"' >> lunchtui.toml

# Option 2: Environment variable - will override the setting in lunchtui.toml
export LUNCHMONEY_API_BASE_URL="https://api.lunchmoney.dev"

# Option 3: Command-line flag - will override config file and env var settings
lunchtui --api-base-url="https://api.lunchmoney.dev" user

Screenshots

Budget Tracking

Monitor your spending against budgets with detailed progress tracking

Key Features:

• Real-time Progress - See how much you've spent vs. your budget for each category
• Multi-currency Support - View budgets in their original currency
• Transaction Count - Track the number of transactions per budget category
• Period Navigation - Switch between different time periods to view historical budget data
• Category Integration - Budgets are automatically linked to your transaction categories

Budget View Information:

• Budget amount and currency
• Amount spent to date
• Number of transactions in the category
• Easy navigation between time periods

Recurring Expenses View

Easily track and manage your recurring expenses and subscriptions

Transaction Browser

Browse through your transactions with powerful filtering and search capabilities

Transaction Categorization

Quickly categorize transactions with an intuitive interface

Contributing

Contributions are welcome!

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Lunch Money - For providing an excellent personal finance platform
• Bubble Tea - For the amazing TUI framework
• Charm - For the beautiful terminal UI components

Color Customization

You can customize the colors used throughout the TUI application by adding a [colors] section to your configuration file. Colors can be specified using either hex values (e.g., "#ff0000") or ANSI color codes (e.g., "21").

Available Color Options

Example Configuration

[colors]
primary = "21"              # ANSI blue instead of default yellow
error = "#ff5555"          # Slightly lighter red  
success = "28"             # ANSI green
warning = "#ff8800"        # Orange instead of red
muted = "240"              # ANSI dark gray
income = "#00cc00"         # Darker green
expense = "#cc0000"        # Darker red
border = "27"              # ANSI bright blue
background = "54"          # ANSI purple
text = "#ffffff"           # Pure white
secondary_text = "245"     # ANSI light gray

Color Formats

• Hex colors: Use standard hex notation like "#ff0000" for red
• ANSI colors: Use ANSI color codes like "21" for bright blue
  • Standard colors: 0-7 (black, red, green, yellow, blue, magenta, cyan, white)
  • Bright colors: 8-15
  • Extended colors: 16-255

The application will fall back to default colors if any color value is invalid or missing.