75 lines
3.4 KiB
Markdown
75 lines
3.4 KiB
Markdown
# Common Cents
|
|
|
|
A keyboard-driven spending tracker that runs in your terminal. Built with Python and [Textual](https://textual.textualize.io/); your data is stored locally in SQLite — no cloud, no account.
|
|
|
|
## Install & run
|
|
|
|
You'll need Python 3.13 and [uv](https://docs.astral.sh/uv/).
|
|
|
|
```bash
|
|
uv sync --all-extras
|
|
uv run common-cents
|
|
```
|
|
|
|
That's it — the database is created automatically the first time you launch.
|
|
|
|
Install the app system-wide:
|
|
```bash
|
|
uv tool install .
|
|
```
|
|
|
|
## What you can do
|
|
|
|
From the main menu:
|
|
|
|
- **Spending** — record what you spent, where, and on what. Categories, merchants, and tags autocomplete as you type, and any new ones can be created on the fly. Filter by date, amount, category, merchant, tag, or a substring of the notes. Press `space` to mark rows, `*` to mark them all, then `b` to apply a single change (a new category, a tag set, a date) to the whole batch. Just deleted something by accident? `u` puts it back.
|
|
- **Metadata** — manage your categories, merchants, and tags in one place. Give a category a monthly budget and Common Cents will track how close you are to it.
|
|
- **Reports** — see where your money went, broken down by category, with progress bars and budget targets. Period selector covers This Month / Last Month / YTD / Last 12 Months, plus a custom from-month / to-month range.
|
|
- **Dashboard** — month-by-month totals for the year, a top-categories list with budget progress and how this month compares to last, and your most recent activity.
|
|
- **Import / Export** — bring in spending from a CSV (with a built-in browser, preview, and duplicate detection), or export everything back to CSV.
|
|
- **Options** — point the app at a different database file, or create a new one. Useful if you want to keep separate ledgers — household vs. side hustle, for example.
|
|
|
|
## Categories with subcategories
|
|
|
|
Categories use a `Parent:Child` convention with arbitrary depth — `Food`, `Food:Groceries`, `Food:Restaurants:Lunch`, and so on. Reports and the dashboard roll subcategories up into their parents automatically, so a budget on `Food` covers everything underneath it.
|
|
|
|
## Keyboard cheat-sheet
|
|
|
|
Most screens share these keys:
|
|
|
|
| Key | Action |
|
|
|---|---|
|
|
| `a` / `e` / `d` | Add / Edit / Delete |
|
|
| `j` `k` `g` `G` | Vim-style cursor movement |
|
|
| `escape` | Back |
|
|
| `q` | Quit (from the main menu) |
|
|
|
|
Spending screen extras: `space` toggles row selection, `*` toggles all visible rows, `b` opens bulk-edit, `u` undoes the last delete.
|
|
|
|
## Where your data lives
|
|
|
|
The database file is stored at:
|
|
|
|
- `$XDG_DATA_HOME/common-cents/common-cents.db` — or
|
|
- `~/.local/share/common-cents/common-cents.db` if `$XDG_DATA_HOME` isn't set.
|
|
|
|
To use a different file, either pick it from the in-app **Options** screen (`o` from the main menu) or pass `--db /path/to/file.db` on launch. The Options screen remembers your choice across runs.
|
|
|
|
## CSV format
|
|
|
|
Both import and export use this format. Headers are case-sensitive.
|
|
|
|
| Column | Required | Notes |
|
|
|---|---|---|
|
|
| `DATE` | yes | `YYYY-MM-DD` |
|
|
| `CENTS` | yes | Integer cents — commas allowed (`"14,901"`) |
|
|
| `CATEGORY` | yes | Use `Parent:Child` for subcategories |
|
|
| `MERCHANT` | no | May be blank |
|
|
| `NOTES` | no | Free-form |
|
|
| `TAGS` | no | Comma-separated within the field — quote it: `"work,lunch"` |
|
|
|
|
See `sample_spending.csv` for a working example.
|
|
|
|
## Development
|
|
|
|
If you want to hack on Common Cents, the architecture, dev workflow, and code conventions are documented in [`CLAUDE.md`](CLAUDE.md).
|