48 lines
1.8 KiB
Markdown
48 lines
1.8 KiB
Markdown
# 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](SPECS.md) — the source of truth for this application.
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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/)
|
|
```
|