sparky

Use sparky to interact with a self-hosted SparkyFitness server — log food, exercise, weight, steps, and mood.

Install

• - Homebrew (macOS/Linux): INLINECODE1
• Build from source (requires Go 1.21+):

Setup (once)

• - sparky config set-url <url> — e.g. INLINECODE3
• INLINECODE4
• INLINECODE5
• INLINECODE6 — verify connection

Food

• - Search: sparky food search "chicken breast" [-l 10] — local DB first, falls back to Open Food Facts; shows Brand column
• Search by barcode: sparky food search --barcode 4061458284547 — exact product lookup, no ambiguity
• Log by name: INLINECODE9
• Log by barcode: sparky food log --barcode 4061458284547 -m lunch -q 113 -u g — most reliable, no brand guessing
• Log by ID: sparky food log --id <uuid> -m lunch -q 150 -u g — skips search, unambiguous
• Pick result: sparky food log "Hähnchenbrust" --pick 2 — select Nth search result instead of defaulting to results[0]
• Diary: INLINECODE13
• Delete entry: INLINECODE14
• Remove from library: sparky food remove <external_id> — purge a wrongly imported product from local library

Exercise

• - Search: sparky exercise search "bench press" [-l 10] — local DB first, falls back to Free Exercise DB
• Search external only: sparky exercise search --external "pushup" — bypasses local cache
• Log by name: INLINECODE18
• Log by ID: sparky exercise log --id <uuid> --set 10x80@8 --set 10x80@9 — skips search, unambiguous
• Sets format: REPS[xWEIGHT][@RPE] — e.g. 10x80@8 = 10 reps, 80 kg, RPE 8; 10x80 or 10@8 also valid
• Diary: INLINECODE24
• Delete: INLINECODE25

Check-ins

• - Weight: INLINECODE26
• Steps: INLINECODE27
• Mood: INLINECODE28
• Diary: sparky checkin diary [-d YYYY-MM-DD] — shows biometrics + mood together

Summary & trends

• - sparky summary [-s YYYY-MM-DD] [-e YYYY-MM-DD] — nutrition/exercise/wellbeing totals (default: last 7 days)
• INLINECODE31 — day-by-day nutrition table

Agentic workflow (always prefer --id to avoid ambiguity)

Exercise — search first, then log by ID:
CODEBLOCK1

Food — preferred agentic workflow:
CODEBLOCK2

Notes

• - -j / --json is a root-level flag: sparky -j food diary, not INLINECODE35
• Always verify brand in search results before logging — Open Food Facts has many products with identical names
• INLINECODE36 is the most reliable option when the product has a scannable barcode
• INLINECODE37 selects the Nth result (1-based); exact local match bypasses --pick entirely
• Both search commands fall back to online providers automatically; matches are added to your library on first log
• Weight is stored in kg; lbs are auto-converted (166 lbs → 75.30 kg)
• Full UUIDs for delete: INLINECODE40
• Meal options: breakfast, lunch, dinner, snacks (default: snacks)