Core Python Expense Tracker CLI

A command-line expense tracker that records categorized expenses, stores them in JSON, and summarizes monthly spending.

Stack

• Python 3.12
• Standard library only
• Local JSON file storage
• unittest for automated tests

Setup

1. Create the virtual environment:

   python -m venv venv

2. Activate it:

   venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

   This project currently uses only the Python standard library, so there are no third-party packages to install.

Environment Variables

See .env.example.

• EXPENSE_TRACKER_DATA_FILE: Optional path for the JSON data file. If omitted, the app uses data/expenses.json.

Running Locally

Open the guided menu:

python -m src.expense_tracker.main

The guided menu asks questions for adding, listing, editing, deleting, reporting, and exporting expenses. You can also open it explicitly:

python -m src.expense_tracker.main interactive

Add an expense directly:

python -m src.expense_tracker.main add --amount 12.50 --category Food --description "Lunch" --date 2026-06-01

View the current month summary:

python -m src.expense_tracker.main summary

List saved expenses:

python -m src.expense_tracker.main list

List expenses for a specific month:

python -m src.expense_tracker.main list --month 2026-06

Delete an expense by ID:

python -m src.expense_tracker.main delete --id expense-id-from-list

Edit an expense by ID:

python -m src.expense_tracker.main edit --id expense-id-from-list --amount 14.25 --category Food --description "Client lunch" --date 2026-06-02

Export expenses to CSV:

python -m src.expense_tracker.main export --output exports/expenses.csv

Export a specific month to CSV:

python -m src.expense_tracker.main export --output exports/june-2026.csv --month 2026-06

View a specific month:

python -m src.expense_tracker.main summary --month 2026-06

View monthly spending insights:

python -m src.expense_tracker.main report --month 2026-06

Set a monthly category budget:

python -m src.expense_tracker.main budget set --month 2026-06 --category Food --amount 300.00

List monthly budgets:

python -m src.expense_tracker.main budget list --month 2026-06

Create a recurring expense template:

python -m src.expense_tracker.main recurring add --amount 1200.00 --category Housing --description "Rent" --day 1

Apply recurring templates to a month:

python -m src.expense_tracker.main recurring apply --month 2026-06

Recurring template application skips matching expenses that already exist for the selected month.

The root launcher also starts the app:

python expense_tracker.py

Run tests:

python -m unittest discover

Screenshots

Guided menu:

Expense Tracker CLI
Answer the prompts to manage expenses without memorizing commands.

1. Add expense
2. List expenses
3. Edit expense
4. Delete expense
5. View monthly summary
6. View monthly report
7. Export CSV
8. Set budget
9. List budgets
10. Add recurring template
11. List recurring templates
12. Apply recurring templates
13. Exit

Monthly report with budget comparison:

Report for 2026-06
Total spent: $1275.00
Transactions: 2
Average expense: $637.50
Top category: Housing
Category breakdown:
- Food: $75.00
- Housing: $1200.00
Budget comparison:
- Food: budget $300.00, spent $75.00, remaining $225.00
- Housing: budget $1200.00, spent $1200.00, remaining $0.00

Recurring template workflow:

Recurring templates
template-id | day 1 | Housing | $1200.00 | Rent

Applied 1 recurring template(s) to 2026-06.
Applied 0 recurring template(s) to 2026-06.

CSV export:

Exported 2 expense record(s) to exports/june-2026.csv.

Deployed

Not deployed. This is a local CLI portfolio project.

Changelog

• e29dd74 - Added README screenshots section with terminal examples.
• 1430e21 - Added duplicate protection when applying recurring templates.
• cee2c8f - Added recurring expense templates for rent, subscriptions, and other repeat expenses.
• eae2c7c - Added monthly budget tracking and budget comparison in reports.
• 57c26d2 - Expanded the guided questionnaire menu for new users.
• a0dee22 - Added monthly spending report with average expense and top category.
• 581b0f0 - Added expense editing by ID.
• 2e7f40b - Added CSV export for spreadsheet workflows.
• ab3607f - Added expense deletion by ID.
• 181f032 - Added expense listing with optional month filtering.
• 587ffd2 - Added explicit expense date support.
• 3cc8cc6 - Built the initial modular expense tracker CLI.

Architecture Notes

I built this as a clean, maintainable version of the original single-file expense tracker. The launcher starts the app, the command layer handles terminal commands, the interactive menu handles guided prompts, validators clean user input, the model defines one expense, storage reads and writes JSON, and the summary service calculates monthly totals. That separation makes each piece easier to understand, test, and improve without turning the app into one large script.

The app supports both a questionnaire-style menu and direct command-line commands. That matters for a portfolio piece because it shows the program can support guided user workflows and predictable automation. Expenses are saved as JSON so the data format stays easy to inspect, and the code uses Decimal for money instead of floats to avoid rounding surprises.

Notes

• The JSON data file is ignored by Git because personal spending data should not be committed.
• The budget data file is ignored by Git because personal financial targets should not be committed.
• The recurring template data file is ignored by Git because personal bill patterns should not be committed.
• Categories are centralized in src/expense_tracker/utils/validators.py.
• Storage writes through a temporary file before replacing the JSON file, reducing the chance of corrupting saved data.
• Future improvements could include import from CSV, richer report formatting, or a small text-based dashboard.