The Google Health API, the official successor to the Fitbit Web API, now has a dedicated open-source command-line interface designed for terminal purists and AI agent workflows. Called ghealth, this single Go binary wraps the Google Health API v4 and exposes 40 verified data types as structured JSON, making it trivial to pipe sleep patterns, heart rate readings, and step counts directly into an agent’s context or a data pipeline.
The tool lives under the Google-Health-API GitHub organization, which also hosts long-standing Fitbit open-source repositories. It is built from source with a single go build -o ghealth .codecodecodecode command and ships as one self-contained binary under the Apache 2.0 license. Every command returns simplified JSON with a stable shape, deterministic exit codes, a --dry-runcodecodecodecode flag, and a --rawcodecodecodecode flag for the original API response. Two Agent Skills ship as SKILL.mdcodecodecodecode 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 addcodecodecodecode.
What Is ghealth? A Terminal-First Wrapper for Google Health API v4
ghealth is explicitly agent-first. The repository ships two Agent Skills as SKILL.mdcodecodecodecode 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 addcodecodecodecode. The tool is a wrapper over the Google Health API v4, built from source with go build -o ghealth .codecodecodecode and delivered as one self-contained binary.
The 40 Verified Data Types: What You Can Access
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.readonlycodecodecodecode scope. Each type supports a subset of operations. Common ones are listcodecodecodecode, rollupcodecodecodecode, daily-rollupcodecodecodecode, and reconcilecodecodecodecode. Writable types (exercise, sleep, weight, body-fat, height) add createcodecodecodecode, updatecodecodecodecode, and deletecodecodecodecode.
The reconcilecodecodecodecode operation merges overlapping data points from multiple sources, mirroring the Reconciled Stream in the v4 API. Sleep is a good example for pattern analysis. The default listcodecodecodecode returns a summary. Adding --detailcodecodecodecode returns stage-by-stage data (awake, deep, REM), which helps you spot patterns week over week.
Setup: What Actually Happens When You Run ghealth setup
Setup runs through one command: ghealth setupcodecodecodecode. 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/codecodecodecode with file mode 0600codecodecodecode. 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 and validates a random state parameter on completion.
Hands-On: Commands and Output in Practice
Reading data is consistent across types. Every read returns an object with rows under dataPointscodecodecodecode.
Recent heart rate readings:
ghealth data heart-rate list --from today --limit 10
prepreprepre
Daily step totals for a week:
ghealth data steps daily-rollup --from 2026-03-22 --to 2026-03-29
prepreprepre
Sleep stages for the last five nights:
ghealth data sleep list --limit 5 --detail
prepreprepre
Step totals return aggregated JSON like this:
{
"dataPoints": [
{"date": "2026-03-28", "countSum": "9037"},
{"date": "2026-03-27", "countSum": "2408"}
]
}
prepreprepre
Output is simplified by default. Use --rawcodecodecodecode for the original API response. Use --format csvcodecodecodecode or --format tablecodecodecodecode for other shapes. The -ocodecodecodecode flag writes a file and prints a schema preview. Pagination is lossless. A large list returns a nextPageTokencodecodecodecode, which you pass back with --page-tokencodecodecodecode to fetch the next page.
Use Cases With Examples
Feed sleep patterns into an agent: Pull several nights with --detailcodecodecodecode. 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 csvcodecodecodecode. Each row is one trackpoint with heart rate and GPS. Then run pd.read_csvcodecodecodecode on the file.
Build a resting heart-rate view: Query daily-resting-heart-ratecodecodecodecode over 30 days. Emit CSV with --format csvcodecodecodecode. Chart it in a notebook or a dashboard.
How ghealth Compares to Alternatives
| 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 | 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 significantly.
Who Should Use ghealth Now
ghealth is best suited for developers, data scientists, and AI practitioners who already work in terminal environments and want programmatic access to their Fitbit or Pixel Watch health data without wrangling OAuth flows and JSON parsing edge cases. It is equally useful for anyone building AI agent pipelines that need structured health metrics as context. The tool is not for casual users who prefer a GUI or for production applications that have already completed Google’s restricted-scope review process and need the full API surface.
For personal health-data exploration, agent prototyping, or lightweight dashboarding, ghealth delivers a clean, repeatable interface. The practical next step is to clone the repository, run ghealth setupcodecodecodecode with your own GCP OAuth credentials, and query your first data type. The tool’s deterministic output and agent skills make it ready to integrate from day one.
