Fitbit Web API 시대가 저물고 구글 헬스 API가 그 자리를 이어받고 있습니다. 그런데 새 API는 gRPC 예제와 OAuth 절차가 낯설어서, 손목에 찬 데이터를 노트북에서 만지려면 여전히 삽질이 필요했습니다. ghealth는 그 사이를 메우는 오픈소스 CLI입니다. Go 하나로 짜서 바이너리 한 개로 떨어지고, 명령 한 줄이면 심박·수면·걸음 수가 JSON으로 튀어나옵니다.
특이한 건 처음부터 사람이 아니라 에이전트를 염두에 두고 설계했다는 점입니다. 모든 출력이 예측 가능한 스키마의 간단한 JSON이고, --dry-run과 --raw 플래그, 결정적 종료 코드까지 갖췄습니다. 클로드나 코덱스에 그대로 파이프로 물릴 수 있게 만든 셈이죠.
핵심 요약
ghealth는 구글 헬스 API v4를 감싼 오픈소스 CLI로, Fitbit Web API의 공식 후속인 v4 스택을 터미널에서 다루게 해줍니다.- Go 단일 바이너리, Apache 2.0 라이선스, 40종의 데이터 타입이 검증돼 있습니다.
- 출력은 간결한 JSON이 기본이고, 원본이 필요하면
--raw, 시트로 넘길 땐--format csv나table을 쓸 수 있습니다. SKILL.md두 개를 함께 배포합니다. 인증·세팅용 하나, 40종 타입 문서용 하나로, 에이전트에 그대로 붙일 수 있습니다.- PKCE S256 기반의 헤드리스 OAuth 흐름과 자동 토큰 갱신을 지원하며, 자격증명은
~/.config/ghealth/에 파일 모드 0600으로 저장됩니다.
40종 데이터, 하나의 커맨드 규격
ghealth가 커버하는 40종에는 걸음 수, 심박, 수면, 체중, 산소포화도, 심박 변이도가 들어갑니다. 심전도 같은 임상급 데이터는 별도의 ecg.readonly 스코프가 필요합니다. Fitbit뿐 아니라 픽셀 워치와 연동된 서드파티 소스도 같은 규격으로 흘러 들어옵니다.
읽기 명령은 타입마다 다르지 않고 일관된 구조를 가집니다. list, rollup, daily-rollup, reconcile 네 가지가 축이고, 쓰기가 허용된 타입인 운동·수면·체중·체지방·키에는 create, update, delete가 추가됩니다. reconcile은 여러 소스에서 겹치는 데이터 포인트를 합쳐 주는데, v4 API의 Reconciled Stream을 그대로 반영합니다.
수면 분석이 재밌는 예시입니다. 그냥 list만 던지면 요약이 오지만, --detail을 붙이면 각성·깊은 잠·렘 수면 같은 스테이지 단위로 쪼개서 돌려줍니다. 주간 패턴을 볼 때 정말 유용합니다.
첫 실행: setup 마법사가 시키는 대로
첫 관문은 명령 하나입니다.
ghealth setup
마법사가 GCP 프로젝트 만들기와 OAuth 클라이언트 등록을 순서대로 안내합니다. 구글 클라우드 콘솔에서 데스크톱 타입 OAuth 클라이언트를 발급하고, 그걸 도구에 물려 주면 끝입니다. 공유 키를 배포하는 방식이 아니어서 자격증명은 각자 자기 것을 가지게 됩니다.
주의할 점은 구글 헬스 API의 모든 스코프가 Restricted로 분류된다는 것입니다. 프로덕션 배포에는 프라이버시·보안 심사가 필요하고, 개인 용도라면 내 프로젝트로 내 계정에만 인가하면 됩니다. 헤드리스 인증은 PKCE S256 챌린지에 무작위 state 검증까지 얹은 표준 절차라, 스크립트에서 돌리기도 무리가 없습니다.
손에 익는 명령 몇 개
가장 자주 쓸 만한 커맨드 몇 개를 보면 감이 옵니다.
# 최근 심박 10건
ghealth data heart-rate list --from today --limit 10
# 지난주 걸음 수 합계
ghealth data steps daily-rollup --from 2026-03-22 --to 2026-03-29
# 최근 5일 수면 스테이지
ghealth data sleep list --limit 5 --detail
결과는 이런 식으로 떨어집니다.
{
"dataPoints": [
{"date": "2026-03-28", "countSum": "9037"},
{"date": "2026-03-27", "countSum": "2408"}
]
}
-o 옵션으로 파일에 바로 쓰고 스키마 프리뷰까지 찍어 주기 때문에, 데이터 파이프라인 앞단에 붙이기 좋습니다. 결과가 커지면 nextPageToken이 딸려 오고, 다음 호출에 --page-token으로 되던지면 무손실 페이지네이션이 됩니다.
실제로 뭘 할 수 있나
문서에 있는 세 가지 활용 예시가 실용적입니다.
- 수면 패턴을 에이전트에 물리기.
--detail로 며칠치 수면을 뽑아 JSON을 그대로 클로드 코드나 코덱스 세션에 붙이면, 주간 깊은 잠 트렌드를 요약해 달라고 시킬 수 있습니다. - 운동을 판다스로 옮기기.
ghealth data exercise export-tcx --id <id> --output ride.csv --as csv를 돌리면 각 행이 한 지점의 심박·GPS 트랙포인트로 정리된 CSV가 만들어집니다. 그대로pd.read_csv에 넣으면 됩니다. - 안정 시 심박 대시보드. 30일치
daily-resting-heart-rate를--format csv로 뽑아서 노트북이나 그라파나 대시보드에 붙이는 흐름도 자연스럽습니다.
비슷한 도구와 어떻게 다른가
시장에는 이미 유사한 CLI가 두어 개 있습니다. 다만 나머지는 스스로 “비공식"이라고 밝히고 있고, 언어와 설계 철학이 조금씩 다릅니다.
| 항목 | ghealth | Google Health API v4 (직접 호출) | rudrankriyam/Google-Health-CLI | googlehealth-cli (npm) |
|---|---|---|---|---|
| 설치 | git clone + go build | 직접 HTTP/gRPC 호출 | Go 소스 빌드 | npm i -g |
| 언어 | Go, 단일 바이너리 | 무관 | Go | Node.js |
| 인증 | 내 OAuth + PKCE S256 | 구글 OAuth 2.0 | 내 OAuth | 내 OAuth |
| 에이전트 출력 | 간결 JSON, 종료 코드, SKILL.md | 원본 JSON/gRPC | 예측 가능 JSON | 안정 --json |
| 데이터 타입 | 실 API 대비 40종 검증 | v4 전 표면 | 문서화된 v4 추적 | 일부 타입 |
| 공식 여부 | 커뮤니티, Google-Health-API 조직 | 구글 공식 | 비공식 명시 | 비공식 명시 |
원시 제어가 필요하면 REST를 그대로 다루는 게 정답이지만, 터미널과 에이전트가 주 사용처라면 인증·포매팅 잔손질을 이 정도까지 줄여 주는 도구가 아직 흔치 않습니다.
실무자가 볼 핵심 포인트
- 손목 데이터를 코드/에이전트에 물리기가 처음으로 편해졌습니다. 명령 한 줄 → JSON 한 덩이 → 파이프라인 다음 단계로 바로 넘어갑니다.
- 자격증명은 팀 공유가 아니라 각자 발급이 원칙입니다. 팀에 배포할 계획이라면 구글 심사 대응까지 감안해서 일정을 잡아야 합니다.
SKILL.md두 파일은 그대로 자산입니다. 사내 에이전트에 인증 절차와 데이터 스키마를 붙이고 싶다면 이걸 시작점으로 쓰면 됩니다.- 쓰기 오퍼레이션이 있는 타입은 신중하게. 운동·수면·체중·체지방·키에 대해
create/update/delete가 가능하니, 실수로 원본 데이터를 덮어쓰지 않도록--dry-run을 습관화하는 게 안전합니다. - 커뮤니티 프로젝트라는 사실을 잊지 마세요. 구글이 API 표면을 바꾸면 CLI가 따라가야 하니, 프로덕션 파이프라인은 버전 고정과 회귀 테스트를 함께 붙이는 편이 낫습니다.
원문 출처
원문 보기 — Michal Sutter, MarkTechPost, 2026-07-02