Skip to content
Back to search

google-health-cli

Google Health CLI — one command-line tool for the Google Health API. Includes AI agent skills.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/google-health-api--google-health-cli/badge.svg)](/listings/google-health-api--google-health-cli)

HTML

<a href="/listings/google-health-api--google-health-cli"><img src="/api/listings/google-health-api--google-health-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

ghealth setup                                              # One-time: GCP project + OAuth
ghealth data steps daily-rollup --from 2026-03-22 --to 2026-03-29  # Weekly step totals
ghealth data heart-rate list --from today --limit 10       # Recent heart rate readings
ghealth schema types                                       # See all available data types

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 416 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # ghealth
  2. CLI for the [Google Health API v4](https://developers.google.com/health) — built for AI agents and developers.
  3. - **40 verified data types**: steps, heart rate, exercise, sleep, weight, SpO2, HRV, ECG, blood glucose, nutrition, and more
  4. - **Agent-first**: simplified JSON output, deterministic exit codes, `--dry-run`, `--raw`
  5. - **Single binary**: `go build -o ghealth .`
  6. ## Quick Start
  7. ```bash
  8. ghealth setup # One-time: GCP project + OAuth
  9. ghealth data steps daily-rollup --from 2026-03-22 --to 2026-03-29 # Weekly step totals
  10. ghealth data heart-rate list --from today --limit 10 # Recent heart rate readings
  11. ghealth schema types # See all available data types
  12. ```
  13. ## Requirements
  14. Download and Install [Go](https://go.dev/doc/install)
  15. ## Installation
  16. ```bash
  17. git clone https://github.com/Google-Health-API/google-health-cli.git
  18. cd google-health-cli
  19. go build -o ghealth .
  20. ```
  21. ## Setup
  22. ```bash
  23. ghealth setup
  24. ```
  25. Walks you through: GCP project ID, OAuth credentials (download from [Console](https://console.cloud.google.com/apis/credentials) — Desktop application type), Health API enablement, scope selection, and browser-based OAuth login.
  26. Files written under `~/.config/ghealth/` (override with `GHEALTH_CONFIG_DIR`):
  27. - `client_secret.json` — your OAuth client (mode 0600)
  28. - `credentials.json` — access + refresh tokens (mode 0600, plaintext JSON)
  29. - `config.toml` — active profile (project, scopes)
  30. Tokens refresh automatically.
  31. ### Non-interactive setup (for agents / CI)
  32. ```bash
  33. ghealth setup \
  34. --project-id my-project \
  35. --client-secret ~/Downloads/client_secret_123.json \
  36. --scopes-preset readonly \
  37. --skip-enable-api \
  38. --no-prompt
  39. ```
  40. Add `--non-interactive-auth` to skip the browser step too — complete later with `ghealth auth login --complete <code>` (see below).
  41. ## Authentication
  42. | Scenario | Method |
  43. |----------|--------|
  44. | Interactive | `ghealth setup` or `ghealth auth login` |
  45. | Headless / no browser | `ghealth auth login --non-interactive` → click URL on any device → `ghealth auth login --complete <code>` |
  46. | Move tokens between machines | `ghealth auth export` → `ghealth auth import` |
  47. | Pre-configured token | `export GHEALTH_ACCESS_TOKEN=ya29...` |
  48. | Credential file | `export GHEALTH_CREDENTIALS_FILE=/path/to/creds.json` |
  49. | GCP environment | Application Default Credentials (automatic) |
  50. Precedence: `GHEALTH_ACCESS_TOKEN` > `GHEALTH_CREDENTIALS_FILE` > stored credentials > ADC.
  51. ### Headless OAuth flow
  52. ```bash
  53. # 1. On the host running ghealth:
  54. ghealth auth login --non-interactive --scopes-preset readonly
  55. # → JSON with auth_url (PKCE S256 challenge + random state baked in)
  56. # and a complete_command. pending_auth.json holds the verifier locally.
  57. # 2. Open auth_url in any browser, click "Allow".
  58. # The browser will redirect to a localhost URL that fails to load — expected.
  59. # Copy either the full redirected URL or just the 'code' query parameter.
  60. # 3. Back on the ghealth host (both forms work):
  61. ghealth auth login --complete 'http://localhost/?code=4/0AX4XfWh...&state=cQq...'
  62. ghealth auth login --complete 4/0AX4XfWh...
  63. # → state validated, PKCE verifier sent on exchange, tokens persisted.
  64. ```
  65. State mismatch (URL paste with the wrong `state` parameter) clears the pending flow and returns exit 2. The bare-code form skips state validation but still consumes the pending file, so a stale flow can't be replayed.
  66. ### Move tokens between machines
  67. ```bash
  68. # source (already authenticated):
  69. ghealth auth export > /tmp/ghealth-creds.json
  70. scp /tmp/ghealth-creds.json target:
  71. # target (also needs client_secret.json — either run 'ghealth setup --non-interactive-auth' or copy it):
  72. ghealth auth import --file /tmp/ghealth-creds.json
  73. ```
  74. ### Bootstrap from a fresh machine (no client_secret yet)
  75. When no OAuth `client_secret.json` is configured, every auth command returns a
  76. structured error with a `next_steps` array — the same six steps every time —
  77. so an agent can relay it to a user verbatim without scraping prose:
  78. ```bash
  79. ghealth auth login
  80. # → exit 5, JSON on stderr:
  81. # {
  82. # "error": {
  83. # "type": "config", "code": 5,
  84. # "message": "No OAuth client_secret.json configured",
  85. # "hint": "Run 'ghealth setup' to create or import OAuth credentials",
  86. # "next_steps": [
  87. # "Open https://console.cloud.google.com/apis/credentials",
  88. # "Create or select a Google Cloud project",
  89. # "Enable the Google Health API (...)",
  90. # "Create OAuth client ID with Application type: Desktop app",
  91. # "Download the client_secret JSON",
  92. # "Run: ghealth setup --client-secret /path/to/client_secret.json"
  93. # ]
  94. # }
  95. # }
  96. ```
  97. Same `next_steps` are emitted by:
  98. - `ghealth auth login` (interactive / `--non-interactive` / `--complete`)
  99. - `ghealth auth status` when neither stored creds nor env creds are present
  100. - `ghealth auth refresh`, `ghealth auth export` (when nothing to refresh/export)
  101. - `ghealth setup --no-prompt` when `--client-secret` is missing
  102. To fetch the checklist **without** triggering an error (e.g. so an agent can
  103. display the bootstrap steps before calling auth at all):
  104. ```bash
  105. ghealth setup --instructions
  106. # → exit 0, JSON on stdout with status: "instructions" and the next_steps array
  107. ```
  108. ## Data Types
  109. 40 types verified against the live API. Run `ghealth schema types` for the full list.
  110. | Type | Key Values | Operations |
  111. |------|-----------|------------|
  112. | `steps` | *(use daily-rollup for `countSum`)* | list, rollup, daily-rollup, reconcile |
  113. | `heart-rate` | `beatsPerMinute` | list, rollup, daily-rollup, reconcile |
  114. | `exercise` | type, duration, calories, avgHeartRate, notes | list, get, create, update, delete, reconcile, export-tcx |
  115. | `sleep` | minutesAsleep, minutesAwake, stageMinutes | list, get, create, update, delete, reconcile |
  116. | `weight` | `weightGrams` | list, get, create, update, delete, rollup, daily-rollup, reconcile |
  117. | `body-fat` | `percentage` | list, get, create, update, delete, rollup, daily-rollup, reconcile |
  118. | `height` | `heightMillimeters` | list, get, create, update, delete, reconcile |
  119. | `distance` | *(use daily-rollup for `millimetersSum`)* | list, rollup, daily-rollup, reconcile |
  120. | `heart-rate-variability` | RMSSD | list, reconcile |
  121. | `oxygen-saturation` | `percentage` (SpO2) | list, reconcile |
  122. | `altitude` | altitude value | list, rollup, daily-rollup, reconcile |
  123. | `active-zone-minutes` | `activeZoneMinutes`, `heartRateZone` | list, daily-rollup, reconcile |
  124. | `activity-level` | SEDENTARY, LIGHT, MODERATE, VIGOROUS | list, reconcile |
  125. | `basal-energy-burned` | `kcal` per interval (BMR) | list, reconcile |
  126. | `active-energy-burned` | `kcal` per interval (activity) | list, rollup, daily-rollup, reconcile |
  127. | `vo2-max` | VO2 max value | list, reconcile |
  128. | `total-calories` | *(use daily-rollup for `kcalSum`)* | daily-rollup |
  129. | `sedentary-period` | sedentary intervals | list, daily-rollup, reconcile |
  130. | `swim-lengths-data` | `swimStrokeType`, `strokeCount` *(use daily-rollup for `strokeCountSum`)* | list, rollup, daily-rollup, reconcile |
  131. | `hydration-log` | `milliliters` consumed | list, get, daily-rollup, reconcile |
  132. | `nutrition-log` | nutrients, `energy`, mealType, food | list, get, rollup, daily-rollup, reconcile |
  133. | `food` | nutrient profiles, servings *(catalog — no time filter)* | list, get |
  134. | `food-measurement-unit` | `displayName` *(catalog — no time filter)* | list, get |
  135. | `blood-glucose` | mg/dL, mealType, measurementTiming | list, get, rollup, daily-rollup, reconcile |
  136. | `core-body-temperature` | `temperatureCelsius` | list, get, rollup, daily-rollup, reconcile |
  137. | `electrocardiogram` | waveform, `resultClassification` *(requires `ecg.readonly`)* | list |
  138. | `irregular-rhythm-notification` | alert windows *(requires `irn.readonly`)* | list |
  139. | `daily-resting-heart-rate` | `beatsPerMinute` per day | list, reconcile |
  140. | `daily-heart-rate-variability` | daily HRV summary | list, reconcile |
  141. | `daily-oxygen-saturation` | daily SpO2 summary | list, reconcile |
  142. | `daily-respiratory-rate` | daily respiratory rate | list, reconcile |
  143. | `daily-vo2-max` | daily VO2 max | list, reconcile |
  144. | `daily-sleep-temperature-derivations` | temp deviation from baseline | list, reconcile |
  145. | `respiratory-rate-sleep-summary` | per-stage respiratory rate | list, reconcile |
  146. | `run-vo2-max` | VO2 max from running | list, daily-rollup, reconcile |
  147. | `floors` | *(rollup only — `countSum`)* | rollup, daily-rollup, reconcile |
  148. | `active-minutes` | *(rollup only)* | rollup, daily-rollup, reconcile |
  149. | `time-in-heart-rate-zone` | *(rollup only)* | daily-rollup, reconcile |
  150. | `calories-in-heart-rate-zone` | *(rollup only — `caloriesInHeartRateZones` array per bucket)* | rollup, daily-rollup, reconcile |
  151. | `daily-heart-rate-zones` | *(reconcile only)* | reconcile |
  152. ### Exercise track export
  153. `export-tcx` writes the raw Google TCX, or — with `--as csv` — flattens it to one row per trackpoint (`time, activity, lap, sport, latitude_deg, longitude_deg, altitude_m, distance_m, heart_rate_bpm, cadence_rpm, speed_mps, watts`) for direct `pd.read_csv` consumption. Indoor activities have no track and yield a header-only CSV; their summary/notes live in `data exercise list`. Pass `--output -` to stream to stdout instead of a file.
  154. ```bash
  155. ghealth data exercise export-tcx --id <id> --output ride.csv --as csv
  156. ghealth data exercise export-tcx --id <id> --output - --as csv | head # stream to stdout
  157. ```
  158. ## Usage
  159. ### Reading data
  160. ```bash
  161. # Recent heart rate (sample-type: returns individual readings)
  162. ghealth data heart-rate list --from today --limit 10
  163. # Daily step totals for a week (rollup: returns aggregated counts)
  164. ghealth data steps daily-rollup --from 2026-03-22 --to 2026-03-29
  165. # Exercises this month
  166. ghealth data exercise list --from 2026-03-01
  167. # Weight history
  168. ghealth data weight list --limit 20
  169. # Sleep (summary by default, --detail for stage-by-stage breakdown)
  170. ghealth data sleep list --limit 5
  171. ghealth data sleep list --limit 5 --detail
  172. ```
  173. Every read (`list`, `get`, `rollup`, `daily-rollup`, `reconcile`) returns the same JSON shape — an object `{"dataPoints": [...]}` with optional `_hints` and `nextPageToken` — so the rows are always under `dataPoints`.
  174. `list` returns up to `--limit` rows (default 500). When more exist it includes a `nextPageToken`; pass it back with `--page-token` to fetch the next page losslessly (no rows skipped or repeated):
  175. ```bash
  176. ghealth data heart-rate list --from 2026-06-15 --limit 500 # → {"dataPoints":[…], "nextPageToken":"ABC"}
  177. ghealth data heart-rate list --from 2026-06-15 --limit 500 --page-token ABC
  178. ```
  179. ### Important: list vs daily-rollup
  180. Some types (steps, distance) return **time intervals without values** from `list`. Use `daily-rollup` to get totals:
  181. ```bash
  182. # This returns minute-by-minute intervals (no step count):
  183. ghealth data steps list --from today --limit 5
  184. # This returns daily totals with actual counts:
  185. ghealth data steps daily-rollup --from 2026-03-22 --to 2026-03-29
  186. # → {"dataPoints": [{"date": "2026-03-28", "countSum": "9037"}, ...]}
  187. ```
  188. ### Gotcha: missing days are NOT zeros
  189. For the presence-aware types — `altitude`, `distance`, `floors`, `steps`, `total-calories` — a date that is **absent** from rollup output means the device was not worn (or did not sync) that day, **not** that the value was zero. A bucket with `countSum: "0"` is a **true zero**: the device was worn and genuinely recorded no activity.
  190. - Missing date → render as "no data", never coalesce to 0
  191. - `countSum: "0"` → true zero (worn, no activity)
  192. - Never average over absent days as if they were zeros — that silently deflates weekly/monthly stats
  193. ### Filtering
  194. ```bash
  195. ghealth data heart-rate list --from 2026-03-28 # From date
  196. ghealth data heart-rate list --from 2026-03-28 --to 2026-03-29 # Date range
  197. ghealth data heart-rate list --from today --limit 50 # Today, max 50
  198. ghealth data heart-rate list --from yesterday # Since yesterday
  199. ```
  200. `--filter` passes a raw expression to the API (overrides `--from`/`--to`). Filter syntax follows [AIP-160](https://google.aip.dev/160) — interval types use `{type}.interval.civil_start_time` (ISO 8601, no `Z`), sleep uses `sleep.interval.civil_end_time` (only end-time is filterable), sample types use `{type}.sample_time.physical_time` (RFC-3339, with `Z`). Only `>=` and `<` comparators are supported.
  201. ### Writing data
  202. Writable types: `exercise`, `sleep`, `weight`, `body-fat`, `height`.
  203. Write operations are asynchronous — the API returns an Operation object. Use `list` to verify the data was persisted.
  204. To discover the correct JSON format, inspect a real response: `ghealth data weight list --raw --limit 1`
  205. ```bash
  206. # Create (use --raw list output to model the payload structure)
  207. ghealth data weight create --json '{"weight": {"weightGrams": 75500, "sampleTime": {"physicalTime": "2026-03-29T10:00:00Z", "utcOffset": "3600s"}}}'
  208. # Update (use --update-mask to specify which fields to change)
  209. ghealth data weight update --id <id> --json '{"weight": {"weightGrams": 76000}}'
  210. # Delete (accepts bare IDs or full resource names)
  211. ghealth data exercise delete --ids 7649353586249326520
  212. ```
  213. ## Output
  214. Responses are **simplified by default** — redundant timestamps, empty fields, and repeated metadata are stripped. Timestamps include the user's UTC offset (e.g., `+01:00`).
  215. ```bash
  216. ghealth data heart-rate list --from today --limit 2
  217. ```
  218. ```json
  219. {
  220. "dataPoints": [
  221. {"time": "2026-03-29T16:33:07+01:00", "beatsPerMinute": "80", "source": "Google Pixel Watch 4 (41mm)"},
  222. {"time": "2026-03-29T16:33:04+01:00", "beatsPerMinute": "80", "source": "Google Pixel Watch 4 (41mm)"}
  223. ]
  224. }
  225. ```
  226. ```bash
  227. ghealth data steps daily-rollup --from 2026-03-26 --to 2026-03-29
  228. ```
  229. ```json
  230. {
  231. "dataPoints": [
  232. {"date": "2026-03-28", "countSum": "9037"},
  233. {"date": "2026-03-27", "countSum": "2408"},
  234. {"date": "2026-03-26", "countSum": "6474"}
  235. ]
  236. }
  237. ```
  238. | Flag | Effect |
  239. |------|--------|
  240. | `--raw` | Return the original API response with no simplification |
  241. | `--format table` | Aligned columns |
  242. | `--format csv` | CSV output (nested objects flatten to dot-separated columns) |
  243. | `-o, --output <file>` | Write data to the file; print only a column schema + 3-row preview to stdout. Prefer this over `> file` (which gives the file but no schema) |
  244. | `--dry-run` | Show the HTTP request without executing |
  245. In `--format csv` and `--format table`, the data stream stays pure: `_hints` and a leftover `nextPageToken` are written to **stderr** rather than mixed into the rows, and an empty result emits an empty CSV (never a JSON object). Use `-o <file>` and the stderr signals together to page through a large export without polluting the CSV.
  246. ## AI Agent Skills
  247. The repo ships 2 Agent Skills (`SKILL.md` files) — one for shared prerequisites (auth, setup, global flags) and one covering all 40 data types, operations, patterns, and gotchas.
  248. ```bash
  249. # Install all skills at once
  250. npx skills add https://github.com/Google-Health-API/google-health-cli
  251. # Or pick only what you need
  252. npx skills add https://github.com/Google-Health-API/google-health-cli/tree/main/skills/ghealth
  253. npx skills add https://github.com/Google-Health-API/google-health-cli/tree/main/skills/ghealth-shared
  254. ```
  255. Agents don't need to read the full skill file upfront. The CLI supports progressive self-discovery:
  256. ```bash
  257. ghealth schema types # What types exist? What operations?
  258. ghealth schema type heart-rate # Fields, parameters, scope for one type
  259. ghealth data <type> --help # What operations does this type support?
  260. ghealth data <type> list --help # What flags does this operation take?
  261. ghealth --dry-run ... # What HTTP request would this send?
  262. ```
  263. ## Other Commands
  264. ```bash
  265. ghealth user identity # User identity
  266. ghealth user profile get # Profile (age, stride length)
  267. ghealth user settings get # Settings (timezone, units)
  268. ghealth auth status # Auth state (scopes, expiry)
  269. ghealth schema types # All data types + operations
  270. ghealth schema type heart-rate # Detail for one type
  271. ghealth schema scopes # OAuth scopes
  272. ghealth schema endpoints # All API endpoints
  273. ghealth config show # Show active configuration (project, scopes, format)
  274. ghealth config set timezone <IANA zone> # Set a config value (keys: project_id, format, timezone)
  275. ghealth webhooks subscribers list # Manage push-notification subscribers / subscriptions
  276. ```
  277. `webhooks` (subscribers, subscriptions, `verify`) manages project-level push notifications and requires the `cloud-platform` scope plus a configured project ID — see the skill docs for details.
  278. Because a `cloud-platform` token is rejected by the data-plane endpoints, keep webhook credentials in a **separate config dir** from your health-data credentials. `auth login` always writes tokens to the active config dir, so use a dedicated `GHEALTH_CONFIG_DIR` for webhooks (not `GHEALTH_CREDENTIALS_FILE`, which only changes where tokens are *read* from):
  279. ```bash
  280. export GHEALTH_CONFIG_DIR=~/.config/ghealth-webhooks
  281. ghealth setup # its own client_secret + project
  282. ghealth auth login --scopes cloud-platform
  283. ghealth webhooks subscribers list
  284. ```
  285. ### Timezones
  286. Date arguments (`--from`/`--to`, `today`, `yesterday`) resolve against exactly one timezone, chosen in this order:
  287. 1. the active profile's configured zone — `ghealth config set timezone <IANA zone>`
  288. 2. otherwise, the machine-local timezone
  289. ### Verifying tokens
  290. `ghealth auth status` is a fast local check by default — it reports what's configured without making any network calls, and the `authenticated` field reflects local state only. For env-token / credentials-file modes it is omitted entirely (presence of a token doesn't prove validity).
  291. ```bash
  292. ghealth auth status --validate
  293. ```
  294. Verifies the access token against Google's `tokeninfo` endpoint. `authenticated` then reflects actual validity, and the response includes `expires_in` and `scope` from Google.
  295. ## Exit Codes
  296. | Code | Meaning |
  297. |------|---------|
  298. | 0 | Success |
  299. | 1 | API error (4xx/5xx) |
  300. | 2 | Auth error (have client_secret, missing or invalid tokens — run `ghealth auth login`) |
  301. | 3 | Validation error |
  302. | 4 | Network error |
  303. | 5 | Config error (often: no `client_secret.json` — error carries `next_steps` for bootstrap) |
  304. Errors are always JSON on stderr and may include a `next_steps: []string` array for multi-step recovery (currently only emitted when no OAuth client is configured).
  305. ## Environment Variables
  306. | Variable | Purpose |
  307. |----------|---------|
  308. | `GHEALTH_ACCESS_TOKEN` | Direct access token |
  309. | `GHEALTH_CREDENTIALS_FILE` | Path to credential JSON |
  310. | `GHEALTH_CONFIG_DIR` | Config directory override |
  311. | `GHEALTH_PROFILE` | Active profile name |
  312. | `GHEALTH_FORMAT` | Default output format (json/table/csv) |
  313. | `GHEALTH_BASE_URL` | Override the API base URL |
  314. ## License
  315. Apache 2.0 — see [LICENSE](LICENSE.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.