Nutrilog

A fast, privacy-first CLI tool for logging meals, macronutrients, and calories directly to the Google Health API (health.googleapis.com/v4) from any terminal. Syncs live with your Google Health app, Fitbit, and Pixel Watch.

                       Today's Nutrition Summary (Mon, Aug 17)
┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┓
┃ Time       ┃ Meal Type    ┃ Food                     ┃ Protein ┃ Calories ┃   Carbs ┃    Fat ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━┩
│ 12:30 PM   │ Lunch        │ Tofu Edamame Soba Bowl   │   38.5g │ 580 kcal │   54.0g │  18.0g │
│ 04:00 PM   │ Snack        │ Protein Shake            │   25.0g │ 180 kcal │    4.0g │   2.0g │
└━━━━━━━━━━━━┴━━━━━━━━━━━━━━┴━━━━━━━━━━━━━━━━━━━━━━━━━━┴━━━━━━━━━┴━━━━━━━━━━┴━━━━━━━━━┴━━━━━━━━┘
╭──────────────────────────────────────────────────────────────────────────────────────────────╮
│ Daily Total: 63.5g / 120g Protein (53%) | 760 / 2,000 kcal (38%)                             │
│ Remaining:   56.5g Protein | 1,240 kcal                                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────╯

⚡ Quickstart

1. Run Instantly with uvx (No Installation Required)

# Log a meal using intuitive shorthand syntax (in dry-run preview)
uvx --from . nutrilog "38p 18f 54c 580k Tofu Edamame Soba Bowl" --dry-run

# View today's summary & daily target progress
uvx --from . nutrilog today

# View command help
uvx --from . nutrilog --help

2. Install Globally with uv or pip

# Install globally via uv
uv tool install .

# Or via standard pip
pip install .

🏗️ Architecture & Cloud Sync

graph LR
    User["User Terminal"] --> CLI["nutrilog CLI<br/>(Typer + Rich)"]
    CLI --> Parser["Macro & Shorthand<br/>Regex Parser"]
    CLI --> Auth["OAuth 2.0 Auth Manager<br/>(PKCE / Loopback)"]
    Auth --> Keyring["Local Token Store<br/>(~/.config/nutrilog/tokens.json)"]
    CLI --> Client["Google Health Client<br/>(health.googleapis.com/v4)"]
    Client --> GoogleHealth["Google Health Platform<br/>(Pixel Watch / Fitbit / Mobile App)"]

• Zero-Friction Logging: Log any meal in $<2$ seconds directly from your command line.
• Hardware & Cloud Sync: Data writes directly to Google Health API and syncs to your Pixel Watch, Fitbit, and phone dashboard.
• Local & Private: Auth tokens are stored locally on your machine with strict 0600 permissions.

🚀 Usage & Commands

1. Shorthand Meal Logging

Macros and calorie tokens can appear anywhere in the string in any order:

# Shorthand notation (protein 'p', fat 'f', carbs 'c', calories 'k' or 'cal')
nutrilog "38p 18f 54c 580k Tofu Edamame Soba Bowl"

# Explicit units and labels
nutrilog "Grilled Salmon protein: 35g, fat: 12g, carbs: 5g, calories: 280, fiber: 2g"

# Prefix notation
nutrilog "p30 f10 c45 390cal Chicken Burrito Bowl"

# Automatic calorie calculation if calories are omitted (4*P + 4*C + 9*F)
nutrilog "30p 40c 10f Oatmeal"

Shorthand Syntax Cheat-Sheet

2. Flag-Based Logging

# Explicit flags
nutrilog log "Grilled Barramundi & Veggies" \
  --protein 36 \
  --calories 480 \
  --fat 14 \
  --carbs 12 \
  --meal lunch

# Quick macro top-up (e.g. protein shake, snack)
nutrilog quick --protein 25 --calories 180 --name "Post-Workout Protein Shake"

# Dry run (preview payload without sending)
nutrilog "35p 450k Protein Shake" --dry-run

# Output raw JSON payload
nutrilog "35p 450k Protein Shake" --json

3. Reviewing Today's Totals, History & Listing Meals

# View today's rollup vs daily targets
nutrilog today

# List recent meals with their Data Point IDs
nutrilog list --days 3

# View past week's meal history
nutrilog history --days 7 --ids

4. Deleting Meals

Delete mistakenly logged or duplicate meals using their Data Point ID:

# Delete with confirmation prompt
nutrilog delete <DATA_POINT_ID>

# Delete immediately (skip prompt)
nutrilog delete <DATA_POINT_ID> --yes
# Or alias
nutrilog rm <DATA_POINT_ID> -y

5. Configuring Daily Nutrition Targets

# Display active daily targets
nutrilog config show

# Set custom daily macro and calorie targets
nutrilog config set --calories 2200 --protein 140 --carbs 220 --fat 65

🤖 AI Agent Skill Integration

Nutrilog includes a packaged Agent Skill (SKILL.md) that allows AI coding assistants (Gemini, Claude Code, Cursor, Antigravity) to discover and run Nutrilog commands autonomously.

# Check skill status across detected AI tools
nutrilog skill status

# Install into default shared location (~/.agents/skills)
nutrilog skill install

# Install into all detected agent tool directories
nutrilog skill install --all

# Symlink instead of copying (for live package updates)
nutrilog skill install --all --link

🔑 Google Cloud Authentication (nutrilog auth)

Nutrilog connects directly to the Google Health API using OAuth 2.0.

Step 1: GCP Project Setup (Free, 1-time)

1. Create or select a project in Google Cloud Console.
2. Enable the Google Health API (APIs & Services $\rightarrow$ Library $\rightarrow$ Google Health API $\rightarrow$ Enable).
3. Under OAuth consent screen, select External, and add your email to Test Users.
4. Under Credentials, create an OAuth client ID of type Desktop App, and download the JSON credentials.

Step 2: Configure & Log In

# Option A: Import client_secrets.json file
nutrilog auth setup --file path/to/client_secrets.json

# Option B: Pass credentials via CLI flags
nutrilog auth setup --client-id "<YOUR_CLIENT_ID>" --client-secret "<YOUR_CLIENT_SECRET>"

# Option C: Use environment variables
export NUTRILOG_CLIENT_ID="<YOUR_CLIENT_ID>"
export NUTRILOG_CLIENT_SECRET="<YOUR_CLIENT_SECRET>"

# Standard local browser login
nutrilog auth login

# Remote SSH / Headless login (copy-paste flow)
nutrilog auth login --remote

# Check authentication status & token expiry
nutrilog auth status

# Sign out & clear local tokens
nutrilog auth logout

🧪 Development & Testing

Each Python module has a corresponding _test.py unit test suite alongside it:

# Set up virtual environment and install dependencies
uv venv
uv pip install -e ".[dev]"

# Run full test suite (57 tests)
uv run pytest

# Run tests with coverage report
uv run pytest --cov=nutrilog

📄 License

MIT License. See LICENSE for details.