核心功能与用法
gccli 是 Garmin Connect 的命令行接口工具，提供对 Garmin 健康与健身生态系统的完整编程访问能力。用户通过 Garmin SSO 完成一次性认证后，即可在终端中查询和管理几乎所有 Garmin 数据类型。
核心能力覆盖
活动数据管理：列出、搜索、下载（FIT/GPX/TCX/KML/CSV）、上传、创建手动活动，支持详细查询包括分段数据、心率区间、功率区间、天气、装备关联等。
健康指标追踪：涵盖步数、心率（静息/运动）、睡眠、呼吸、血氧、HRV、压力、Body Battery、训练准备度、训练状态、体能年龄、VO2max、乳酸阈值、骑行FTP、比赛预测、耐力评分、强度分钟数等完整健康图谱。
身体成分记录：体重记录、体脂/肌肉量等详细体成分数据、血压监测，支持历史范围查询。
训练与课程：创建结构化训练（支持配速/心率/功率目标）、管理训练计划、导入/导出课程（GPX）、发送至设备。
设备与装备管理：设备列表、设置、闹钟、太阳能数据；装备追踪、关联活动、统计里程。
目标与社交： goals 追踪、徽章系统、挑战赛、个人记录、赛事规划。
技术特性
- 认证安全：OAuth 令牌存储于系统密钥环（macOS Keychain/Linux Secret Service），支持 MFA，token 自动刷新
- 输出格式：默认表格友好输出，
--json用于程序化解析，--plain提供 TSV 格式 - 日期智能：支持
today、yesterday、3d快捷语法及标准日期范围 - 可靠性：401 自动重授权，429/5xx 指数退避重试
- 跨平台：macOS 与 Linux 支持，Homebrew 一键安装
显著优势
1. 官方级数据完整性：相比第三方 API 爬取方案，gccli 提供 Garmin 原生数据结构的完整访问
2. 自动化友好：JSON 输出、管道支持、token 导出/导入，适合 CI/CD 与健康数据自动化流水线
3. 力量训练工作流：独特的 exercise-sets 系统支持通过 CLI 精确记录结构化力量训练
局限性与风险
- 非官方工具：由社区开发者维护（bpauli），非 Garmin 官方出品，存在 API 变更导致失效的风险
- 认证依赖：需要有效的 Garmin 账户，部分高级功能依赖设备型号支持
- 区域限制：Garmin 中国账户需手动设置
GCCLI_DOMAIN=garmin.cn - 数据隐私：健康敏感数据通过命令行处理，需确保环境安全
适合人群
- 需要将 Garmin 数据集成到个人健康分析工作流的技术用户
- 开发者构建健身应用、训练日志自动化、健康数据仪表盘的场景
- 希望避免手动导出 FIT 文件的高级运动爱好者
- 力量训练用户，需要精确记录组数、重量、休息时间的结构化训练者
常规风险
- API 稳定性：Garmin 可能随时更改私有 API，导致工具临时失效
- 账户安全：凭证存储虽使用系统密钥环，但仍建议定期审计授权
- 数据准确性：CLI 创建的手动活动可能与设备记录存在细微差异