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 for MFA)
• Set default account: export GCCLI_ACCOUNT=you@example.com
• 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 (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
• Activity details: gccli activity details
• Activity splits: gccli activity splits
• Activity weather: gccli activity weather
• Activity HR zones: gccli activity hr-zones
• Activity power zones: gccli activity power-zones
• Activity exercise sets (show): gccli activity exercise-sets
• Set exercise sets: gccli activity exercise-sets set -e "CATEGORY/NAME:reps@weightkg[:dSECS][:rSECS]" [-e ...]
• Activity gear: gccli activity gear
• Download activity (FIT): gccli activity download --format fit
• Download activity (GPX): gccli activity download --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 "New Name"
• Retype activity: gccli activity retype running
• Delete activity: gccli activity delete --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
• Download workout (FIT): gccli workouts download --output workout.fit
• Upload workout (JSON): gccli workouts upload ./workout.json
• Schedule workout: gccli workouts schedule add 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 (use --force to skip confirmation)
• Delete workout: gccli workouts delete
• 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
• 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
• Delete course: gccli courses delete (use -f to skip confirmation)
• List devices: gccli devices list
• Device settings: gccli devices settings
• Primary device: gccli devices primary
• Last used device: gccli devices last-used
• Device alarms: gccli devices alarms
• Solar data: gccli devices solar --start 2024-06-01 --end 2024-06-30
• List gear: gccli gear list
• Gear stats: gccli gear stats
• Gear activities: gccli gear activities --limit 20
• Gear defaults: gccli gear defaults
• Link gear: gccli gear link
• Unlink gear: gccli gear unlink
• 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
• 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 (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 ").
6. Add exercise sets: gccli activity exercise-sets set -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.com 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.