- name
- garmin-connect
- description
- Garmin Connect CLI for activities, health, body composition, workouts, devices, gear, goals, and more.
- homepage
- https://github.com/bpauli/gccli
- metadata
- {"clawdbot":{"emoji":"⌚","os":["darwin","linux"],"requires":{"bins":["gccli"]},"install":[{"id":"homebrew","kind":"brew","formula":"bpauli/tap/gccli","bins":["gccli"],"label":"Homebrew (recommended)"},{"id":"source","kind":"source","url":"https://github.com/bpauli/gccli","bins":["gccli"],"label":"Build from source (Go 1.24+)"}]}}
gccli
Use gccli for Garmin Connect health, fitness, and activity data. Requires Garmin SSO authentication.
Setup (once)
gccli auth login you@example.com(opens browser for Garmin SSO)- Headless:
gccli auth login you@example.com --headless(with--mfa-code <code>for MFA) - Set default account:
export GCCLI_ACCOUNT=you@example.com - Verify:
gccli auth status
Output
- Default: human-friendly tables. Use
--json/-jfor JSON,--plainfor TSV. - Data goes to stdout, messages/errors to stderr.
- Always use
--jsonwhen parsing output programmatically.
Date shortcuts
today,yesterday,3d(N days ago),YYYY-MM-DD(specific date).- Use
--start/--endflags 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>(fromauth exportoutput) - 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 - Activity types:
gccli activities types - 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--forceto 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-fto 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-fto 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:
- Fetch the Garmin exercise catalog:
gccli exercises list --json - 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.
- Show the user the proposed mapping and ask for confirmation before proceeding.
- Create the activity:
gccli activity create --name "Upper Body" --type strength_training --duration 34m --date 2024-06-15T19:01:00 - Extract the activity ID from the output (JSON: activityId field, table: "Created activity <id>").
- 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=you@example.comto avoid repeating--account. - For scripting, use
--jsonfor JSON output or--plainfor TSV. - Dates support
today,yesterday,3d, orYYYY-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.