Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
gccli는 Garmin Connect 데이터를 터미널에서 빠르고 스크립트 친화적으로 관리할 수 있는 CLI 도구입니다. 활동 기록, 건강 데이터(HRV, VO2max 등), 체성분, 운동 카탈로그, 코스 정보 등 다양한 항목에 접근하고 다운로드/업로드가 가능합니다. JSON 우선 출력과 다중 계정 지원 등의 기능을 제공하여 개발자 친화적입니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기ci
Go Version
Release
License
Docs
Buy Me A Coffee
Garmin Connect용 빠르고 스크립트 친화적인 CLI(Command Line Interface)입니다. 활동, 건강 데이터, 체성분, 운동, 코스, 기기, 장비, 목표, 배지 등 다양한 항목에 접근할 수 있습니다. JSON 우선 출력 방식, 다중 계정 지원, OS 키링에 자격 증명 저장 기능을 제공합니다.
활동 (Activities) - 목록 보기, 검색, 상세 정보 보기, 다운로드(FIT/GPX/TCX/KML/CSV), 업로드, 수동 항목 생성(날짜 포함), 이름 변경, 재입력, 설명 추가, 개인 정보 보호 설정 변경, 즐겨찾기 표시, 삭제, 근력 운동을 위한 세트 설정, 활동 유형 목록 보기, 보류 중인 활동 목록 보기, 댓글 및 좋아요 목록 보기, 좋아요/싫어요
운동 카탈로그 (Exercise Catalog) — Garmin의 근력 운동 카테고리 및 운동 둘러보기
건강 데이터 (Health Data) — 일일 요약, 걸음 수, 심박수, 안정 시 심박수(resting HR), 수면, 스트레스, HRV(Heart Rate Variability), SpO2, 호흡률, 배터리 상태(body battery), 층수, 훈련 준비도/상태(training readiness/status), VO2max, 피트니스 연령(fitness age), 레이스 예측, 지구력/언덕 점수, 강도 분(intensity minutes), 젖산 역치(lactate threshold), 사이클링 FTP(Functional Threshold Power), 핵심 수영 속도(critical swim speed), 파워 커브(power curve), 달리기 경제성(running economy)
체성분 (Body Composition) - 체중 추적, 최근 측정 기록, 주간 체중 요약, 체지방, 근육량, 혈압, 포도당, 구성 요소 업로드를 위한 FIT 파일 인코딩
운동 (Workouts) - 목록 보기, 보기, FIT 형식으로 다운로드, JSON에서 업로드, JSON에서 제자리 업데이트, 스포츠 유형 및 목표(페이스/HR/파워/케이던스)를 포함하여 생성, 일정 설정(추가/목록 보기/제거/내보내기), 기기로 전송, 운동 유형 및 스포츠 유형 목록 보기, 보기, 근력 벤치마크 설정 및 초기화, 삭제
코스 (Courses) — 코스 목록 보기, 즐겨찾는 코스 보기, 전체 코스 상세 정보 가져오기, FIT/GPX로 다운로드, GPX 파일을 새 코스로 가져오기, 기기로 코스 직접 전송, 코스 삭제
Devices: 등록된 장치 목록 보기, 설정 보기, 태양광 데이터, 알람, 기본/마지막 사용 장치, 페어링된 센서, 백업 요약, 기록 장치, 장치 메시지, 보류 중인 장치 메시지 취소
Gear: 기어 목록 보기, 사용 통계, 연결된 활동, 활동 유형별 기본 설정, 활동에 링크/링크 해제, 기어 유형, 추가, 업데이트, 은퇴 및 비은퇴, 그리고 삭제하기, 기어 컬렉션 목록 보기, 생성, 이름 변경 및 삭제, 컬렉션에 기어 추가
Goals & Badges: 활성 목표, 걸음 수, 층수, 강도 분, 수분 섭취량에 대한 일일 목표 설정, 획득/사용 가능/진행 중인 배지, 배지 상세 정보, 도전 과제, 개인 기록
Training: 트레이닝 계획 찾아보고 보기, 활성 계획 표시, 적응형 코칭 운동 유형 목록 제공
Profile: 사용자 프로필 및 설정, 개인 정보 보호 설정, 개인 정보 보호 구역 목록, 추가 및 삭제, 심박수 및 파워 구역
Hydration: 일일 수분 섭취량 보기 및 기록
Nutrition: 일일 음식 로그, 식사 및 영양 설정 보기, Garmin 식품 데이터베이스 검색, 최근 및 즐겨찾는 음식 목록 보기, 식사에 음식 로그 및 빠른 항목 추가, 로그 항목 삭제, 즐겨찾는 음식 추가 및 제거 (앞의 세 가지를 제외한 모든 기능은 Garmin Connect+ 필요)
Events: 캘린더 이벤트(레이스, 그룹 라이드 등) 목록 보기, 예정된 목록 보기, 목표 및 트레이닝 우선순위 지원을 통해 추가 및 삭제
Calendar: 캘린더 메모 추가, 업데이트, 이동 및 삭제
Wellness: 생리 주기 데이터 및 캘린더, 생리 일일 로그 (보기, 설정, 삭제), 임신 요약, 시차 적응 여행 및 상태
Social: 알림, 알림 환경설정 보기 및 변경, 연결, 연결 요청, 팔로워, 팔로우 중, 뉴스피드, 그룹
Agent-ready: Claude Code, Codex, Hermes, OpenClaw와 같은 AI 비서에 플러그인되는 번들 에이전트 스킬(skills/gccli/)을 제공하여 일반 언어로 Garmin Connect를 제어할 수 있게 함
Multiple accounts: --account 플래그를 통해 여러 Garmin 계정 관리
자격 증명 저장소 (Credential storage): OS 키링(macOS Keychain, Linux Secret Service)에 저장하며, 파일 폴백을 지원합니다 ( Credential Storage 참조).
자동 새로고침 토큰 (Auto-refreshing tokens): 한 번 인증하면 401 에러 발생 시 토큰이 자동으로 새로고침됩니다.
복원력 있는 네트워킹 (Resilient networking): API 호출은 429 에러 발생 시 재시도하며 (Retry-After 헤더를 최대 30초까지 대기, 최대 3회 재시도), 읽기 요청(GET)은 5xx 에러 발생 시 재시도합니다 (최대 2회, 지수 백오프). 쓰기 요청은 5xx 에러 발생 시 다시 전송되지 않습니다. API 요청은 데이터 이동이 60초 동안 없으면 실패하며, 계속해서 데이터가 이동하는 전송에는 시간 제한이 없습니다.
셸 완성 (Shell completion): bash, zsh, fish, PowerShell용 스크립트가 생성됩니다.
파싱 가능한 출력 (Parseable output): 스크립팅 및 자동화를 위해 JSON과 일반/TSV 모드를 지원합니다. --json 출력이 주요 버전 내에서 안정적으로 유지됩니다. 테이블 및 --plain 출력은 마이너 릴리스에서 변경될 수 있습니다.
사용자 단위 시스템 (Your unit system): 테이블은 Garmin Connect 프로필에 설정된 대로 km 또는 miles, km당/mile당 페이스, 미터 또는 피트의 고도, kg 또는 lbs의 무게를 표시합니다. --units 플래그로 지정할 수 있습니다.
brew install bpauli/tap/gccli
Go 1.26 이상이 필요합니다.
git clone https://github.com/bpauli/gccli.git
cd gccli
make build
생성된 바이너리는 ./bin/gccli에 위치합니다.
실행:
./bin/gccli --help
도움말 (Help):
gccli --help는 최상위 명령어 그룹을 보여줍니다.gccli <그룹> --help로 심층 탐색할 수 있습니다 (더 깊은 하위 명령어도 가능).make run -- --help (또는 make run -- activities --help).gccli auth login [email protected]
이 명령어는 Garmin SSO 인증을 위해 브라우저를 열어줍니다. DI OAuth 토큰은 시스템 키링에 저장됩니다.
브라우저가 없는 서버 또는 환경의 경우:
gccli auth login [email protected] --headless
비밀번호를 입력하라는 메시지가 표시됩니다. 계정에 2단계 인증이 설정되어 있는 경우:
gccli auth login [email protected] --headless --mfa-code 123456
로그인하면 이메일이 기본 계정으로 자동 저장되므로, 모든 명령어에 --account를 전달하거나 GCCLI_ACCOUNT을 설정할 필요가 없습니다.
gccli auth status
gccli activities list --limit 5
gccli는 skills/gccli/SKILL.md에서 즉시 사용 가능한 **에이전트 스킬(agent skill)**을 제공합니다. 이 스킬은 AI 어시스턴트에게 인증(auth), 활동(activities), 건강(health), 신체 구성(body composition), 운동(workouts), 코스(courses), 기기(devices), 장비(gear), 목표(goals), 이벤트(events) 등 전체 명령어 표면을 학습시켜, 사용자가 일반 언어로 질문하고 에이전트가 CLI를 구동할 수 있게 합니다:
이 스킬은 휴대 가능한 SKILL.md 형식(프론트매터 + Markdown)을 사용하며, 다음을 포함하여 스킬을 지원하는 모든 에이전트 런타임에서 작동합니다:
gccli 바이너리를 자동으로 프로비저닝할 수 있습니다.레포지토리를 클론하고 에이전트를 번들된 스킬 디렉터리(에이전트가 스킬을 발견하는 곳 어디든 복사하거나 심볼릭 링크를 만드세요)로 지정합니다:
git clone https://github.com/bpauli/gccli.git
# 그런 다음 gccli/skills/gccli를 에이전트의 스킬 디렉터리로 복사하거나 심볼릭 링크를 만드세요
gccli 바이너리가 설치되어 있는지 확인하고 (설치(Installation) 참조), gccli auth login으로 한 번 인증을 완료해야 합니다. 에이전트가 모든 호출에서 --account를 전달할 필요가 없도록 GCCLI_ACCOUNT를 설정하세요. 이 스킬은 결과를 파싱할 때 에이전트에게 --json 출력을 사용하도록 지시하고, 파괴적인 작업 전에는 확인을 요청합니다.
이 스킬은 자유 형식의 근력 운동 세션을 기록하기 위한 안내된 워크플로우를 포함합니다. 에이전트는 Garmin의 운동 카탈로그(gccli exercises list --json)를 가져와, 사용자가 설명한 운동을 Garmin의 CATEGORY/EXERCISE_NAME 쌍에 매핑하고, 이 매핑을 사용자에게 확인받은 후 활동(activity)을 생성하며, 각 세트(set)는 gccli activity exercise-sets set을 통해 기록합니다.
gccli는 OAuth 토큰을 키링 백엔드(keyring backend)에 저장합니다. 기본값은 자동 감지(auto-detection)이며, 사용자의 OS/환경에서 가장 적합한 백엔드를 사용합니다.
현재 인증 상태 목록 보기:
gccli auth status
원시 OAuth2 액세스 토큰 출력 (스크립팅에 유용). 토큰이 만료된 경우, 이 명령은 먼저 토큰을 새로 고친 후 새 토큰을 출력합니다. 새로 고치기에 실패하면 아무것도 출력하지 않고 3으로 종료됩니다:
gccli auth token
저장된 자격 증명 제거:
gccli auth remove
백엔드:
gccli에 내장된 고정 암호(fixed passphrase)로 암호화됩니다. (Credential Storage 참조)환경 변수를 통해 백엔드 설정:
export GCCLI_KEYRING_BACKEND=file
또는 설정 파일(config.json)에서:
{
"keyring_backend": "file"
}
Linux의 경우, D-Bus를 사용할 수 없으면 gccli가 자동으로 파일 백엔드로 폴백(fall back)합니다.
Garmin China 계정(garmin.cn)의 경우:
export GCCLI_DOMAIN=garmin.cn
또는 config.json에서:
{
"domain": "garmin.cn"
}
계정은 다음 순서로 해결됩니다:
--account 플래그GCCLI_ACCOUNT 환경 변수gccli auth login에 의해 저장된 기본 계정 (config.json에 저장됨)# 플래그를 통한 방식
gccli activities list --account [email protected]
...