技能包

gccli：Garmin Connect 資料的命令列與 agent 查詢指南

gccli 最適合在終端機或 agent 用戶端裡直接查詢自己的 Garmin Connect 活動、健康、身體組成等資料，並把 JSON 或 plain/TSV 可解析輸出交給腳本；使用前必須完成 Garmin SSO 驗證，且備援權杖檔案以原始碼內建固定密碼加密，請先確認能接受再開始。

官方來源 · gccli — A command-line interface for Garmin Connect

安裝

brew install bpauli/tap/gccli

適合誰

gccli 是 Garmin Connect 的命令列工具，官方定位為「快速、適合腳本的 CLI」，可存取活動、健康資料、身體組成、訓練、路線、裝置、裝備、目標與徽章。適合這些人：

  • 想在終端機直接查詢自己的 Garmin 資料、並讓結果進腳本的人：官方提供 JSON 與 plain/TSV 兩種可解析輸出，明確面向腳本與自動化。
  • 在 agent 用戶端裡工作、想讓 agent 代查資料的人：gccli 內建即用的 agent skill，官方說明面向 Claude Code、Codex、Hermes、OpenClaw 等 AI agent 用戶端。
  • 需要把訓練與健康資料併入自動化流程的開發者。

不適合或需先確認的情況：

  • 沒有 Garmin Connect 帳號無法使用：驗證經 Garmin SSO 完成，這是必要前提。
  • 不想用 Homebrew 的環境：官方提供的可複製安裝指令只有 Homebrew 一條；從原始碼建置要求 Go 1.26 或更高，完整建置步驟官方儲存庫未提供。
  • 用戶端名單是官方列舉而非窮盡，名單之外是否相容未說明，接入前以儲存庫說明文件為準。

3 分鐘完成第一次嘗試

推薦主路徑只有一條：用 Homebrew 安裝，完成 Garmin SSO 驗證，再讓 agent 跑一個查詢。

前提：已有 Garmin Connect 帳號；本機已安裝 Homebrew；知道首次驗證會把憑證寫入系統 keyring（副作用見「使用邊界」）。

第 1 步，安裝：

brew install bpauli/tap/gccli

第 2 步，驗證。驗證經 Garmin SSO 進行，憑證保存到系統 keyring。一個必須先知道的細節：官方明確說明，gccli 用內建於原始碼的固定密碼加密每個權杖檔案——即 keyring 不可用時的備援權杖檔案，其加密密碼並非你的專屬祕密，能否接受請在首次驗證前自行判斷。具體登入指令官方說明文件未給出，安裝後依 gccli 內建說明完成登入。

第 3 步，讓 agent 接上技能。gccli 內建的 agent skill 在 skills/gccli/SKILL.md，官方稱其即用；接入你所用用戶端的具體步驟官方說明文件未給出，以各用戶端說明文件為準。

第 4 步，發起一個查詢任務。直接對 agent 說：「列出我最近的跑步活動與這週的身體組成數據」。這類任務落在官方列出的資料存取能力內；查詢過程是否寫入本機檔案官方未說明、未確認，已確認的寫入副作用只有權杖儲存（見「使用邊界」），不要預設「唯讀不寫」。

第 5 步，核對成功訊號：回傳應是 JSON 或 plain/TSV 的可解析輸出，可直接貼上或交給腳本；看到結構化輸出即代表連動成功。

使用案例

案例 1：彙整訓練與身體數據。

  • 情境：想一次看全最近的運動紀錄與體重變化，不在網頁版逐筆翻。
  • 發起：在接好 gccli 的 agent 用戶端裡說「列出我最近的訓練與身體組成紀錄」。
  • 工作流：agent 經 gccli 存取活動與身體組成這兩類官方確認的資料類別。
  • 可期待結果：拿到 JSON 或 plain/TSV 可解析輸出，可貼進試算表或交給腳本；單筆紀錄的欄位清單官方未列出，以實際回傳為準。

案例 2：把 Garmin 數據併入自動化腳本。

  • 情境：想每週固定彙整裝置、裝備、目標與徽章狀態，形成自己的訓練檔案。
  • 發起：在已有的腳本或排程 agent 任務裡呼叫 gccli，把輸出交給下游處理。
  • 工作流：利用官方「適合腳本」定位與 JSON、plain/TSV 輸出模式接入現有流程。
  • 可期待結果：機器可讀輸出可穩定進入下一步；具體子指令與參數清單官方未逐字給出，動手前以 gccli 說明輸出與儲存庫說明為準。

使用邊界

  • 網路與帳號：資料來自 Garmin Connect 雲端，驗證與每次查詢都需連上網路並使用你的 Garmin 帳號；官方未提及離線能力，未確認。
  • 憑證與寫入副作用：首次驗證經 Garmin SSO，憑證寫入系統 keyring；keyring 不可用時的備援權杖檔案用原始碼內建固定密碼加密。除權杖儲存外，查詢是否寫入其他檔案，官方未說明，未確認。
  • 執行環境：從原始碼建置要求 Go 1.26 或更高；推薦主路徑經 Homebrew 安裝，不涉及本機建置；其他執行需求未寫明。
  • 用戶端前提：內建 agent skill 面向 Claude Code、Codex、Hermes、OpenClaw 等 AI agent 用戶端；名單之外的用戶端是否相容、各用戶端接入步驟是否一致，官方未逐一說明，接入前以各用戶端說明文件為準。
  • 明確限制：速率限制、匯出上限、服務條款層面的約束官方均未提及；大量或高頻使用前先查閱官方儲存庫。