SparkyFitness CLI for food diary, exercise tracking, biometric check-ins, and health summaries.
Use sparky to interact with a self-hosted SparkyFitness server — log food, exercise, weight, steps, and mood.
Install
brew tap aronjanosch/tap && brew install sparky-cligit clone https://github.com/aronjanosch/sparky-cli
cd sparky-cli
go build -o sparky .
sudo mv sparky /usr/local/bin/
Setup (once)
sparky config set-url <url> — e.g. sparky config set-url https://sparky.example.comsparky config set-key <key>sparky config showsparky ping — verify connectionFood
sparky food search "chicken breast" [-l 10] — local DB first, falls back to Open Food Facts; shows Brand columnsparky food search --barcode 4061458284547 — exact product lookup, no ambiguitysparky food log "chicken breast" -m lunch -q 150 -u g [-d YYYY-MM-DD]sparky food log --barcode 4061458284547 -m lunch -q 113 -u g — most reliable, no brand guessingsparky food log --id <uuid> -m lunch -q 150 -u g — skips search, unambiguoussparky food log "Hähnchenbrust" --pick 2 — select Nth search result instead of defaulting to results[0]sparky food diary [-d YYYY-MM-DD]sparky food delete <uuid>sparky food remove <external_id> — purge a wrongly imported product from local libraryExercise
sparky exercise search "bench press" [-l 10] — local DB first, falls back to Free Exercise DBsparky exercise search --external "pushup" — bypasses local cachesparky exercise log "Pushups" [--duration 45] [--calories 400] [-d YYYY-MM-DD]sparky exercise log --id <uuid> --set 10x80@8 --set 10x80@9 — skips search, unambiguousREPS[xWEIGHT][@RPE] — e.g. 10x80@8 = 10 reps, 80 kg, RPE 8; 10x80 or 10@8 also validsparky exercise diary [-d YYYY-MM-DD]sparky exercise delete <uuid>Check-ins
sparky checkin weight 75.5 [-u kg|lbs] [-d YYYY-MM-DD]sparky checkin steps 9500 [-d YYYY-MM-DD]sparky checkin mood 8 [-n "notes"] [-d YYYY-MM-DD]sparky checkin diary [-d YYYY-MM-DD] — shows biometrics + mood togetherSummary & trends
sparky summary [-s YYYY-MM-DD] [-e YYYY-MM-DD] — nutrition/exercise/wellbeing totals (default: last 7 days)sparky trends [-n 30] — day-by-day nutrition tableAgentic workflow (always prefer --id to avoid ambiguity)
Exercise — search first, then log by ID:
# 1. Find candidates; use --external to bypass local cache if needed
sparky -j exercise search --external "pushup"
# Each result has is_local: true/false
# is_local: true → id is a UUID → use --id directly
# is_local: false → id is a source string → log by exact name to import first,
# then search again to get the UUID
# 2a. Local exercise
sparky -j exercise log --id <uuid> --set 3x10@8
# 2b. External exercise (import on first log, then switch to --id)
sparky -j exercise log "Pushups" --set 3x10
sparky -j exercise search "Pushups" # now is_local: true
sparky -j exercise log --id <uuid> --set 3x10
Food — preferred agentic workflow:
# Option A: barcode (most reliable)
sparky food log --barcode 4061458284547 -q 113 -u g -m lunch
# Option B: search → inspect brand+macros → log by --id
sparky -j food search "Hähnchenbrust"
# check brand + calories in results; pick the right one
sparky food log --id <uuid> -q 400 -u g -m dinner
# Option C: search with --pick N (when brand column shows the right one)
sparky food log "Hähnchenbrust" --pick 3 -q 400 -u g -m dinner
# Remove a bad import from local library
sparky food remove <external_id> # external_id from search results
Notes
-j / --json is a root-level flag: sparky -j food diary, not sparky food diary -j--barcode is the most reliable option when the product has a scannable barcode--pick N selects the Nth result (1-based); exact local match bypasses --pick entirely166 lbs → 75.30 kg)sparky -j food diary | jq '.[0].id'breakfast, lunch, dinner, snacks (default: snacks)