hledger-tui

A beautiful, keyboard-driven terminal UI for viewing and analyzing your hledger financial data. Built with Textual, this TUI provides an intuitive interface to explore your expenses, assets, and financial statistics.

Observe your finances without leaving the terminal!

✨ Features

• 📊 Expenses Analysis: Categorized expense tracking with bar charts, tag pivoting, and flexible time period navigation (weeks, months, quarters, years)
• 💰 Asset Monitoring: Track asset balances over time with interactive line charts and customizable time subdivisions (day, week, month, year)
• 📈 Statistics Dashboard: Comprehensive journal insights including account summaries, commodity tracking, and transaction metrics
• 🔍 Detailed Views: Dive into account overviews, transaction lists, and balance histories for any account
• ⌨️ Keyboard-Driven: Fast navigation with intuitive keyboard shortcuts and context-sensitive footer
• 🎨 Visual Charts: Compare data across accounts and time periods with built-in bar and line charts

📋 Requirements

• Python >= 3.10
• hledger >= 1.25 installed and available on your PATH
• LEDGER_FILE environment variable or -f/--file flag specifying your hledger journal file

💾 Installation

pip install hledger-tui

Or try it without installing (requires uv):

uvx hledger-tui

🎮 Usage

1. Set up your environment (optional if using -f flag):

   export LEDGER_FILE=/path/to/your/journal.ledger

2. Launch the TUI:

   hledger-tui

   Or with a specific ledger file:

   hledger-tui -f /path/to/your/journal.ledger

   Or alternatively:

   hledger tui

3. Web App Mode (optional):

   You can also run hledger-tui as a web application accessible via browser:

   hledger-tui --serve

   This will start a web server and provide a URL to access the TUI in your browser.

Command-Line Options

• -f, --file: Specify the path to your hledger journal file (takes precedence over LEDGER_FILE environment variable)
• --serve: Run the app in web app mode, accessible via browser
• --help: Show help message with all available options and examples

That's it! Use the keyboard shortcuts shown in the footer to navigate and explore your financial data.

⚙️ Configuration

hledger-tui can be configured using a YAML config file or environment variables. The config file is the recommended approach for most users, while environment variables are useful for temporary overrides or containerized deployments.

When the same setting is specified in multiple places, they are applied in this priority order (highest to lowest):

1. Environment variables (e.g., HLEDGER_TUI_DEPTH=3)
2. Config file (~/.config/hledger-tui/config.yaml)
3. Default values (built into the application)

Configuration File (Recommended)

Create a config file at the platform-specific location:

• Linux: ~/.config/hledger-tui/config.yaml
• macOS: ~/Library/Application Support/hledger-tui/config.yaml
• Windows: %LOCALAPPDATA%\hledger-tui\config.yaml

Example config.yaml:

# Path to hledger file:oOptional if LEDGER_FILE is set, or when using `-f`/`--file`
ledger_file: /path/to/hledger.journal
# Query defaults for filtering results in various tabs
queries:
  assets:
    - acct:assets
  expenses:
    - acct:expenses
  tags:
    - acct:expenses

# Display settings
depth: 2
commodity: ""  # Empty = use market prices; set to "$" or "€" to convert

# Period settings
period:
  unit: months          # Options: weeks, months, quarters, years
  subdivision: weekly   # Options: daily, weekly, monthly, yearly

# Extra options for HLedger commands
extra_options:
  balance: []   # Example: ["--cost", "--depth", "4"]
  register: []  # Example: ["--related", "--cost"]

Environment Variables

You can override any config file setting using environment variables. This is especially useful for CI/CD, containers, or temporary changes.

Variable	Description	Default	Example
LEDGER_FILE	Path to your hledger journal file (can be overridden with -f flag)	None	/path/to/journal.ledger
HLEDGER_TUI_QUERIES_ASSETS	JSON array of asset query filters	["acct:assets", "acct:liabilities", ...]	'["acct:assets", "acct:liabilities"]'
HLEDGER_TUI_QUERIES_EXPENSES	JSON array of expense query filters	["acct:expenses", "not:acct:financial", ...]	'["acct:expenses", "not:tag:excluded"]'
HLEDGER_TUI_QUERIES_TAGS	JSON array of tag query filters	["acct:expenses"]	'["acct:expenses", "acct:income"]'
HLEDGER_TUI_DEPTH	Default depth for account hierarchy display	2	3
HLEDGER_TUI_COMMODITY	Currency for exchange conversion (empty = use market prices)	`` (empty)	€, $, USD
HLEDGER_TUI_EXTRA_OPTIONS_BALANCE	JSON array of extra options for hledger balance command	[]	'["--cost", "--depth", "4"]'
HLEDGER_TUI_EXTRA_OPTIONS_REGISTER	JSON array of extra options for hledger register command	[]	'["--cost", "--related"]'

Note: List-type environment variables must be in JSON array format. Use single quotes to wrap the JSON string in shell:

export HLEDGER_TUI_QUERIES_EXPENSES='["acct:expenses", "not:acct:financial"]'

💱 Multi-Currency Support

hledger-tui supports journals with multiple currencies, but it can only display one at a time. Terminal plots require a single currency, because trying to display multiple at once would make bar and line charts in the TUI cluttered, or would make lines overlap.

There are three main strategies to handle multi-currency journals.

Automatic Conversion (Default)

When HLEDGER_TUI_COMMODITY is not set (default), hledger-tui uses the --market flag from HLedger to convert all amounts to one currency, based on market prices declared in your journal:

Convert to a Specific Currency

Set HLEDGER_TUI_COMMODITY to convert all amounts to a specific currency using the --exchange HLedger flag.

# Convert everything to euros
export HLEDGER_TUI_COMMODITY="€"
hledger-tui

The currency must exist in hledger commodities --declared or an error will be raised.

Filter Transactions by Currency

Add currency filters to your queries to view only transactions related to a specific commodity:

# Show only euro transactions
export HLEDGER_TUI_QUERIES_EXPENSES="acct:expenses,cur:€"
export HLEDGER_TUI_QUERIES_ASSETS="acct:assets,cur:€"
export HLEDGER_TUI_COMMODITY="€"
hledger-tui

Custom Conversion Options

You can pass additional HLedger options using the HLEDGER_TUI_EXTRA_OPTIONS_BALANCE and HLEDGER_TUI_EXTRA_OPTIONS_REGISTER environment variables. For example, to use cost basis conversion instead of market prices:

# Use cost basis for all balance commands
export HLEDGER_TUI_EXTRA_OPTIONS_BALANCE='["--cost"]'
export HLEDGER_TUI_EXTRA_OPTIONS_REGISTER='["--cost"]'
hledger-tui

These variables accept any valid HLedger command-line options and can be used to customize behavior beyond the built-in settings.

🔧 Development

Prerequisites

• uv for dependency management
• just for running common tasks

Setup

# Clone the repository
git clone https://github.com/lucabello/hledger-tui.git
cd hledger-tui

# Install development dependencies
uv sync --extra dev

Available Commands

Run just to see all available commands:

∮ just
just --list
Available recipes:
    [build]
    build  # Build the project
    clean  # Remove build artifacts, caches, and temporary files

    [dev]
    check  # Run all quality checks
    format # Format the codebase using ruff
    lint   # Lint the codebase using ruff
    run    # Run the app with hledger-tui
    test   # Run tests

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run quality checks (just check)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Please ensure your code follows the project's style guidelines and includes appropriate tests.

📝 License

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

🙏 Acknowledgments

• hledger - Plain text accounting software
• Textual - Modern TUI framework for Python
• textual-plotext - Charts for Textual

📬 Contact

Project Link: https://github.com/lucabello/hledger-tui

---

Made with ❤️ for plain text accounting enthusiasts