Install
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 클라이언트를 대상으로 합니다. 목록 외 클라이언트의 호환 여부, 클라이언트별 연동 절차의 일관성은 공식이 하나하나 설명하지 않으므로, 연동 전에 각 클라이언트 문서를 확인하세요.
- 명시적 제한: 속도 제한, 내보내기 상한, 서비스 약관 수준의 제약은 공식 언급이 없습니다. 대량 또는 고빈도 사용 전에 공식 저장소를 먼저 확인하세요.