The Google Well being API Obtained a CLI: ghealth is an Open-Supply Software for Your Fitbit Air Information

The Google Well being API is the official successor to the Fitbit Internet API. It targets the Google Well being API v4 and strikes builders onto Google OAuth 2.0. Now an open-source CLI command-line instrument known as ghealth wraps that API for terminals and AI brokers.

The instrument is a single Go binary beneath the Apache 2.0 license. It exposes 40 verified knowledge varieties as structured JSON. That design helps you to pipe sleep, coronary heart price, and step knowledge into an agent’s context.

What’s ghealth?

ghealth is a wrapper over the Google Well being API v4. You construct it from supply with go construct -o ghealth .. It ships as one self-contained binary.

The instrument is explicitly agent-first. Each command returns simplified JSON with a secure form. It additionally supplies deterministic exit codes, a --dry-run flag, and a --raw flag.

The repository ships two Agent Abilities as SKILL.md recordsdata. One covers auth, setup, and international flags. The opposite paperwork all 40 knowledge varieties, operations, patterns, and gotchas. Brokers set up them with npx expertise add.

The CLI lives beneath the Google-Well being-API GitHub group. That group additionally hosts long-standing Fitbit open-source repositories.

The Information Floor: 40 Verified Varieties

The 40 varieties cowl most Fitbit and Pixel Watch alerts. Examples embrace steps, heart-rate, sleep, weight, oxygen-saturation, and heart-rate-variability. Medical varieties like electrocardiogram require the ecg.readonly scope.

Every sort helps a subset of operations. Widespread ones are listing, rollup, daily-rollup, and reconcile. Writable varieties (train, sleep, weight, body-fat, peak) add create, replace, and delete.

The reconcile operation merges overlapping knowledge factors from a number of sources. That mirrors the Reconciled Stream within the v4 API.

Sleep is an effective instance for sample evaluation. The default listing returns a abstract. Including --detail returns stage-by-stage knowledge (awake, deep, REM). That helps you see patterns week over week.

Setup: What Truly Occurs

Setup runs by means of one command: ghealth setup. A wizard walks you thru the GCP undertaking and OAuth. You create a Desktop-type OAuth consumer within the Google Cloud Console.

You carry your personal OAuth credentials. The instrument holds no shared key. Recordsdata are written beneath ~/.config/ghealth/ with file mode 0600. Tokens refresh mechanically.

All Google Well being API scopes are categorized as Restricted. Google requires a privateness and safety evaluation for manufacturing entry. For private use, you authorize your personal undertaking in opposition to your personal account. The API returns knowledge from Fitbit, Pixel Watch, and related third-party sources.

The headless move makes use of PKCE with an S256 problem. It additionally validates a random state parameter on completion.

Arms-On: Instructions and Output

Studying knowledge is constant throughout varieties. Each learn returns an object with rows beneath dataPoints.

# Latest coronary heart price readings
ghealth knowledge heart-rate listing --from in the present day --limit 10

# Day by day step totals for every week
ghealth knowledge steps daily-rollup --from 2026-03-22 --to 2026-03-29

# Sleep phases for the final 5 nights
ghealth knowledge sleep listing --limit 5 --detail

Step totals return aggregated JSON:

{
  "dataPoints": [
    {"date": "2026-03-28", "countSum": "9037"},
    {"date": "2026-03-27", "countSum": "2408"}
  ]
}

Output is simplified by default. Use --raw for the unique API response. Use --format csv or --format desk for different shapes. The -o flag writes a file and prints a schema preview.

Pagination is lossless. A big listing returns a nextPageToken. You go it again with --page-token to fetch the subsequent web page.

Use Circumstances With Examples

Feed sleep patterns into an agent: Pull a number of nights with --detail. Pipe the JSON right into a Claude Code or Codex session. Ask the agent to summarize deep-sleep traits over the week.
Load exercises into pandas: Run ghealth knowledge train export-tcx --id --output experience.csv --as csv. Every row is one trackpoint with coronary heart price and GPS. Then run pd.read_csv on the file.
Construct a resting heart-rate view: Question daily-resting-heart-rate over 30 days. Emit CSV with --format csv. Chart it in a pocket book or a dashboard.

How ghealth Compares

The desk beneath units ghealth in opposition to the uncooked API and two different CLIs. The opposite two CLIs each self-identify as unofficial.

Attribute	ghealth (this CLI)	Google Well being API v4 (direct REST)	rudrankriyam/Google-Well being-CLI	googlehealth-cli (npm)
Set up	`git clone` + `go construct`	None; name HTTP/gRPC your self	Construct from Go supply	`npm i -g googlehealth-cli`
Language	Go, single binary	Any	Go	Node.js
Auth	Your individual OAuth consumer, PKCE S256	Google OAuth 2.0	Your individual OAuth consumer	Your individual OAuth consumer
Agent output	Simplified JSON, exit codes, `SKILL.md`	Uncooked JSON / gRPC	Predictable JSON	Secure `--json` envelope
Information varieties	40 verified in opposition to stay API	Full v4 floor	Tracks documented v4 floor	Subset of varieties
Official standing	No; group, in Google-Well being-API org	Sure; Google	No; states unofficial	No; states unaffiliated

For uncooked management, the direct REST API is the bottom fact. For terminal and agent use, ghealth reduces auth and formatting boilerplate.

Interactive Explainer

ghealth knowledge “+esc(sort)+’ ‘+esc(op); if(op===’listing’){ html += ‘ –from in the present day’; html += ‘ –limit ‘+esc(restrict); if(sort===’sleep’ && element) html += ‘ –detail‘; } else if(op===’daily-rollup’){ html += ‘ –from 2026-03-26 –to 2026-03-29′; } if(fmt!==’json’) html += ‘ –format ‘+esc(fmt); return html; } perform plainCmd(sort, op, fmt, element, restrict){ var s=”ghealth knowledge “+sort+’ ‘+op; if(op===’listing’){s+=’ –from in the present day –limit ‘+restrict;if(sort===’sleep’&&element)s+=’ –detail’;} else if(op===’daily-rollup’){s+=’ –from 2026-03-26 –to 2026-03-29′;} if(fmt!==’json’) s+=’ –format ‘+fmt; return s; } // —- notes —- perform noteFor(sort, op){ if(sort===’steps’ && op===’listing’) return ‘Word: <code>steps listing</code> returns minute intervals with no counts. Use <code>daily-rollup</code> to get actual totals (<code>countSum</code>).’; if(op===’daily-rollup’) return ‘Word: a lacking date means the machine was not worn — not a zero. A <code>countSum</code> of “0” is a real zero.’; if(sort===’sleep’) return ‘Word: default output is a abstract. Add <code>--detail</code> for per-stage minutes (awake, deep, REM, mild).’; return ‘Word: reads return an object with rows beneath <code>dataPoints</code>. Add <code>--raw</code> for the unique API response.’; } // —- wiring —- perform refreshOps(){ var sort = $(‘ghp-type’).worth; var ops = OPS[type]; var sel = $(‘ghp-op’); var prev = sel.worth; sel.innerHTML = ”; ops.forEach(perform(o){ var choose = doc.createElement(‘choice’); choose.worth = o; choose.textContent = o + (o===’listing’?’ (default)’:”); sel.appendChild(choose); }); if(ops.indexOf(prev)>=0) sel.worth = prev; } perform syncDetail(){ var sort = $(‘ghp-type’).worth, op = $(‘ghp-op’).worth; var wrap = $(‘ghp-detail-wrap’); var enabled = (sort===’sleep’ && op===’listing’); wrap.classList.toggle(‘ghp-disabled’, !enabled); $(‘ghp-detail’).disabled = !enabled; if(!enabled) $(‘ghp-detail’).checked = false; } perform postHeight(){ strive{ var h = root.offsetHeight + 40; // element’s personal offsetHeight + 40 (by no means scrollHeight) mum or dad.postMessage({sort:’ghealth-resize’, peak:h}, ‘*’); }catch(e){} } perform render() $(‘ghp-type’).addEventListener(‘change’, perform(){refreshOps();render();}); $(‘ghp-op’).addEventListener(‘change’, render); $(‘ghp-fmt’).addEventListener(‘change’, render); $(‘ghp-detail’).addEventListener(‘change’, render); $(‘ghp-limit’).addEventListener(‘enter’, render); $(‘ghp-copy’).addEventListener(‘click on’, perform(){ var t = this.getAttribute(‘data-cmd’)||”; var btn = this; perform finished(){btn.textContent=”Copied”;setTimeout(perform(){btn.textContent=”Copy”;},1200);} if(navigator.clipboard && navigator.clipboard.writeText){navigator.clipboard.writeText(t).then(finished,finished);} else{var ta=doc.createElement(‘textarea’);ta.worth=t;doc.physique.appendChild(ta);ta.choose();strive{doc.execCommand(‘copy’);}catch(e){}doc.physique.removeChild(ta);finished();} }); refreshOps(); render(); window.addEventListener(‘load’, postHeight); window.addEventListener(‘resize’, postHeight); setTimeout(postHeight, 300); })(); “>

Take a look at the Repo. Additionally, be happy to observe us on Twitter and don’t overlook to affix our 150k+ML SubReddit and Subscribe to our E-newsletter. Wait! are you on telegram? now you’ll be able to be part of us on telegram as nicely.

Must companion with us for selling your GitHub Repo OR Hugging Face Web page OR Product Launch OR Webinar and so forth.? Join with us

Michal Sutter is a knowledge science skilled with a Grasp of Science in Information Science from the College of Padova. With a stable basis in statistical evaluation, machine studying, and knowledge engineering, Michal excels at remodeling complicated datasets into actionable insights.