bagels

bagels [--at path] [--migrate type --source path]
bagels locate {config | database}

bagels is a terminal user interface (TUI) application for tracking personal expenses and income. It stores all financial data locally in a SQLite database and presents an interactive interface built on the Textual framework.
The application is organized into two main views: Home and Manager. The Home view displays transaction records, account balances, spending insights with graphs, income/expense mode toggles, and quick-access templates. The Manager view provides tools for configuring accounts, categories with subcategories, budgets, and people for split tracking.
Key features include split transactions across multiple categories, transfers between tracked accounts and external accounts, recurring transaction templates accessible via number keys, and a jump mode system for keyboard-driven navigation between UI panels. The insights module provides spending analysis with visual graphs, estimated projections, and budget tracking against configurable limits.
Bagels supports budgeting with configurable income assessment policies, savings percentage targets, and wants-versus-needs spending ratios. Records can be filtered by label, amount, category, and time period (day, week, month, or year).
All data remains local on the user's machine, following XDG base directory conventions for file storage. The database and configuration can optionally be placed in a custom directory using the --at flag.

--at path

Specify a custom directory for storing the database and configuration files. Defaults to XDG base directories.

Run a data migration from another application. Currently supports actualbudget.

Path to the source database file when using --migrate.

Display the path to the configuration YAML file.

Display the path to the SQLite database file.

Configuration is stored in a config.yaml file at the XDG config directory (typically ~/.config/bagels/config.yaml). The file is auto-generated on first run and uses YAML format.
defaults.period

Default time period for the home view. Options: day, week, month, year. Default: week.

First day of the week (0 = Monday, 6 = Sunday). Default: 6.

Date display format string. Default: %d/%m.

Number of decimal places for amounts. Default: 2.

Graph plot marker style. Options: braille, fhd, hd, dot. Default: braille.

Color theme. Available themes include tokyo-night, nord, gruvbox, catppuccin-mocha, dracula, galaxy, alpine, cobalt, hacker, flexoki, and dark. Default: tokyo-night.

Check PyPI for new versions on startup. Default: true.

Budgeting parameters including income assessment policy, savings percentage, and wants spending ratio.

All keyboard shortcuts are fully configurable under the hotkeys section.

Customizable display symbols for lines, split indicators, category markers, and amount signs.

a

Add a new record, account, or category (context-dependent)

Edit selected item

Delete selected item

Toggle jump mode for quick navigation between UI panels

Cycle between Home and Manager tabs

Create a new transfer between accounts

Open budgets view

Toggle transaction splits display

Display records by date / by person

Open advanced filter

Cycle time offset type (day, week, month, year)

Toggle between income and expense mode

Select previous / next account

Toggle account-based record filtering

Navigate to previous / next time period

Quick-apply a transaction template by its number

Add a new split to a record (in record modal)

Delete the last split (in record modal)

Submit and save as template (in record modal)

Quit the application

Requires Python 3.13 or later. For best rendering, use a modern terminal emulator; macOS users should consider Ghostty, and Windows users should use Windows Terminal.
The --migrate option currently only supports importing from Actual Budget. The --source flag is required when using migration.
All data is stored locally with no cloud synchronization. Backup the database file (located via bagels locate database) to prevent data loss.

Bagels was created by Jax (EnhancedJax) and first released in 2024 as an open-source terminal expense tracker. The project is built on the Textual TUI framework and was inspired by the Posting terminal application. It gained popularity in the terminal tooling community, accumulating over 2,700 GitHub stars. The project is licensed under GPL-3.0.

ledger(1), hledger(1), awk(1)