QuickLedger

QuickLedger is a fast, intuitive, CLI-first expense tracker built with Python and Typer. Track your daily spending using natural language, export summaries, and optionally extend via a lightweight FastAPI backend.

---

Features

• Add expenses via command line (ledger add)
• View by day, week, or custom date range
• Natural language support (e.g. Bought food for 2000)
• Summary and basic analytics
• Edit and delete entries
• Export to CSV
• Simple REST API (no auth yet)
• JSON-based storage (easy to inspect and backup)
• Pythonic, Typer-powered CLI with FastAPI backend

---

Installation

You can use either pip (recommended for end users) or poetry (recommended for contributors or development setup).

✅ Option 1: Using pip (PyPI)

pip install quickledger

Then you can use it directly via:

ledger

🛠️ Option 2: Using Poetry (Development)

1. Clone the repo:

git clone https://github.com/chinyereunamba/ledger.git
cd ledger

2. Install dependencies:

poetry install

3. Run the CLI:

poetry run ledger

---

CLI Commands

➕ Add Expense

ledger add

Supports natural language:

ledger say "Bought food for 1500"

📅 View Expenses

ledger view --date 2025-07-25
ledger view --week
ledger view --range 2025-07-01 2025-07-25

✏️ Edit or Delete

ledger edit --date 2025-07-24 --index 1
ledger delete --date 2025-07-24 --index 1

📤 Export

ledger export --path my_expenses.csv

---

🌐 API

Start the FastAPI server from the api/ folder:

uvicorn main:app --reload

Endpoints

Method	Endpoint	Description
GET	/expenses/	Get all expenses
POST	/expenses/	Add a new expense
GET	/expenses/{date}	Get expenses for a date
DELETE	/expenses/{date}	Delete all expenses for a date
GET	/summary/	Get total summary
GET	/summary/{date}	Summary for a specific date
GET	/summary/week	Past 7 days summary
GET	/summary/range	Summary for a date range

⚠️ No authentication yet — intended for local/private use.

---

🧠 NLP Support

You can input expenses like:

ledger say "Paid for transport 700"

This is automatically parsed as:

• Expense: transport
• Amount: 700
• Date: today (default)

---

📂 Project Structure

ledger/
├── ledger/               # CLI logic & utilities
│   ├── ledger.py
│   ├── utils.py
│   └── constants.py
├── api/                  # FastAPI backend
│   ├── main.py
│   ├── routes/
│   │   └── __init__.py
│   └── models.py
├── ledger.json           # Local JSON storage
├── main.py
├── pyproject.toml        # Poetry config
├── README.md             # ← You're here
└── LICENSE

---

📦 PyPI

Coming soon to PyPI for easier installation via pip.

---

📃 License

MIT © 2025 Chinyere Unamba