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 log "38p 18f 54c 580k Tofu Edamame Soba Bowl"

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

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

# Automatic calorie calculation if calories are omitted (4*P + 4*C + 9*F)
nutrilog log "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

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

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

3. Reviewing Today's Totals & History

# View today's total consumed nutrition & meals
nutrilog history

# View yesterday's meals and totals
nutrilog history --date yesterday

# View a specific past date
nutrilog history --date 2026-08-15

# View past 7 days of meal history
nutrilog history --days 7

# Structured JSON output
nutrilog history --json
nutrilog history --days 7 --json

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. Configuration & Timezone

# Display active configuration
nutrilog config show

# Set active timezone
nutrilog config set --timezone "Australia/Sydney"
nutrilog config set -z AEST

# Reset timezone to machine system local
nutrilog config set --timezone auto

🤖 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.

1. Instant Zero-Config Login (Default)

Nutrilog includes built-in Desktop App client credentials so you can log in immediately from any terminal:

# 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

2. Custom GCP Credentials (Optional / Advanced)

If you prefer to use your own Google Cloud Project instead of the built-in desktop app:

1. Create a project in Google Cloud Console and enable the Google Health API.
2. Under Credentials, create an OAuth client ID of type Desktop App.
3. Set your environment variables:

export NUTRILOG_CLIENT_ID="<YOUR_CLIENT_ID>"
export NUTRILOG_CLIENT_SECRET="<YOUR_CLIENT_SECRET>"

🧪 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.