Ledgerly/README.md

Ledgerly

A tiny, zero-dependency personal finance tracker for the command line. Record income and expense transactions, set a monthly budget per expense category, and report where the money went. All data lives in one SQLite file; the runtime needs nothing but the Python standard library.

See SPECS.md — the source of truth for this application.

Quick start

python -m ledgerly add 45.20 --category Groceries --note "weekly shop"
python -m ledgerly add 3000 --category Salary --date 2026-10-01
python -m ledgerly budget-set Rent 1500
python -m ledgerly list
python -m ledgerly budget-show --month 2026-10
python -m ledgerly report --month 2026-10

Data is stored in ~/.ledgerly/ledgerly.db (override with --db PATH, a global option that goes before the subcommand).

Commands

Command	Purpose
add AMOUNT --category NAME [--date YYYY-MM-DD] [--note TEXT]	record a transaction
list [--month YYYY-MM] [--category NAME] [--all]	list transactions (newest first)
delete ID	delete a transaction
categories	list categories
category-add NAME --type income|expense	add a category
category-del NAME	delete an unused category
budget-set CATEGORY AMOUNT	set/replace the monthly budget
budget-del CATEGORY	remove a budget
budget-show [--month YYYY-MM]	budgets vs. spending (flags OVER, surfaces unbudgeted spending)
report [--month YYYY-MM]	income / expenses / net + category breakdown

Exit codes: 0 success · 1 domain error · 2 usage error.

Development

python -m pytest                          # run the test suite
python -m coverage run -m pytest          # run with coverage
python -m coverage report                 # report (gate: 95% of ledgerly/)