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: INLINECODE4
- Verify: INLINECODE5
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: INLINECODE16
- Auth token (for scripting): INLINECODE17
- 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: INLINECODE21
- List activities: INLINECODE22
- List activities by type: INLINECODE23
- Activity count: INLINECODE24
- Search activities: INLINECODE25
- Activity summary: INLINECODE26
- Activity details: INLINECODE27
- Activity splits: INLINECODE28
- Activity weather: INLINECODE29
- Activity HR zones: INLINECODE30
- Activity power zones: INLINECODE31
- Activity exercise sets (show): INLINECODE32
- Set exercise sets: INLINECODE33
- Activity gear: INLINECODE34
- Download activity (FIT): INLINECODE35
- Download activity (GPX): INLINECODE36
- Upload activity: INLINECODE37
- Create manual activity: INLINECODE38
- Rename activity: INLINECODE39
- Retype activity: INLINECODE40
- Delete activity: INLINECODE41
- Health summary: INLINECODE42
- Steps chart: INLINECODE43
- Daily steps range: INLINECODE44
- Weekly steps: INLINECODE45
- Heart rate: INLINECODE46
- Resting HR: INLINECODE47
- Floors climbed: INLINECODE48
- Sleep: INLINECODE49
- Respiration: INLINECODE50
- SpO2: INLINECODE51
- HRV: INLINECODE52
- Stress: INLINECODE53
- Weekly stress: INLINECODE54
- Body battery: INLINECODE55
- Body battery range: INLINECODE56
- Training readiness: INLINECODE57
- Training status: INLINECODE58
- Fitness age: INLINECODE59
- VO2max / max metrics: INLINECODE60
- Lactate threshold: INLINECODE61
- Cycling FTP: INLINECODE62
- Race predictions: INLINECODE63
- Race predictions range: INLINECODE64
- Endurance score: INLINECODE65
- Hill score: INLINECODE66
- Intensity minutes: INLINECODE67
- Weekly intensity minutes: INLINECODE68
- Wellness events: INLINECODE69
- Body composition: INLINECODE70
- Body composition range: INLINECODE71
- Weigh-ins: INLINECODE72
- Add weight: INLINECODE73
- Add composition: INLINECODE74
- Blood pressure: INLINECODE75
- Add blood pressure: INLINECODE76
- List workouts: INLINECODE77
- Workout detail: INLINECODE78
- Download workout (FIT): INLINECODE79
- Upload workout (JSON): INLINECODE80
- Schedule workout: INLINECODE81
- List scheduled workouts: INLINECODE82
- List scheduled workouts in range: INLINECODE83
- Remove scheduled workout:
gccli workouts schedule remove <schedule-id> (use --force to skip confirmation) - Delete workout: INLINECODE86
- Create running workout with pace: INLINECODE87
- Create workout with HR targets: INLINECODE88
- Create cycling workout with power: INLINECODE89
- List courses: INLINECODE90
- Favorite courses: INLINECODE91
- Course detail: INLINECODE92
- Import course from GPX (default: cycling, private): INLINECODE93
- Import course with name: INLINECODE94
- Import course with type: INLINECODE95
- Import public course: INLINECODE96
- Send course to device: INLINECODE97
- Delete course:
gccli courses delete <id> (use -f to skip confirmation) - List devices: INLINECODE100
- Device settings: INLINECODE101
- Primary device: INLINECODE102
- Last used device: INLINECODE103
- Device alarms: INLINECODE104
- Solar data: INLINECODE105
- List gear: INLINECODE106
- Gear stats: INLINECODE107
- Gear activities: INLINECODE108
- Gear defaults: INLINECODE109
- Link gear: INLINECODE110
- Unlink gear: INLINECODE111
- Goals: INLINECODE112
- Earned badges: INLINECODE113
- Available badges: INLINECODE114
- In-progress badges: INLINECODE115
- Challenges: INLINECODE116
- Badge challenges: INLINECODE117
- Personal records: INLINECODE118
- Profile: INLINECODE119
- Profile settings: INLINECODE120
- Hydration: INLINECODE121
- Log water: INLINECODE122
- Nutrition food log: INLINECODE123
- Nutrition meals: INLINECODE124
- Nutrition settings: INLINECODE125
- Training plans: INLINECODE126
- Training plan detail: INLINECODE127
- Menstrual cycle: INLINECODE128
- Pregnancy summary: INLINECODE129
- List events: INLINECODE130
- List events from date: INLINECODE131
- Add event: INLINECODE132
- Add event with goal and training priority: INLINECODE133
- Delete event:
gccli events delete <id> (use -f to skip confirmation) - Reload data: INLINECODE136
- List exercise categories: INLINECODE137
- List exercises in category: INLINECODE138
- List exercises (JSON): INLINECODE139
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: INLINECODE140
- Map each user-described exercise to the best matching Garmin CATEGORY/EXERCISENAME pair. The catalog uses SCREAMINGSNAKECASE (e.g. BENCHPRESS/BARBELLBENCHPRESS, PULLUP/WIDEGRIPLATPULLDOWN, LATERALRAISE/DUMBBELLLATERALRAISE, LUNGE/DUMBBELLLUNGE, CALFRAISE/STANDINGBARBELLCALFRAISE). Use your best judgement to find the closest match.
- Show the user the proposed mapping and ask for confirmation before proceeding.
- Create the activity: INLINECODE141
- Extract the activity ID from the output (JSON: activityId field, table: "Created activity ").
- Add exercise sets: INLINECODE142
Exercise set format: CATEGORY/NAME:reps@weightkg[:dSECS][:rSECS]
- - CATEGORY: exercise category (e.g. BENCHPRESS, PULLUP, LATERALRAISE, LUNGE, CALFRAISE)
- NAME: specific exercise name within category (e.g. BARBELLBENCHPRESS, WIDEGRIPLAT_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:
CODEBLOCK0
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.
gccli
使用 gccli 获取 Garmin Connect 健康、健身和活动数据。需要 Garmin SSO 认证。
设置（一次性）
- - gccli auth login you@example.com（打开浏览器进行 Garmin SSO 认证）
- 无头模式：gccli auth login you@example.com --headless（使用 --mfa-code
进行多因素认证） - 设置默认账户：export GCCLI_ACCOUNT=you@example.com
- 验证：gccli auth status
输出
- - 默认：人类友好的表格。使用 --json / -j 获取 JSON 格式，--plain 获取 TSV 格式。
- 数据输出到标准输出，消息/错误输出到标准错误。
- 以编程方式解析输出时始终使用 --json。
日期快捷方式
- - today、yesterday、3d（N 天前）、YYYY-MM-DD（具体日期）。
- 使用 --start/--end 标志指定日期范围。
常用命令
- - 认证状态：gccli auth status
- 认证令牌（用于脚本）：gccli auth token
- 导出凭据：gccli auth export（管道到文件或复制到另一台机器）
- 导入凭据：gccli auth import （来自 auth export 输出）
- 移除凭据：gccli auth remove
- 列出活动：gccli activities list --limit 20
- 按类型列出活动：gccli activities list --type running
- 活动计数：gccli activities count
- 搜索活动：gccli activities search --start-date 2024-01-01 --end-date 2024-12-31
- 活动摘要：gccli activity summary
- 活动详情：gccli activity details
- 活动分段：gccli activity splits
- 活动天气：gccli activity weather
- 活动心率区间：gccli activity hr-zones
- 活动功率区间：gccli activity power-zones
- 活动训练组（显示）：gccli activity exercise-sets
- 设置训练组：gccli activity exercise-sets set -e CATEGORY/NAME:reps@weightkg[:dSECS][:rSECS] [-e ...]
- 活动装备：gccli activity gear
- 下载活动（FIT）：gccli activity download --format fit
- 下载活动（GPX）：gccli activity download --format gpx --output track.gpx
- 上传活动：gccli activity upload ./activity.fit
- 创建手动活动：gccli activity create --name Morning Run --type running --date 2024-06-15T07:30:00 --duration 1800 --distance 5000
- 重命名活动：gccli activity rename New Name
- 更改活动类型：gccli activity retype running
- 删除活动：gccli activity delete --force
- 健康摘要：gccli health summary [date]
- 步数图表：gccli health steps [date]
- 每日步数范围：gccli health steps daily --start 2024-01-01 --end 2024-01-31
- 每周步数：gccli health steps weekly --weeks 4
- 心率：gccli health hr [date]
- 静息心率：gccli health rhr [date]
- 爬楼层数：gccli health floors [date]
- 睡眠：gccli health sleep [date]
- 呼吸：gccli health respiration [date]
- 血氧饱和度：gccli health spo2 [date]
- 心率变异性：gccli health hrv [date]
- 压力：gccli health stress [date]
- 每周压力：gccli health stress weekly --weeks 4
- 身体电量：gccli health body-battery [date]
- 身体电量范围：gccli health body-battery range --start 2024-01-01 --end 2024-01-07
- 训练准备度：gccli health training-readiness [date]
- 训练状态：gccli health training-status [date]
- 体能年龄：gccli health fitness-age [date]
- 最大摄氧量/最大指标：gccli health max-metrics [date]
- 乳酸阈值：gccli health lactate-threshold
- 骑行功能阈值功率：gccli health cycling-ftp
- 比赛预测：gccli health race-predictions [date]
- 比赛预测范围：gccli health race-predictions range --start 2024-01-01 --end 2024-06-30
- 耐力评分：gccli health endurance-score [date]
- 爬坡评分：gccli health hill-score [date]
- 强度分钟数：gccli health intensity-minutes [date]
- 每周强度分钟数：gccli health intensity-minutes weekly --start 2024-01-01 --end 2024-01-31
- 健康事件：gccli health events [date]
- 身体成分：gccli body composition [date]
- 身体成分范围：gccli body composition --start 2024-01-01 --end 2024-01-31
- 体重记录：gccli body weigh-ins --start 2024-01-01 --end 2024-01-31
- 添加体重：gccli body add-weight 75.5 --unit kg
- 添加身体成分：gccli body add-composition 75.5 --body-fat 15.2 --muscle-mass 35.0
- 血压：gccli body blood-pressure --start 2024-01-01 --end 2024-01-31
- 添加血压：gccli body add-blood-pressure --systolic 120 --diastolic 80 --pulse 65
- 列出训练计划：gccli workouts list --limit 20
- 训练计划详情：gccli workouts detail
- 下载训练计划（FIT）：gccli workouts download --output workout.fit
- 上传训练计划（JSON）：gccli workouts upload ./workout.json
- 安排训练计划：gccli workouts schedule add 2024-06-20
- 列出已安排的训练计划：gccli workouts schedule list 2024-06-20
- 列出范围内的已安排训练计划：gccli workouts schedule list --start 2024-06-01 --end 2024-06-30
- 移除已安排的训练计划：gccli workouts schedule remove （使用 --force 跳过确认）
- 删除训练计划：gccli workouts delete
- 创建带配速的跑步训练计划：gccli workouts create Easy Run --type run --step warmup:5m --step run:20m@pace:5:00-5:30 --step cooldown:5m
- 创建带心率目标的训练计划：gccli workouts create HR Run --type run --step warmup:10m --step run:20m@hr:140-160 --step cooldown:10m
- 创建带功率的骑行训练计划：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
- 列出路线：gccli courses list
- 收藏路线：gccli courses favorites
- 路线详情：gccli courses detail
- 从 GPX 导入路线（默认：骑行，私有）：gccli courses import route.gpx
- 带名称导入路线：gccli courses import route.gpx --name Sunday Ride
- 带类型导入路线：gccli courses import route.gpx --type gravel_cycling
- 导入公开路线：gccli courses import route.gpx --privacy 1
- 发送路线到设备：gccli courses send
- 删除路线：gccli courses delete （使用 -f 跳过确认）
- 列出设备：gccli devices list
- 设备设置：gccli devices settings
-
