sparky

SparkyFitness CLI for food diary, exercise tracking, biometric check-ins, and health summaries.

Security Scan

The SKILL.md largely matches a CLI for a self-hosted fitness app, but there are inconsistencies (different homepage/source URLs) and small scope mismatches in the instructions that warrant caution before installing or trusting the binary.

Purpose & Capability

The skill claims to be a SparkyFitness CLI and the instructions focus on using a local 'sparky' binary to talk to a self-hosted server — that is coherent. However the registry metadata lists homepage https://github.com/CodeWithCJ/SparkyFitness while the SKILL.md references aronjanosch/sparky-cli (brew tap, releases). This source/homepage mismatch is unexplained and could indicate a packaging or provenance problem.

Instruction Scope

SKILL.md contains detailed CLI usage and agentic workflows that stay within the stated purpose (searching/logging food, exercise, check-ins). A few examples reference other tools (jq, git, go, sudo, brew) for install or JSON parsing, but those binaries are not declared in the skill metadata — this is a minor mismatch but not obviously malicious. The instructions do not ask the agent to read unrelated files or environment variables.

Install Mechanism

This is an instruction-only skill (no install spec) so nothing is installed by the platform itself. The SKILL.md mentions installing prebuilt binaries or building from source using GitHub releases/Go; these are standard but require the user to verify release authenticity (checksums/signatures) because binaries will be placed on disk.

Credentials

The skill declares no required environment variables or credentials. That aligns with the README-style instructions which show the CLI storing a URL/key via 'sparky config'. Be aware that the CLI itself will ask for a server URL and API key (entered by the user) — those secrets are not requested by the skill metadata but will be used by the binary at runtime.

Persistence & Privilege

always:false and model invocation is allowed (defaults). The skill does not request elevated persistence or modify other skills. It's an agent-invocable helper that runs local CLI commands — typical for this class of skill.

What to consider before installing

This skill is mostly coherent for controlling a local 'sparky' CLI, but verify provenance before installing or running any downloaded binary. Specifically: - Confirm which GitHub project/release is authoritative — SKILL.md references aronjanosch/sparky-cli while registry metadata points at CodeWithCJ; ask the publisher or check the linked repos to ensure you download the intended project. - If you install a prebuilt binary, verify checksums/signatures from the official release page and prefer building from source if you can audit it. - The examples use tools like jq, git, go, brew and sudo; ensure those tools are present and trustworthy on your system. - The CLI will ask you to set a server URL and API key (sparky config set-url / set-key). Treat those values as sensitive: only provide them to a server you control or trust. - Because this is an instruction-only skill, the platform won’t install code itself — the primary risk is running an unfamiliar binary locally. If you’re unsure, run the binary in a sandbox or inspect/build from source before use. If you can provide the exact repository you expect this skill to reference (or the publisher confirm the correct homepage), I can re-evaluate with higher confidence.

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/
  

• Pre-built binaries: https://github.com/aronjanosch/sparky-cli/releases (Linux, macOS, Windows — amd64/arm64)

Setup (once)

• sparky config set-url <url> — e.g. sparky config set-url https://sparky.example.com
• sparky config set-key <key>
• sparky config show
• sparky 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 prompting
• Create custom: sparky food create "My Meal" --calories 450 --protein 28 --carbs 42 --fat 16 — adds a custom food to your library; defaults to 100g serving; optional: --fiber, --sugar, --sodium, --saturated-fat, --brand, --serving-size, --serving-unit
• Diary: sparky food diary [-d YYYY-MM-DD]
• Delete entry: sparky food delete <uuid> — removes a diary entry
• Remove from library: sparky food remove <uuid> — purge a food from your local library (get UUID via sparky -j food search)

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; 10x80 or 10@8 also valid
• Notes: sparky exercise log "Pushups" --notes "felt strong"
• 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 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 -j food search "bad product"   # get the food's id (UUID)
sparky food remove <uuid>

Custom food (when you have nutrition facts and it's not in the DB):

# Ingredients/beverages — nutrition per 100g/ml (default)
sparky -j food create "Craft Beer" --calories 43 --protein 0.5 --carbs 3.6 --fat 0 --serving-unit ml
sparky -j food log --id <uuid> -q 330 -m dinner

# Meals (Cookidoo, Chefkoch, etc.) — nutrition per serving, specify explicitly
sparky -j food create "Lasagna" --calories 450 --protein 28 --carbs 42 --fat 16 --serving-size 1 --serving-unit serving
sparky -j food log --id <uuid> -q 1 -m dinner

Notes

• -j / --json is a root-level flag: sparky -j food diary, not sparky food diary -j
• Always verify brand in search results before logging — Open Food Facts has many products with identical names
• --barcode is the most reliable option when the product has a scannable barcode
• --pick N selects the Nth result (1-based); exact local name match bypasses --pick entirely
• In JSON mode with ambiguous results, the CLI always picks results[0] — use --id in scripts to be safe
• 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)