- name
- sparky
- description
- SparkyFitness CLI for food diary, exercise tracking, biometric check-ins, and health summaries.
- homepage
- https://github.com/CodeWithCJ/SparkyFitness
- metadata
- {"clawdbot":{"emoji":"🏃","requires":{"bins":["sparky"]}}}
sparky
Use sparky to interact with a self-hosted SparkyFitness server — log food, exercise, weight, steps, and mood.
Install
- Homebrew (macOS/Linux):
brew tap aronjanosch/tap && brew install sparky-cli - Build from source (requires Go 1.21+):
git 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 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:
sparky food log "chicken breast" -m lunch -q 150 -u g [-d YYYY-MM-DD] - 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:
sparky food diary [-d YYYY-MM-DD] - Delete entry:
sparky food delete <uuid> - 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:
sparky exercise log "Pushups" [--duration 45] [--calories 400] [-d YYYY-MM-DD] - 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;10x80or10@8also valid - Diary:
sparky exercise diary [-d YYYY-MM-DD] - Delete:
sparky exercise delete <uuid>
Check-ins
- Weight:
sparky checkin weight 75.5 [-u kg|lbs] [-d YYYY-MM-DD] - Steps:
sparky checkin steps 9500 [-d YYYY-MM-DD] - Mood:
sparky checkin mood 8 [-n "notes"] [-d YYYY-MM-DD] - 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)sparky trends [-n 30]— day-by-day nutrition table
Agentic 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 3x10Food — 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 resultsNotes
-j/--jsonis a root-level flag:sparky -j food diary, notsparky food diary -j- Always verify brand in search results before logging — Open Food Facts has many products with identical names
--barcodeis the most reliable option when the product has a scannable barcode--pick Nselects the Nth result (1-based); exact local match bypasses--pickentirely- 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:
sparky -j food diary | jq '.[0].id' - Meal options:
breakfast,lunch,dinner,snacks(default:snacks)