gccli 是做什麼的？
使用 gccli 存取 Garmin Connect 的健康、健身與活動資料。需要 Garmin SSO 認證。
設定（一次性）
gccli auth login [email protected]（開啟瀏覽器進行 Garmin SSO 登入）- 無頭模式：
gccli auth login [email protected] --headless（搭配--mfa-code <code>使用 MFA） - 設定預設帳號：
export [email protected] - 驗證：
gccli auth status
輸出
- 預設：人類友善的表格。使用
--json/-j取得 JSON 格式，--plain取得 TSV 格式。 - 資料輸出至 stdout，訊息/錯誤輸出至 stderr。
- 程式化解析輸出時一律使用
--json。
日期快捷方式
today、yesterday、3d（N 天前）、YYYY-MM-DD（特定日期）。- 使用
--start/--end旗標指定日期範圍。
常用指令
- 認證狀態：
gccli auth status - 認證 Token（用於腳本）：
gccli auth token - 匯出憑證：
gccli auth export（可導向檔案或複製到其他機器） - 匯入憑證：
gccli auth import <token>（來自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 <id> - 活動詳細資料：
gccli activity details <id> - 活動分段：
gccli activity splits <id> - 活動天氣：
gccli activity weather <id> - 活動心率區間：
gccli activity hr-zones <id> - 活動功率區間：
gccli activity power-zones <id> - 活動訓練組數（顯示）：
gccli activity exercise-sets <id> - 設定訓練組數：
gccli activity exercise-sets set <id> -e "CATEGORY/NAME:reps@weightkg[:dSECS][:rSECS]" [-e ...] - 活動裝備：
gccli activity gear <id> - 下載活動（FIT）：
gccli activity download <id> --format fit - 下載活動（GPX）：
gccli activity download <id> --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 <id> "New Name" - 變更活動類型：
gccli activity retype <id> running - 刪除活動：
gccli activity delete <id> --force - 活動類型：
gccli activities types - 健康摘要：
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] - HRV：
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] - VO2max / 最大指標：
gccli health max-metrics [date] - 乳酸閾值：
gccli health lactate-threshold - 自行車 FTP：
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 <id> - 下載訓練（FIT）：
gccli workouts download <id> --output workout.fit - 上傳訓練（JSON）：
gccli workouts upload ./workout.json - 更新訓練（JSON）：
gccli workouts update <id> ./workout.json— 原地取代該訓練，保留其 ID 與任何現有排程 - 排程訓練：
gccli workouts schedule add <id> 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 <schedule-id>（使用--force跳過確認） - 刪除訓練：
gccli workouts delete <id> - 建立含配速的跑步訓練：
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 <id> - 下載路線（FIT）：
gccli courses download <id> --format fit - 下載路線（GPX）：
gccli courses download <id> --format gpx --output route.gpx - 從 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 <course-id> <device-id> - 刪除路線：
gccli courses delete <id>（使用-f跳過確認） - 列出裝置：
gccli devices list - 裝置設定：
gccli devices settings <device-id> - 主要裝置：
gccli devices primary - 上次使用裝置：
gccli devices last-used - 裝置鬧鐘：
gccli devices alarms - 太陽能資料：
gccli devices solar <device-id> --start 2024-06-01 --end 2024-06-30 - 列出裝備：
gccli gear list - 裝備統計：
gccli gear stats <uuid> - 裝備活動：
gccli gear activities <uuid> --limit 20 - 裝備預設值：
gccli gear defaults - 連結裝備：
gccli gear link <uuid> <activity-id> - 解除裝備連結：
gccli gear unlink <uuid> <activity-id> - 目標：
gccli goals list --status active - 已獲得徽章：
gccli badges earned - 可獲得徽章：
gccli badges available - 進行中徽章：
gccli badges in-progress - 挑戰：
gccli challenges list - 徽章挑戰：
gccli challenges badge - 個人紀錄：
gccli records - 個人檔案：
gccli profile - 個人檔案設定：
gccli profile settings - 水分補充：
gccli hydration [date] - 記錄飲水量：
gccli hydration add 500 - 營養食物日誌：
gccli nutrition [date] - 營養餐點：
gccli nutrition meals [date] - 營養設定：
gccli nutrition settings [date] - 訓練計畫：
gccli training plans --locale en - 訓練計畫詳細資料：
gccli training plan <id> - 月經週期：
gccli wellness menstrual-cycle --start-date 2024-01-01 --end-date 2024-03-31 - 懷孕摘要：
gccli wellness pregnancy-summary - 列出活動：
gccli events list - 從某日期起列出活動：
gccli events list --start 2024-06-01 --limit 50 - 新增活動：
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 - 新增含目標與訓練優先級的活動：
gccli events add --name "Spring 10K" --date 2026-05-10 --type running --race --distance 10km --goal 40m --training - 刪除活動：
gccli events delete <id>（使用-f跳過確認） - 重新載入資料：
gccli reload [date] - 列出運動分類：
gccli exercises list - 列出分類中的運動：
gccli exercises list -c BENCH_PRESS - 列出運動（JSON）：
gccli exercises list --json
重量訓練工作流程（LLM 輔助運動比對）
當使用者想記錄以自由文字描述的重量訓練活動時（例如「臥推 3x12@20kg，滑輪下拉 3x12@41kg」），請遵循以下流程：
- 取得 Garmin 運動目錄：
gccli exercises list --json - 將使用者描述的每個運動對應至最相符的 Garmin CATEGORY/EXERCISE_NAME 配對。目錄使用 SCREAMING_SNAKE_CASE（例如 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）。請以最佳判斷尋找最接近的配對。
- 向使用者顯示建議的對應並要求確認後再繼續。
- 建立活動：
gccli activity create --name "Upper Body" --type strength_training --duration 34m --date 2024-06-15T19:01:00 - 從輸出中擷取活動 ID（JSON：activityId 欄位，表格：「Created activity 」）。
- 加入訓練組數：
gccli activity exercise-sets set <id> -e "CATEGORY/NAME:reps@weightkg[:dSECS][:rSECS]" [-e ...]
訓練組數格式：CATEGORY/NAME:reps@weightkg[:dSECS][:rSECS]
- CATEGORY：運動分類（例如 BENCH_PRESS、PULL_UP、LATERAL_RAISE、LUNGE、CALF_RAISE）
- NAME：該分類中的具體運動名稱（例如 BARBELL_BENCH_PRESS、WIDE_GRIP_LAT_PULLDOWN）
- reps：次數
- weightkg：重量（公斤，例如 20 代表 20kg、41.5 代表 41.5kg、0 代表體重）
- :dSECS：可選的組數持續時間（秒，例如 :d30 代表 30 秒）
- :rSECS：可選的該組後休息時間（秒，例如 :r60 代表 60 秒）
每個 -e 旗標代表一組。若要做 3 組 12 下，請使用三個相同的 -e 旗標。
完整工作流程範例：
gccli activity create --name "Upper Body" --type strength_training --duration 34m --date 2026-03-13T19:01:00 --json
# 從 JSON 回應中擷取 activityId
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"
注意事項
- 設定
[email protected]可避免重複指定--account。 - 腳本化時，使用
--json取得 JSON 輸出，或--plain取得 TSV 輸出。 - 日期支援
today、yesterday、3d或YYYY-MM-DD。 - Token 會安全儲存在作業系統金鑰環中（macOS Keychain、Linux Secret Service，檔案備援）。
- Token 會在收到 401 時自動重新整理；遇到 429/5xx 時會自動以指數退避重試。
- 若為 Garmin 中國帳號：
export GCCLI_DOMAIN=garmin.cn。 - 刪除活動/訓練前會要求確認（或使用
--force）。 - 下載格式：FIT（預設）、GPX、TCX、KML、CSV。
- 訓練步驟格式：
type:duration[@target:low-high]— 類型：warmup、run、recovery、cooldown；目標：pace（分:秒）、hr（bpm）、power（瓦特）、cadence。 workouts update會取代整個訓練，因此請從gccli workouts detail <id>取得檔案後編輯。workoutId會由 ID 參數設定，因此upload的 payload 可直接使用。