Michael H

Posted on Oct 13 Originally published at agent5.news

ghealth Explained: The Open-Source Google Health API CLI

#ai #machinelearning #ghealth #googlehealthapi

Originally published on agent5.news.

ghealth is an open-source command-line tool from Google that reads your Fitbit and Pixel Watch data through the Google Health API, the service that replaces the Fitbit Web API. You type a short command in a terminal (the text window where commands run) and get your steps, sleep or heart rate back as structured text. This guide covers who made ghealth, why the Fitbit Web API is going away, installation and sign-in, the main commands, use by AI agents, the data it reaches, and the privacy questions to settle first. All facts were checked on October 12, 2026.

What is ghealth, and who made it?

ghealth is the short name of the Google Health CLI, and it is an official Google project, not a community one. A CLI (command-line interface) is a program you run by typing commands instead of clicking buttons.

The evidence is public:

The Google Health team announced it on July 1, 2026 in the Google Health help community and described it as "designed with agent use in mind."
Google's developer documentation lists it as the command-line tool for the Health API, on a page last updated on September 30, 2026.
The code sits in the Google-Health-API organization on GitHub, next to older Fitbit open-source projects. The files carry a Google LLC copyright notice and the Apache 2.0 open-source license, which lets anyone use and change the code at no charge.

As of October 12, 2026 the repository (the public code folder) shows 267 stars (bookmarks from users) and no tagged release, meaning no packaged version. The code gives its version as 0.1.0, and the latest change is dated July 9, 2026.

Some early coverage listed the tool as a community project, and there are similarly named third-party tools that describe themselves as unofficial. For the Google Health API CLI from Google itself, check that the repository path reads Google-Health-API/google-health-cli.

What is the Google Health API, and why is the Fitbit Web API being replaced?

The Google Health API is Google's Fitbit Web API replacement: the interface apps use to read and write health data from Fitbit devices and Pixel Watches, with the user's consent. An API (application programming interface) is the channel one program uses to ask another for data. Google launched this one on March 24, 2026.

Google says it rebuilt the old Fitbit service on its own infrastructure. Two documented changes stand out:

More than 100 old endpoints (the addresses a program requests data from) became a smaller set of data types.
Sign-in moved from Fitbit's own system to Google OAuth 2.0, the standard way to give an app limited account access without sharing a password.

The old service follows a fixed schedule:

September 30, 2026: support for the Fitbit Web API ended. It still runs, but Google no longer fixes bugs.
October 30, 2026: the Fitbit Web API is turned off and stops syncing data.

Fitbit devices and Pixel Watches, current and older, feed the new API, except Fitbit Ace devices.

How do you install ghealth and sign in?

There is no installer or app store download yet. A ghealth install means building the program from its source code, then running a setup wizard that links it to a Google Cloud project (Google's container for API access) that you create yourself.

You need Go 1.23 or later (Go is a programming language) and Git to copy the code. The README, the project's instruction page, gives three commands:

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

The result is a single program file named ghealth. Before the first run, prepare three things:

Sign in to the Google Health mobile app with the Google account you plan to use. Google's setup guide requires this before any app can connect.
In the Google Cloud console, create a project, switch on the Google Health API, and create an OAuth client ID with the application type Desktop app. Download its JSON file, a small file of structured text.
Add your own email address to the project's test users list. Google's guide says new OAuth clients start unverified, are capped at 100 users, and work only for accounts on that list.

Then run the wizard:

ghealth setup

It asks for the project ID and the JSON file, lets you choose scopes (named permissions, such as reading sleep data), and opens a browser where you click Allow. The default is every read-only scope.

ghealth saves its files under ~/.config/ghealth/. One of them, credentials.json, holds your access and refresh tokens (digital keys that prove your consent) as plain text, readable only by your user account. The tokens refresh on their own.

Two caveats:

Google's setup guide says refresh tokens for a project in Testing status expire after 7 days, so expect to sign in again about once a week.
A notice across Google's Health API documentation says Google is "not onboarding new projects at this time." It does not say what that means for a personal project, so setup may stop here.

What are the main ghealth commands?

Almost every command follows one pattern: ghealth data, then a data type, then an operation. Results come back as JSON, a structured text format.

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 one total per day. Use it for steps and distance, because list returns time intervals without counts for those types.
list returns individual readings or sessions, up to 500 rows by default.
--detail adds a stage-by-stage breakdown to sleep sessions.
schema types shows every data type and the operations it supports.

Three options change the output:

--format table or --format csv prints aligned columns or CSV, the plain format spreadsheets open.
-o with a file name writes the data to that file and prints only a short summary.
--dry-run shows the request without sending it.

This command saves a week of daily step totals as a CSV file:

ghealth data steps daily-rollup --from 2026-03-24 --to 2026-03-30 --format csv -o steps.csv

One trap from the README: a day missing from a rollup means the device was not worn or did not sync. It is not a zero.

How can an AI agent use ghealth?

An AI agent (a model that runs tools in a loop until a task is done) uses the ghealth CLI the way a person does: it runs commands and reads the output. Three design choices help:

Skills. The repository ships two agent skills, instruction files named SKILL.md that teach an agent how to use a tool. One covers setup and sign-in, the other the 40 data types and their pitfalls. The command below installs both.
Predictable output. Every read has the same JSON shape, with rows under dataPoints. Errors are JSON too, and six exit codes (the number a program returns when it ends), 0 to 5, signal success or the type of failure.
Less data in the conversation. With -o, the agent sees only the row count, the column names and a three-row preview. The full data stays in the file.

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

The repository's guide for agents names Claude Code and Codex among its main users. The model never contacts Google itself. Its harness does: the software around the model that runs commands and passes results back, covered in our explainer on what an agent harness is.

Google's announcement suggests a daily sync of sleep and recovery trends as one use. That suits an agent loop with memory, where the agent keeps notes between runs. One step stays human: a person has to click Allow in a browser before any data flows.

What data can ghealth reach, and what can it not?

ghealth can reach 40 data types from the Google account you signed in with, limited to what your devices have synced to Google Health.

Activity: steps, distance, floors, active minutes, calories, and exercise sessions with their GPS tracks.
Heart and vitals: heart rate, resting heart rate, heart rate variability (HRV), blood oxygen, breathing rate and VO2 max (a fitness measure). ECG (a recording of the heart's electrical activity) and irregular rhythm alerts need their own scopes.
Sleep: sessions with sleep stages, plus nightly temperature deviation.
Body and nutrition: weight, body fat, height, food and water logs, blood glucose and core body temperature.

The device matters. Take the Fitbit Air, the screenless band Google announced on May 7, 2026, starting at $99.99. Google's compatibility table lists 23 data types for it, including steps, heart rate, sleep, blood oxygen and HRV. ECG is not among them, and Ars Technica's review of June 5, 2026 also notes the Air has none.

Five types can also be written: exercise, sleep, weight, body fat and height. Treat that part as unfinished, because the tool's built-in scope list still uses the write scope names Google replaced on May 26, 2026.

What ghealth cannot reach, as of October 12, 2026:

Newer data types. Women's health types added on August 17, 2026 and a skin temperature type still in preview are not among the 40.
Blood pressure. It is not on the list. A feature request has been open since August 20, 2026.
App features. The readiness score, chats with the Health Coach (the AI coach in the Google Health app) and uploaded medical records do not appear as data types.
Long ranges. One rollup covers at most 90 days, or 14 for heart rate and three other types.

For a one-time Fitbit Air data export you do not need ghealth: Google's blog names Google Takeout, its account download tool, for a full copy. ghealth is for repeated, automated access.

What should you check before giving an AI agent your health data?

Settle three things first: which permissions the tool gets, where the tokens are stored, and which AI model will see the numbers.

Grant less than the default. The wizard's default is all nine read-only scopes, which include exercise GPS location, ECG and irregular rhythm alerts. You can pick a narrower set. With write scopes, an agent could also add or delete entries.
Protect the token file. An agent that runs commands as you can read credentials.json, and ghealth auth export prints the tokens. Keep them out of chat logs, shared folders and code repositories.
Know where the model runs. Google says Google Health data is not used for Google Ads, and The Verge reports that using it to train Google's AI is off unless you opt in. Those commitments cover Google's services. Once ghealth prints your numbers into an agent's session, that agent provider's terms apply, and a cloud model receives the data on its servers. Our explainer on why some systems keep personal data on the device explains the difference.
Know how to stop. ghealth auth logout deletes the stored tokens on your machine. Google's scope guide says users can also revoke an app's access in their Google Account.

If the goal is Fitbit data for AI agents, start with one read-only category such as sleep and widen it later. An agent can summarize numbers. Its summary is not a medical diagnosis.

What happens next

October 30, 2026: the Fitbit Web API is turned off. Google's timeline says the old service stops working and syncing that day, so scripts and apps that were never moved will stop returning data. ghealth is not affected, because it already uses the new API.

The preview channel and new data types. Google opened a public preview channel named v4beta on October 1, 2026, and its roadmap for the fourth quarter of 2026 lists more data types, including granular skin temperature. A pull request (a proposed code change) opened on October 8, 2026 would let ghealth use that channel. The repository has had no new changes since July 9, 2026, so watch whether it is merged.

Access and a first release. Google says it will post updates as it opens the API to more developers, so check that notice before you spend time on setup. A first tagged release and a fix for the write scope names are the other changes to look for. We follow these in our running news on AI agents and products.

DEV Community