{"id":61812,"date":"2026-07-02T15:04:29","date_gmt":"2026-07-02T19:04:29","guid":{"rendered":"https:\/\/overcentral.com\/en\/?p=61812"},"modified":"2026-07-02T15:04:30","modified_gmt":"2026-07-02T19:04:30","slug":"ghealth-cli-google-health-api","status":"publish","type":"post","link":"https:\/\/overcentral.com\/en\/ghealth-cli-google-health-api\/","title":{"rendered":"ghealth CLI Exposes 40 Google Health API Data Types for Terminals"},"content":{"rendered":"

The Google Health API<\/a>, 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<\/strong>, 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.<\/p>\n

The tool lives under the Google-Health-API GitHub<\/a> organization, which also hosts long-standing Fitbit open-source repositories. It is built from source with a single go build -o ghealth .<\/code>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-run<\/code>codecodecodecode flag, and a --raw<\/code>codecodecodecode flag for the original API response. Two Agent Skills ship as SKILL.md<\/code>codecodecodecode 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<\/code>codecodecodecode.<\/p>\n

What Is ghealth? A Terminal-First Wrapper for Google Health API v4<\/h2>\n

ghealth is explicitly agent-first. The repository ships two Agent Skills as SKILL.md<\/code>codecodecodecode 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<\/code>codecodecodecode. The tool is a wrapper over the Google Health API v4, built from source with go build -o ghealth .<\/code>codecodecodecode and delivered as one self-contained binary.<\/p>\n

The 40 Verified Data Types: What You Can Access<\/h2>\n

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<\/code>codecodecodecode scope. Each type supports a subset of operations. Common ones are list<\/code>codecodecodecode, rollup<\/code>codecodecodecode, daily-rollup<\/code>codecodecodecode, and reconcile<\/code>codecodecodecode. Writable types (exercise, sleep, weight, body-fat, height) add create<\/code>codecodecodecode, update<\/code>codecodecodecode, and delete<\/code>codecodecodecode.<\/p>\n

The reconcile<\/code>codecodecodecode 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 list<\/code>codecodecodecode returns a summary. Adding --detail<\/code>codecodecodecode returns stage-by-stage data (awake, deep, REM), which helps you spot patterns week over week.<\/p>\n

Setup: What Actually Happens When You Run ghealth setup<\/code><\/h2>\n

Setup runs through one command: ghealth setup<\/code>codecodecodecode. A wizard walks you through the GCP project and OAuth<\/a>. 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\/<\/code>codecodecodecode with file mode 0600<\/code>codecodecodecode. Tokens refresh automatically.<\/p>\n

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.<\/p>\n

Hands-On: Commands and Output in Practice<\/h2>\n

Reading data is consistent across types. Every read returns an object with rows under dataPoints<\/code>codecodecodecode.<\/p>\n

Recent heart rate readings:<\/strong><\/p>\n

\nghealth data heart-rate list --from today --limit 10\n<\/pre>\n
prepreprepre<\/p>\n
Daily step totals for a week:<\/strong><\/p>\n
\nghealth data steps daily-rollup --from 2026-03-22 --to 2026-03-29\n<\/pre>\n
prepreprepre<\/p>\n
Sleep stages for the last five nights:<\/strong><\/p>\n
\nghealth data sleep list --limit 5 --detail\n<\/pre>\n
prepreprepre<\/p>\n
Step totals return aggregated JSON like this:<\/p>\n
\n{\n  \"dataPoints\": [\n    {\"date\": \"2026-03-28\", \"countSum\": \"9037\"},\n    {\"date\": \"2026-03-27\", \"countSum\": \"2408\"}\n  ]\n}\n<\/pre>\n
prepreprepre<\/p>\n
Output is simplified by default. Use --raw<\/code>codecodecodecode for the original API response. Use --format csv<\/code>codecodecodecode or --format table<\/code>codecodecodecode for other shapes. The -o<\/code>codecodecodecode flag writes a file and prints a schema preview. Pagination is lossless. A large list returns a nextPageToken<\/code>codecodecodecode, which you pass back with --page-token<\/code>codecodecodecode to fetch the next page.<\/p>\n
Use Cases With Examples<\/h2>\n
Feed sleep patterns into an agent:<\/strong> Pull several nights with --detail<\/code>codecodecodecode. Pipe the JSON into a Claude Code<\/a> or Codex session. Ask the agent to summarize deep-sleep trends over the week.<\/p>\n
Load workouts into pandas:<\/strong> Run ghealth data exercise export-tcx --id <id> --output ride.csv --as csv<\/code>codecodecodecode. Each row is one trackpoint with heart rate and GPS. Then run pd.read_csv<\/code>codecodecodecode on the file.<\/p>\n
Build a resting heart-rate view:<\/strong> Query daily-resting-heart-rate<\/code>codecodecodecode over 30 days. Emit CSV with --format csv<\/code>codecodecodecode. Chart it in a notebook or a dashboard.<\/p>\n
How ghealth Compares to Alternatives<\/h2>\n\n\n\n\n\n\n\n\n
Attribute<\/th>\nghealth (this CLI)<\/th>\nGoogle Health API v4 (direct REST)<\/th>\nrudrankriyam\/Google-Health-CLI<\/th>\ngooglehealth-cli (npm)<\/th>\n<\/tr>\n
Install<\/td>\ngit clone + go build<\/td>\nNone; call HTTP\/gRPC yourself<\/td>\nBuild from Go source<\/td>\nnpm i -g googlehealth-cli<\/td>\n<\/tr>\n
Language<\/td>\nGo, single binary<\/td>\nAny<\/td>\nGo<\/td>\nNode.js<\/td>\n<\/tr>\n
Auth<\/td>\nYour own OAuth client, PKCE S256<\/td>\nGoogle OAuth 2.0<\/td>\nYour own OAuth client<\/td>\nYour own OAuth client<\/td>\n<\/tr>\n
Agent output<\/td>\nSimplified JSON, exit codes, SKILL.md<\/td>\nRaw JSON \/ gRPC<\/td>\nPredictable JSON<\/td>\nStable –json envelope<\/td>\n<\/tr>\n
Data types<\/td>\n40 verified against live API<\/td>\nFull v4 surface<\/td>\nTracks documented v4 surface<\/td>\nSubset of types<\/td>\n<\/tr>\n
Official status<\/td>\nNo; community, in Google-Health-API org<\/td>\nYes; Google<\/td>\nNo; states unofficial<\/td>\nNo; states unaffiliated<\/td>\n<\/tr>\n<\/table>\n
For raw control, the direct REST API is the ground truth. For terminal and agent use, ghealth reduces auth and formatting boilerplate significantly.<\/p>\n
Who Should Use ghealth Now<\/h2>\n
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.<\/p>\n
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 setup<\/code>codecodecodecode 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.<\/p>\n","protected":false},"excerpt":{"rendered":"
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, […]<\/p>\n","protected":false},"author":7,"featured_media":94797,"comment_status":"closed","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"fifu_image_url":"https:\/\/cards.overcentral.com\/cards\/en\/61812.png","fifu_image_alt":"ghealth CLI Exposes 40 Google Health API Data Types for Terminals","footnotes":""},"categories":[349],"tags":[],"class_list":["post-61812","post","type-post","status-publish","format-standard","has-post-thumbnail","category-articles"],"fifu_image_url":"https:\/\/cards.overcentral.com\/cards\/en\/61812.png","fifu_image_alt":"ghealth CLI Exposes 40 Google Health API Data Types for Terminals","_links":{"self":[{"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/posts\/61812","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/users\/7"}],"replies":[{"embeddable":true,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/comments?post=61812"}],"version-history":[{"count":0,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/posts\/61812\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/media\/94797"}],"wp:attachment":[{"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/media?parent=61812"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/categories?post=61812"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/tags?post=61812"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}