{"slug": "the-google-health-api-got-a-cli-ghealth-is-an-open-source-tool-for-your-fitbit", "title": "The Google Health API Got a CLI: ghealth is an Open-Source Tool for Your Fitbit Air Data", "summary": "An open-source CLI tool called ghealth wraps the Google Health API v4, exposing 40 verified data types such as sleep, heart rate, and steps as structured JSON for use in terminals and AI agents. The tool, built as a single Go binary under Apache 2.0, provides agent-first features like deterministic exit codes and dry-run flags, and supports operations including list, rollup, and reconcile for health data from Fitbit and Pixel Watch.", "body_md": "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\n\n`ghealth`\n\nwraps 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.\n\n**What is ghealth?**\n\n`ghealth`\n\nis a wrapper over the Google Health API v4. You build it from source with `go build -o ghealth .`\n\n. It ships as one self-contained binary.\n\nThe tool is explicitly agent-first. Every command returns simplified JSON with a stable shape. It also provides deterministic exit codes, a `--dry-run`\n\nflag, and a `--raw`\n\nflag.\n\nThe repository ships two Agent Skills as `SKILL.md`\n\nfiles. 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`\n\n.\n\nThe CLI lives under the `Google-Health-API`\n\nGitHub organization. That organization also hosts long-standing Fitbit open-source repositories.\n\n**The Data Surface: 40 Verified Types**\n\nThe 40 types cover most Fitbit and Pixel Watch signals. Examples include `steps`\n\n, `heart-rate`\n\n, `sleep`\n\n, `weight`\n\n, `oxygen-saturation`\n\n, and `heart-rate-variability`\n\n. Clinical types like `electrocardiogram`\n\nrequire the `ecg.readonly`\n\nscope.\n\nEach type supports a subset of operations. Common ones are `list`\n\n, `rollup`\n\n, `daily-rollup`\n\n, and `reconcile`\n\n. Writable types (`exercise`\n\n, `sleep`\n\n, `weight`\n\n, `body-fat`\n\n, `height`\n\n) add `create`\n\n, `update`\n\n, and `delete`\n\n.\n\nThe `reconcile`\n\noperation merges overlapping data points from multiple sources. That mirrors the Reconciled Stream in the v4 API.\n\nSleep is a good example for pattern analysis. The default `list`\n\nreturns a summary. Adding `--detail`\n\nreturns stage-by-stage data (awake, deep, REM). That helps you spot patterns week over week.\n\n**Setup: What Actually Happens**\n\nSetup runs through one command: `ghealth setup`\n\n. A wizard walks you through the GCP project and OAuth. You create a Desktop-type OAuth client in the Google Cloud Console.\n\nYou bring your own OAuth credentials. The tool holds no shared key. Files are written under `~/.config/ghealth/`\n\nwith file mode 0600. Tokens refresh automatically.\n\nAll 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.\n\nThe headless flow uses PKCE with an S256 challenge. It also validates a random `state`\n\nparameter on completion.\n\n**Hands-On: Commands and Output**\n\nReading data is consistent across types. Every read returns an object with rows under `dataPoints`\n\n.\n\n```\n# Recent heart rate readings\nghealth data heart-rate list --from today --limit 10\n\n# Daily step totals for a week\nghealth data steps daily-rollup --from 2026-03-22 --to 2026-03-29\n\n# Sleep stages for the last five nights\nghealth data sleep list --limit 5 --detail\n```\n\nStep totals return aggregated JSON:\n\n```\n{\n  \"dataPoints\": [\n    {\"date\": \"2026-03-28\", \"countSum\": \"9037\"},\n    {\"date\": \"2026-03-27\", \"countSum\": \"2408\"}\n  ]\n}\n```\n\nOutput is simplified by default. Use `--raw`\n\nfor the original API response. Use `--format csv`\n\nor `--format table`\n\nfor other shapes. The `-o`\n\nflag writes a file and prints a schema preview.\n\nPagination is lossless. A large `list`\n\nreturns a `nextPageToken`\n\n. You pass it back with `--page-token`\n\nto fetch the next page.\n\n**Use Cases With Examples**\n\n**Feed sleep patterns into an agent**: Pull several nights with`--detail`\n\n. 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`\n\n. Each row is one trackpoint with heart rate and GPS. Then run`pd.read_csv`\n\non the file.**Build a resting heart-rate view**: Query`daily-resting-heart-rate`\n\nover 30 days. Emit CSV with`--format csv`\n\n. Chart it in a notebook or a dashboard.\n\n**How ghealth Compares**\n\nThe table below sets `ghealth`\n\nagainst the raw API and two other CLIs. The other two CLIs both self-identify as unofficial.\n\n| Attribute | ghealth (this CLI) | Google Health API v4 (direct REST) | rudrankriyam/Google-Health-CLI | googlehealth-cli (npm) |\n|---|---|---|---|---|\n| Install | `git clone` + `go build` | None; call HTTP/gRPC yourself | Build from Go source | `npm i -g googlehealth-cli` |\n| Language | Go, single binary | Any | Go | Node.js |\n| Auth | Your own OAuth client, PKCE S256 | Google OAuth 2.0 | Your own OAuth client | Your own OAuth client |\n| Agent output | Simplified JSON, exit codes, `SKILL.md` | Raw JSON / gRPC | Predictable JSON | Stable `--json` envelope |\n| Data types | 40 verified against live API | Full v4 surface | Tracks documented v4 surface | Subset of types |\n| Official status | No; community, in Google-Health-API org | Yes; Google | No; states unofficial | No; states unaffiliated |\n\nFor raw control, the direct REST API is the ground truth. For terminal and agent use, `ghealth`\n\nreduces auth and formatting boilerplate.\n\n**Interactive Explainer**\n\nCheck out the ** Repo**.\n\n**Also, feel free to follow us on**\n\n**and don’t forget to join our**[Twitter](https://x.com/intent/follow?screen_name=marktechpost)\n\n**and Subscribe to**\n\n[150k+ML SubReddit](https://www.reddit.com/r/machinelearningnews/)**. Wait! are you on telegram?**\n\n[our Newsletter](https://www.aidevsignals.com/)\n\n[now you can join us on telegram as well.](https://t.me/machinelearningresearchnews)Need to partner with us for promoting your GitHub Repo OR Hugging Face Page OR Product Release OR Webinar etc.? [Connect with us](https://forms.gle/wbash1wF6efRj8G58)\n\nMichal Sutter is a data science professional with a Master of Science in Data Science from the University of Padova. With a solid foundation in statistical analysis, machine learning, and data engineering, Michal excels at transforming complex datasets into actionable insights.\n\n- Michal Sutter\n- Michal Sutter\n- Michal Sutter\n- Michal Sutter\n- Michal Sutter\n- Michal Sutter", "url": "https://wpnews.pro/news/the-google-health-api-got-a-cli-ghealth-is-an-open-source-tool-for-your-fitbit", "canonical_source": "https://www.marktechpost.com/2026/07/02/the-google-health-api-got-a-cli-ghealth-is-an-open-source-tool-for-your-fitbit-air-data/", "published_at": "2026-07-02 08:46:56+00:00", "updated_at": "2026-07-03 21:43:25.969872+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["Google Health API", "Fitbit", "Pixel Watch", "Google OAuth 2.0", "Apache 2.0", "Google Cloud Console", "Claude Code", "Codex"], "alternates": {"html": "https://wpnews.pro/news/the-google-health-api-got-a-cli-ghealth-is-an-open-source-tool-for-your-fitbit", "markdown": "https://wpnews.pro/news/the-google-health-api-got-a-cli-ghealth-is-an-open-source-tool-for-your-fitbit.md", "text": "https://wpnews.pro/news/the-google-health-api-got-a-cli-ghealth-is-an-open-source-tool-for-your-fitbit.txt", "jsonld": "https://wpnews.pro/news/the-google-health-api-got-a-cli-ghealth-is-an-open-source-tool-for-your-fitbit.jsonld"}}