caltrack 0.1.0

A simple CLI calorie tracker

caltrack

A minimal CLI calorie tracker. Built with Python and Click.

---

Installation

From local source (recommended while developing)

# Clone or navigate to the project folder
cd caltrack

# Install in editable mode — changes to source take effect immediately
pip install -e .

From PyPI (once published)

pip install caltrack

---

Usage

# Add calories
caltrack add 1300

# Remove calories
caltrack remove 400

# Check today's total
caltrack read

# Show version
caltrack --version

# Show help
caltrack --help
caltrack add --help

---

Where data is stored

All data lives in ~/.caltrack/caltrack.db (SQLite). You can inspect it anytime:

sqlite3 ~/.caltrack/caltrack.db "SELECT * FROM calories;"

The calories table has one row per day:

id	date	calories
1	2026-04-27	1800

---

Developer Guide — Adding New Commands

1. Add your command to an existing or new file

Commands live in caltrack/commands/. Open an existing file or create a new one.

# caltrack/commands/calories.py  (or a new file like caltrack/commands/goals.py)

import click
from caltrack import storage

@click.command()
@click.argument("goal", type=int)
def set_goal(goal: int):
    """Set a daily calorie GOAL."""
    # your logic here
    click.echo(f"🎯 Daily goal set to {goal} kcal")

2. Register the command in cli.py

Open caltrack/cli.py and add two lines:

from caltrack.commands.calories import add, remove, read, set_goal  # add your import

cli.add_command(set_goal)  # register it

That's it. Run caltrack set-goal 2000 and it works.

Note: Click automatically converts underscores to hyphens in command names, so set_goal becomes caltrack set-goal.

3. Adding storage fields or new tables

New data belongs in caltrack/storage.py. To add a new table, drop a CREATE TABLE IF NOT EXISTS block into _init_db() — it runs on every connection so it's always safe:

def _init_db(conn):
    # existing calories table ...
    conn.execute("""
        CREATE TABLE IF NOT EXISTS goals (
            id      INTEGER PRIMARY KEY AUTOINCREMENT,
            date    TEXT NOT NULL UNIQUE,
            goal    INTEGER NOT NULL
        )
    """)
    conn.commit()

Then add a helper function and use it from your command:

def set_goal(goal: int):
    with _db() as conn:
        conn.execute(
            "INSERT OR REPLACE INTO goals (date, goal) VALUES (?, ?)",
            (today_key(), goal),
        )

4. Bumping the version

Edit the version field in pyproject.toml:

version = "0.2.0"

Then reinstall:

pip install -e .

5. Publishing to PyPI

# Install build tools (one-time)
pip install build twine

# Build the package
python -m build

# Upload to PyPI
twine upload dist/*

---

Project structure

caltrack/
├── pyproject.toml          # Package metadata and dependencies
├── README.md
└── caltrack/
    ├── __init__.py
    ├── cli.py              # Entry point — registers all commands
    ├── storage.py          # Read/write ~/.caltrack/data.json
    └── commands/
        ├── __init__.py
        └── calories.py     # add, remove, read commands

---

Dependencies

• Click — CLI framework