Google Health API 推出 CLI：ghealth 是一款针对 Fitbit 数据的开源工具

Google Health API 推出 CLI：ghealth 是一款针对 Fitbit 数据的开源工具 · AI HOT

MarkTechPost（RSS）

精选

72

导出 Markdown

Google Health API 推出 CLI：ghealth 是一款针对 Fitbit 数据的开源工具

2026-07-02 16:46

·

41分钟前

Michal Sutter

阅读原文

marktechpost.com

精选理由

把 Google Health API 封装成终端和 AI 代理友好的 CLI，一次性解决了认证、JSON 输出和分页这些烦人细节，想用 Fitbit 数据做健康分析或喂给代理的人可以直接上手，但它的影响仅限于个人健康数据爱好者这个小圈层。

AI 摘要

ghealth 是一款封装 Google Health API v4 的开源命令行工具，以单个 Go 二进制文件发布（Apache 2.0 协议）。它提供 40 种已验证的数据类型（包括步数、心率、睡眠、体重、血氧饱和度、心率变异性等）的结构化 JSON 输出。工具采用 Agent 优先设计，具备确定性退出码、--dry-run 和 --raw 标志，并附带两个 SKILL.md 文件供 AI 智能体使用。用户需自行创建 OAuth 凭据，通过 PKCE S256 认证。数据来源覆盖 Fitbit、Pixel Watch 及连接的第三方设备。

原文

· 保持原样，未翻译

The Google Health API is the official successor to the Fitbit Web API. It targets the Google Health API v4 and moves developers onto Google OAuth 2.0. Now an open-source CLI command-line tool called ghealth wraps that API for terminals and AI agents.

The tool is a single Go binary under the Apache 2.0 license. It exposes 40 verified data types as structured JSON. That design lets you pipe sleep, heart rate, and step data into an agent’s context.

What is ghealth?

ghealth is a wrapper over the Google Health API v4. You build it from source with go build -o ghealth . . It ships as one self-contained binary.

The tool is explicitly agent-first. Every command returns simplified JSON with a stable shape. It also provides deterministic exit codes, a --dry-run flag, and a --raw flag.

The repository ships two Agent Skills as SKILL.md files. One covers auth, setup, and global flags. The other documents all 40 data types, operations, patterns, and gotchas. Agents install them with npx skills add .

The CLI lives under the Google-Health-API GitHub organization. That organization also hosts long-standing Fitbit open-source repositories.

The Data Surface: 40 Verified Types

The 40 types cover most Fitbit and Pixel Watch signals. Examples include steps , heart-rate , sleep , weight , oxygen-saturation , and heart-rate-variability . Clinical types like electrocardiogram require the ecg.readonly scope.

Each type supports a subset of operations. Common ones are list , rollup , daily-rollup , and reconcile . Writable types ( exercise , sleep , weight , body-fat , height ) add create , update , and delete .

The reconcile operation merges overlapping data points from multiple sources. That mirrors the Reconciled Stream in the v4 API.

Sleep is a good example for pattern analysis. The default list returns a summary. Adding --detail returns stage-by-stage data (awake, deep, REM). That helps you spot patterns week over week.

Setup: What Actually Happens

Setup runs through one command: ghealth setup . A wizard walks you through the GCP project and OAuth. You create a Desktop-type OAuth client in the Google Cloud Console.

You bring your own OAuth credentials. The tool holds no shared key. Files are written under ~/.config/ghealth/ with file mode 0600. Tokens refresh automatically.

All Google Health API scopes are classified as Restricted. Google requires a privacy and security review for production access. For personal use, you authorize your own project against your own account. The API returns data from Fitbit, Pixel Watch, and connected third-party sources.

The headless flow uses PKCE with an S256 challenge. It also validates a random state parameter on completion.

Hands-On: Commands and Output

Reading data is consistent across types. Every read returns an object with rows under dataPoints .

Copy Code

Copied

Use a different Browser

# Recent heart rate readings
ghealth data heart-rate list --from today --limit 10

# Daily step totals for a week
ghealth data steps daily-rollup --from 2026-03-22 --to 2026-03-29

# Sleep stages for the last five nights
ghealth data sleep list --limit 5 --detail

Step totals return aggregated JSON:

{
  "dataPoints": [
    {"date": "2026-03-28", "countSum": "9037"},
    {"date": "2026-03-27", "countSum": "2408"}
  ]
}

Output is simplified by default. Use --raw for the original API response. Use --format csv or --format table for other shapes. The -o flag writes a file and prints a schema preview.

Pagination is lossless. A large list returns a nextPageToken . You pass it back with --page-token to fetch the next page.

Use Cases With Examples

• Feed sleep patterns into an agent : Pull several nights with --detail . Pipe the JSON into a Claude Code or Codex session. Ask the agent to summarize deep-sleep trends over the week.

• Load workouts into pandas : Run ghealth data exercise export-tcx --id <id> --output ride.csv --as csv . Each row is one trackpoint with heart rate and GPS. Then run pd.read_csv on the file.

• Build a resting heart-rate view : Query daily-resting-heart-rate over 30 days. Emit CSV with --format csv . Chart it in a notebook or a dashboard.

How ghealth Compares

The table below sets ghealth against the raw API and two other CLIs. The other two CLIs both self-identify as unofficial.

Attribute

ghealth (this CLI)

Google Health API v4 (direct REST)

rudrankriyam/Google-Health-CLI

googlehealth-cli (npm)

Install

git clone

+

go build

None; call HTTP/gRPC yourself

Build from Go source

npm i -g googlehealth-cli

Language

Go, single binary

Any

Go

Node.js

Auth

Your own OAuth client, PKCE S256

Google OAuth 2.0

Your own OAuth client

Agent output

Simplified JSON, exit codes,

SKILL.md

Raw JSON / gRPC

Predictable JSON

Stable

--json

envelope

Data types

40 verified against live API

Full v4 surface

Tracks documented v4 surface

Subset of types

Official status

No; community, in Google-Health-API org

Yes; Google

No; states unofficial

No; states unaffiliated

For raw control, the direct REST API is the ground truth. For terminal and agent use, ghealth reduces auth and formatting boilerplate.

Interactive Explainer