Garmin Connect CLI

Garmin Connect CLI for activities, health, body composition, workouts, devices, gear, goals, and more.

Security Scan

The skill's requirements and instructions are consistent with a Garmin Connect command-line client: it installs a gccli binary via a Homebrew tap and instructs the agent to run that binary and authenticate with Garmin SSO to access personal fitness data.

Purpose & Capability

Name/description match the requested artifact: the skill requires the gccli binary and documents commands for Garmin Connect operations (activities, health, workouts, etc.). Requesting the gccli binary and offering a Homebrew formula or build-from-source URL is proportional to the described purpose.

Instruction Scope

SKILL.md instructs the agent to run gccli commands (auth login/status/token/export, list/download/upload activities, health queries). This is within scope. Note: the docs explicitly describe exporting auth tokens and headless login (MFA) which, while legitimate for scripting, means a running agent could read or export your Garmin auth tokens and health data — sensitive but expected for this tool.

Install Mechanism

Install spec uses a Homebrew formula (bpauli/tap/gccli). Homebrew taps are a normal distribution mechanism for CLI tools. The formula references the same upstream project (GitHub repo listed in homepage), which is proportionate. No high-risk download-from-unknown-URL patterns are present.

Credentials

The skill declares no required environment variables or credentials beyond using gccli's own auth flow. That aligns with the documented behavior (gccli uses Garmin SSO managed interactively or via exported tokens). No unrelated secrets or system config paths are requested.

Persistence & Privilege

The skill is not always-enabled and does not request elevated persistence. It is user-invocable and allows autonomous invocation (platform default), which is expected for skills and not by itself a red flag.

Assessment

This skill appears to be what it says: a wrapper around the gccli command-line tool. Before installing, verify you trust the Homebrew tap owner (bpauli) and the upstream GitHub repo. Be aware that gccli requires Garmin SSO credentials and can export auth tokens and personal health/activity data — avoid running it on untrusted systems or sharing exported tokens. If you want to limit risk, install gccli locally yourself and only grant the skill access when needed; consider disabling autonomous invocation if you do not want the agent to run the CLI without explicit consent.

gccli

Use gccli for Garmin Connect health, fitness, and activity data. Requires Garmin SSO authentication.

Setup (once)

• gccli auth login [e-mail] (opens browser for Garmin SSO)
• Headless: gccli auth login [e-mail] --headless (with --mfa-code <code> for MFA)
• Set default account: export GCCLI_ACCOUNT=[e-mail]
• Verify: gccli auth status

Output

• Default: human-friendly tables. Use --json / -j for JSON, --plain for TSV.
• Data goes to stdout, messages/errors to stderr.
• Always use --json when parsing output programmatically.

Date shortcuts

• today, yesterday, 3d (N days ago), YYYY-MM-DD (specific date).
• Use --start/--end flags for date ranges.

Common commands

• Auth status: gccli auth status
• Auth token (for scripting): gccli auth token
• Export credentials: gccli auth export (pipe to file or copy to another machine)
• Import credentials: gccli auth import <token> (from auth export output)
• Remove credentials: gccli auth remove
• List activities: gccli activities list --limit 20
• List activities by type: gccli activities list --type running
• Activity count: gccli activities count
• Search activities: gccli activities search --start-date 2024-01-01 --end-date 2024-12-31
• Activity summary: gccli activity summary <id>
• Activity details: gccli activity details <id>
• Activity splits: gccli activity splits <id>
• Activity weather: gccli activity weather <id>
• Activity HR zones: gccli activity hr-zones <id>
• Activity power zones: gccli activity power-zones <id>
• Activity exercise sets (show): gccli activity exercise-sets <id>
• Set exercise sets: gccli activity exercise-sets set <id> -e "CATEGORY/NAME:reps@weightkg[:dSECS][:rSECS]" [-e ...]
• Activity gear: gccli activity gear <id>
• Download activity (FIT): gccli activity download <id> --format fit
• Download activity (GPX): gccli activity download <id> --format gpx --output track.gpx
• Upload activity: gccli activity upload ./activity.fit
• Create manual activity: gccli activity create --name "Morning Run" --type running --date 2024-06-15T07:30:00 --duration 1800 --distance 5000
• Rename activity: gccli activity rename <id> "New Name"
• Retype activity: gccli activity retype <id> running
• Delete activity: gccli activity delete <id> --force
• Health summary: gccli health summary [date]
• Steps chart: gccli health steps [date]
• Daily steps range: gccli health steps daily --start 2024-01-01 --end 2024-01-31
• Weekly steps: gccli health steps weekly --weeks 4
• Heart rate: gccli health hr [date]
• Resting HR: gccli health rhr [date]
• Floors climbed: gccli health floors [date]
• Sleep: gccli health sleep [date]
• Respiration: gccli health respiration [date]
• SpO2: gccli health spo2 [date]
• HRV: gccli health hrv [date]
• Stress: gccli health stress [date]
• Weekly stress: gccli health stress weekly --weeks 4
• Body battery: gccli health body-battery [date]
• Body battery range: gccli health body-battery range --start 2024-01-01 --end 2024-01-07
• Training readiness: gccli health training-readiness [date]
• Training status: gccli health training-status [date]
• Fitness age: gccli health fitness-age [date]
• VO2max / max metrics: gccli health max-metrics [date]
• Lactate threshold: gccli health lactate-threshold
• Cycling FTP: gccli health cycling-ftp
• Race predictions: gccli health race-predictions [date]
• Race predictions range: gccli health race-predictions range --start 2024-01-01 --end 2024-06-30
• Endurance score: gccli health endurance-score [date]
• Hill score: gccli health hill-score [date]
• Intensity minutes: gccli health intensity-minutes [date]
• Weekly intensity minutes: gccli health intensity-minutes weekly --start 2024-01-01 --end 2024-01-31
• Wellness events: gccli health events [date]
• Body composition: gccli body composition [date]
• Body composition range: gccli body composition --start 2024-01-01 --end 2024-01-31
• Weigh-ins: gccli body weigh-ins --start 2024-01-01 --end 2024-01-31
• Add weight: gccli body add-weight 75.5 --unit kg
• Add composition: gccli body add-composition 75.5 --body-fat 15.2 --muscle-mass 35.0
• Blood pressure: gccli body blood-pressure --start 2024-01-01 --end 2024-01-31
• Add blood pressure: gccli body add-blood-pressure --systolic 120 --diastolic 80 --pulse 65
• List workouts: gccli workouts list --limit 20
• Workout detail: gccli workouts detail <id>
• Download workout (FIT): gccli workouts download <id> --output workout.fit
• Upload workout (JSON): gccli workouts upload ./workout.json
• Schedule workout: gccli workouts schedule add <id> 2024-06-20
• List scheduled workouts: gccli workouts schedule list 2024-06-20
• List scheduled workouts in range: gccli workouts schedule list --start 2024-06-01 --end 2024-06-30
• Remove scheduled workout: gccli workouts schedule remove <schedule-id> (use --force to skip confirmation)
• Delete workout: gccli workouts delete <id>
• Create running workout with pace: gccli workouts create "Easy Run" --type run --step "warmup:5m" --step "run:20m@pace:5:00-5:30" --step "cooldown:5m"
• Create workout with HR targets: gccli workouts create "HR Run" --type run --step "warmup:10m" --step "run:20m@hr:140-160" --step "cooldown:10m"
• Create cycling workout with power: gccli workouts create "FTP Intervals" --type bike --step "warmup:10m" --step "run:5m@power:250-280" --step "recovery:3m" --step "run:5m@power:250-280" --step "cooldown:10m"
• List courses: gccli courses list
• Favorite courses: gccli courses favorites
• Course detail: gccli courses detail <id>
• Import course from GPX (default: cycling, private): gccli courses import route.gpx
• Import course with name: gccli courses import route.gpx --name "Sunday Ride"
• Import course with type: gccli courses import route.gpx --type gravel_cycling
• Import public course: gccli courses import route.gpx --privacy 1
• Send course to device: gccli courses send <course-id> <device-id>
• Delete course: gccli courses delete <id> (use -f to skip confirmation)
• List devices: gccli devices list
• Device settings: gccli devices settings <device-id>
• Primary device: gccli devices primary
• Last used device: gccli devices last-used
• Device alarms: gccli devices alarms
• Solar data: gccli devices solar <device-id> --start 2024-06-01 --end 2024-06-30
• List gear: gccli gear list
• Gear stats: gccli gear stats <uuid>
• Gear activities: gccli gear activities <uuid> --limit 20
• Gear defaults: gccli gear defaults
• Link gear: gccli gear link <uuid> <activity-id>
• Unlink gear: gccli gear unlink <uuid> <activity-id>
• Goals: gccli goals list --status active
• Earned badges: gccli badges earned
• Available badges: gccli badges available
• In-progress badges: gccli badges in-progress
• Challenges: gccli challenges list
• Badge challenges: gccli challenges badge
• Personal records: gccli records
• Profile: gccli profile
• Profile settings: gccli profile settings
• Hydration: gccli hydration [date]
• Log water: gccli hydration add 500
• Nutrition food log: gccli nutrition [date]
• Nutrition meals: gccli nutrition meals [date]
• Nutrition settings: gccli nutrition settings [date]
• Training plans: gccli training plans --locale en
• Training plan detail: gccli training plan <id>
• Menstrual cycle: gccli wellness menstrual-cycle --start-date 2024-01-01 --end-date 2024-03-31
• Pregnancy summary: gccli wellness pregnancy-summary
• List events: gccli events list
• List events from date: gccli events list --start 2024-06-01 --limit 50
• Add event: gccli events add --name "Berlin Marathon" --date 2026-09-27 --type running --race --location "Berlin, Germany" --distance 42.195km --time 09:15 --timezone Europe/Berlin
• Add event with goal and training priority: gccli events add --name "Spring 10K" --date 2026-05-10 --type running --race --distance 10km --goal 40m --training
• Delete event: gccli events delete <id> (use -f to skip confirmation)
• Reload data: gccli reload [date]
• List exercise categories: gccli exercises list
• List exercises in category: gccli exercises list -c BENCH_PRESS
• List exercises (JSON): gccli exercises list --json

Strength training workflow (LLM-assisted exercise matching)

When a user wants to log a strength training activity with exercises described in free text (e.g. "Bench Press 3x12@20kg, Lat Pulldowns 3x12@41kg"), follow this workflow:

1. Fetch the Garmin exercise catalog: gccli exercises list --json
2. Map each user-described exercise to the best matching Garmin CATEGORY/EXERCISE_NAME pair. The catalog uses SCREAMING_SNAKE_CASE (e.g. BENCH_PRESS/BARBELL_BENCH_PRESS, PULL_UP/WIDE_GRIP_LAT_PULLDOWN, LATERAL_RAISE/DUMBBELL_LATERAL_RAISE, LUNGE/DUMBBELL_LUNGE, CALF_RAISE/STANDING_BARBELL_CALF_RAISE). Use your best judgement to find the closest match.
3. Show the user the proposed mapping and ask for confirmation before proceeding.
4. Create the activity: gccli activity create --name "Upper Body" --type strength_training --duration 34m --date 2024-06-15T19:01:00
5. Extract the activity ID from the output (JSON: activityId field, table: "Created activity <id>").
6. Add exercise sets: gccli activity exercise-sets set <id> -e "CATEGORY/NAME:reps@weightkg[:dSECS][:rSECS]" [-e ...]

Exercise set format: CATEGORY/NAME:reps@weightkg[:dSECS][:rSECS]

• CATEGORY: exercise category (e.g. BENCH_PRESS, PULL_UP, LATERAL_RAISE, LUNGE, CALF_RAISE)
• NAME: specific exercise name within category (e.g. BARBELL_BENCH_PRESS, WIDE_GRIP_LAT_PULLDOWN)
• reps: number of repetitions
• weightkg: weight in kg (e.g. 20 for 20kg, 41.5 for 41.5kg, 0 for bodyweight)
• :dSECS: optional set duration in seconds (e.g. :d30 for 30s)
• :rSECS: optional rest duration in seconds after this set (e.g. :r60 for 60s)

Each -e flag is one set. For 3 sets of 12 reps, use three -e flags with the same exercise.

Example full workflow:

gccli activity create --name "Upper Body" --type strength_training --duration 34m --date 2026-03-13T19:01:00 --json
# Extract activityId from JSON response
gccli activity exercise-sets set <id> \
  -e "PULL_UP/WIDE_GRIP_LAT_PULLDOWN:12@41:d30:r60" \
  -e "PULL_UP/WIDE_GRIP_LAT_PULLDOWN:12@41:d30:r60" \
  -e "PULL_UP/WIDE_GRIP_LAT_PULLDOWN:12@41:d30:r90" \
  -e "LATERAL_RAISE/DUMBBELL_LATERAL_RAISE:12@8:d25:r60" \
  -e "LATERAL_RAISE/DUMBBELL_LATERAL_RAISE:12@8:d25:r60" \
  -e "LATERAL_RAISE/DUMBBELL_LATERAL_RAISE:12@8:d25:r90" \
  -e "BENCH_PRESS/BARBELL_BENCH_PRESS:12@20:d30:r60" \
  -e "BENCH_PRESS/BARBELL_BENCH_PRESS:8@20:d35:r60" \
  -e "BENCH_PRESS/BARBELL_BENCH_PRESS:5@20:d40"

Notes

• Set GCCLI_ACCOUNT=[e-mail] to avoid repeating --account.
• For scripting, use --json for JSON output or --plain for TSV.
• Dates support today, yesterday, 3d, or YYYY-MM-DD.
• Tokens are stored securely in the OS keyring (macOS Keychain, Linux Secret Service, file fallback).
• Tokens auto-refresh on 401; automatic retry on 429/5xx with exponential backoff.
• For Garmin China accounts: export GCCLI_DOMAIN=garmin.cn.
• Confirm before deleting activities/workouts (or use --force).
• Download formats: FIT (default), GPX, TCX, KML, CSV.
• Workout step format: type:duration[@target:low-high] — types: warmup, run, recovery, cooldown; targets: pace (min:sec), hr (bpm), power (watts), cadence.