ghealth Explained: Google Health API's Official Open-Source CLI Tool

Title

ghealth Explained: Google Health API's Official Open-Source CLI Tool

Meta Description

ghealth is Google's official open-source CLI for the Health API, supporting Fitbit and Pixel Watch data with AI agents in mind. This guide covers install, config, core commands, 40 data types, privacy risks, and migration after the Fitbit Web API shutdown.

Article Content

The Fitbit Web API will shut down completely on October 30, 2026, and every script and third-party app still relying on the old interface will stop receiving data. Google's replacement is the Google Health API, and around it there is an official open-source command-line tool called ghealth. It isn't just a debugger for developers — it's an interface layer designed for AI agents to read health data.

What Is ghealth, and Who Builds It?

ghealth is short for Google Health CLI and belongs to an official Google project, not a community effort. According to an announcement from the Google Health team on July 1, 2026, it is explicitly positioned as "designed for agent use." The code is hosted on GitHub under the Google-Health-API organization, alongside earlier Fitbit open-source projects, with files bearing the Google LLC copyright notice and the Apache 2.0 license.

As of October 12, 2026, the repository has 267 stars, no tagged release yet, a version number of 0.1.0, and a last commit on July 9. Some early coverage mislabeled it as a community project. The way to tell is simple: confirm the repo path is Google-Health-API/google-health-cli.

Why Replace the Fitbit Web API with the Google Health API?

The Google Health API launched on March 24, 2026, and is the official replacement for the Fitbit Web API. Google describes it as the old Fitbit service rebuilt on its own infrastructure, with two core changes worth noting: more than 100 legacy endpoints were consolidated into fewer data types, and login moved from Fitbit's own system to Google OAuth 2.0.

The retirement schedule for the old service is hard: support ends on September 30, 2026 (it still runs but no bugs are fixed), and it officially shuts down on October 30, halting data sync. Current and older Fitbit devices and the Pixel Watch all support the new API, with the only exception being the Fitbit Ace series.

How OAuth 2.0 differs from the old login system: The Fitbit Web API used a homegrown OAuth 1.0a/2.0 hybrid auth, with tokens issued by the Fitbit domain, and third-party apps had to register separately and follow Fitbit's permission model. After migrating to Google OAuth 2.0, the authorization principal shifts from a Fitbit account to a Google account, scopes are managed centrally by Google, and the token refresh mechanism, revocation entry point (the "Third-party apps & services" page in a Google account), and test user list all follow the standard process of a Google Cloud project. For users, this means no more separate Fitbit account authorization step; for developers, it means you must create your own Google Cloud project, enable the API, and configure an OAuth client. The onboarding barrier shifts from "register an app" to "configure a cloud project" — which is why ghealth requires running the setup wizard first.

The semantic difference between daily-rollup and list: daily-rollup returns per-day aggregated summary values, with the Google Health API doing day-level rollup on the server, suited to cumulative metrics like steps, distance, and calories; list returns raw data points or sessions, each dataPoint carrying its own timestamp and metadata, suited to high-frequency sampled data like heart rate and HRV. The two are not different views of the same data — the aggregation definition is set API-side, so summing a list yourself may not match the daily-rollup result. Understanding this distinction is a prerequisite for avoiding statistical errors.

How Do You Install ghealth and Complete Login?

There is currently no installer or app store download. Installing means building from source, then running a configuration wizard to bind the Google Cloud project you create yourself. You need Go 1.23 or later and Git:

git clone https://github.com/Google-Health-API/google-health-cli.git
cd google-health-cli
go build -o ghealth .

Before the first run, prepare three things: log in to the Google Health mobile app with the target Google account; in the Google Cloud console, create a project, enable the Google Health API, create an OAuth client ID of the desktop app type, and download the JSON file; and add your own email to the project's test user list.

Then run the ghealth setup wizard, enter the project ID and JSON file, choose scopes, and click Allow in the browser. All read-only scopes are checked by default. Credential files are stored under ~/.config/ghealth/, where credentials.json stores the access and refresh tokens in plaintext.

Two key caveats: refresh tokens for projects in testing status expire after 7 days, requiring weekly re-login; and a note in Google's documentation states that "new project access is not currently accepted," though it's unclear whether personal projects are affected.

Main Commands and Data Operations

Nearly all commands follow the same pattern: ghealth data + data type + operation. Results are returned as JSON.

ghealth data steps daily-rollup --from 2026-03-22 --to 2026-03-29
ghealth data heart-rate list --from today --limit 10
ghealth data sleep list --limit 5 --detail
ghealth schema types

daily-rollup returns daily summary values, good for steps and distance; list returns individual readings or sessions, capped at 500 rows by default; --detail adds stage-level breakdown for sleep sessions; schema types lists all data types and their supported operations.

Output can be switched with --format table or --format csv, -o writes data to a file and prints only a summary, and --dry-run shows the request without sending it. A common trap: a missing day in a rollup means the device wasn't worn or didn't sync — not that the value was zero.

How Do AI Agents Call ghealth?

ghealth offers three conveniences designed for agents: the repo ships with two SKILL.md skill files, covering configuration/login and the pitfalls of 40 data types respectively; all reads return a unified JSON structure with row data under dataPoints, errors are also JSON, and 6 exit codes (0-5) identify success or failure types; and when using -o, the agent sees only the row count, column names, and a three-row preview, with full data left in the file.

npx skills add https://github.com/Google-Health-API/google-health-cli

The repo's agent guide lists Claude Code and Codex as the primary users. The model itself never contacts Google directly — it's the agent framework that executes commands and returns results. Google's announcement suggests one daily use case: syncing sleep and recovery trends daily, which suits an agent loop with memory. The only step that requires human involvement is clicking Allow in the browser.

SKILL.md and the skills ecosystem: SKILL.md is the de facto descriptor file for agent skill packages, using natural language plus examples to explain how a class of tasks should call tools and what common errors exist. The ghealth repo ships with two SKILL.md files, one for "configuration and login" and one for "query pitfalls across 40 data types," and the npx skills add command registers them into agent frameworks that support the convention (such as Claude Code and Codex). This means the model doesn't need to hardcode ghealth usage into its prompt; it loads the skill files on demand for context, reducing the prompt overhead of each call.

Exit codes and structured errors: The CLI's 6 exit codes (0-5) represent different failure types: success, argument error, authentication failure, network error, API-returned error, and rate limiting, among others. Because errors are also output as JSON, an agent can branch on exit codes while also using JSON fields to retry or degrade, without parsing human-readable error text. This "exit code + JSON" dual-channel design is a key characteristic of ghealth being aimed at automation rather than interactive use.

What Data Can ghealth Read, and What Can't It Read?

ghealth can access 40 data types, with scope depending on what the device has synced to Google Health. Activity covers steps, distance, floors, active minutes, calories, and exercise records with GPS tracks; heart and vitals include heart rate, resting heart rate, HRV, blood oxygen, respiratory rate, and VO2 max, with ECG and irregular rhythm notifications requiring separate authorization; sleep includes staged sessions and nightly temperature deviation; body and nutrition cover weight, body fat, height, food logging, blood glucose, and core body temperature.

Device differences are significant. The Fitbit Air, a screenless band, lists 23 data types in its compatibility table, excluding ECG. Five types support writing: exercise, sleep, weight, body fat, and height, but this functionality is incomplete, and the built-in scope list still uses write permission names that Google replaced on May 26.

What's inaccessible includes: women's health types and the preview skin temperature type, blood pressure (a feature request open since August 20), app features like readiness score and Health Coach conversations, and long-range queries beyond 90 days (types like heart rate are limited to 14 days). If you need a one-time export of Fitbit Air data, Google Takeout is more suitable; ghealth is positioned for repetitive, automated access.

What Should You Confirm Before Handing Health Data to an AI Agent?

Three questions must be resolved in advance: permission scopes, where tokens are stored, and which AI model will see the data. The configuration wizard checks all nine read-only scopes by default, including exercise GPS location, ECG, and irregular rhythm notifications, and you can narrow them manually. Once write scopes are enabled, agents can also add or delete records.

The token file needs special protection: an agent running commands as you can read credentials.json, and ghealth auth export prints the token directly. Avoid letting it appear in chat logs, shared folders, and code repositories.

The data flow also needs to be clear. Google states health data is not used for advertising, nor for training its AI unless you actively opt in. But these promises only cover Google's own services. Once ghealth prints data into an agent session, that agent provider's terms apply, and a cloud model receives the data on its servers. To stop: ghealth auth logout deletes the local token, and you can also revoke app access in your Google account.

If the goal is to have an AI agent process Fitbit data, start with one read-only category like sleep, then expand gradually. An agent can summarize numbers, but its summary is not a medical diagnosis.

What Future Changes Are Worth Watching

After the Fitbit Web API shuts down on October 30, 2026, unmigrated scripts and apps will stop returning data; ghealth is unaffected because it already uses the new API. On October 1, Google opened a public preview channel called v4beta, and the Q4 roadmap lists more data types including fine-grained skin temperature. On October 8, someone submitted a pull request to make ghealth use that channel, but the repo has had no new changes since July 9, so whether it gets merged is worth watching.

Two other observation points: Google says it will gradually open the API to more developers, so before investing time in configuration you should confirm the status of that notice; and the first tagged release and the write permission name fix are also important signals.

FAQ

Is ghealth free? Yes. The Apache 2.0 license allows anyone to use and modify the code for free.

How is ghealth different from the official Fitbit app? ghealth is a command-line tool aimed at automated access for developers and AI agents, not a daily app for ordinary users.

What devices do I need to use it? Current and older Fitbit devices and the Pixel Watch work, except the Fitbit Ace series.

Is the data safe? Tokens are stored locally in plaintext, readable by any process running as you. The core risk is that once data enters a cloud AI agent's session, it's governed by that provider's terms.

One-line Summary

Google's official open-source CLI tool ghealth gives AI agents access to the Google Health API, replacing the soon-to-shut-down Fitbit Web API.

Paragraph Summary

The Fitbit Web API shuts down completely on October 30, 2026, and Google's replacement is the Google Health API, paired with the official open-source command-line tool ghealth. ghealth is hosted under the Google-Health-API organization, uses the Apache 2.0 license, and is explicitly positioned as "designed for agent use." Installing requires building from source (Go 1.23+) and completing OAuth login via your own Google Cloud project, with tokens expiring after 7 days in testing status. The tool can access 40 data types, but device differences are significant, write functionality is incomplete, and blood pressure, women's health types, and others are out of scope. The article also warns you to narrow permission scopes before use, protect plaintext tokens, and clarify that cloud AI model data handling falls under third-party terms.