Ghealth shared

Skill Google-Health-API/google-health-cli/skills/ghealth-shared

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

Install

npx -y skills add Google-Health-API/google-health-cli --skill ghealth-shared

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its author says it does

Copied from the file, not written here

Shared prerequisites for all ghealth skills — auth, setup, global flags, command structure

SKILL.md

6.7 KB, as published. Nobody here has run it

ghealth — Shared Prerequisites

Setup

ghealth setup                       # interactive wizard, run once

Six steps: GCP project ID, OAuth client_secret JSON (Desktop application), Health API enable, scope selection, browser-based OAuth, save profile.

Scriptable (skips prompts):

ghealth setup \
  --project-id my-project \
  --client-secret ~/Downloads/client_secret_123.json \
  --scopes-preset readonly \
  --skip-enable-api \
  --no-prompt

Add --non-interactive-auth to skip the browser step and finish later with ghealth auth login --complete <code>.

Files written

All under ~/.config/ghealth/ (override with GHEALTH_CONFIG_DIR):

File	Contents	Mode
`client_secret.json`	Your GCP OAuth client	0600
`credentials.json`	Access + refresh tokens (plaintext JSON)	0600
`pending_auth.json`	In-progress non-interactive flow state	0600
`config.toml`	Active profile (project, scopes, format)	0600

Authentication

Method	Usage
Stored credentials	`ghealth auth login` (default after setup)
Headless (no browser)	`ghealth auth login --non-interactive` → click URL → `ghealth auth login --complete <code>`
Move tokens between machines	`ghealth auth export > creds.json` → on target: `ghealth auth import --file creds.json`
Access token (no refresh)	`export GHEALTH_ACCESS_TOKEN=ya29...`
Credential file	`export GHEALTH_CREDENTIALS_FILE=/path/to.json`
ADC (GCP envs)	Automatic if available

Precedence: env token > credential file > stored > ADC. Refresh tokens are persisted in credentials.json and refreshed automatically (1h access-token lifetime); a 401 from the API force-refreshes once before erroring.

Check: ghealth auth status. Exit codes:

0 — locally configured; does not make a network call. Expired stored tokens still exit 0 — the JSON reports authenticated: false / expired: true
2 — client_secret.json present but no stored tokens (credentials.json missing); run ghealth auth login
5 — no client_secret.json at all; error carries next_steps[] for bootstrap (see below)

Add --validate to verify the access token against Google's tokeninfo endpoint. Without it, env-token / credentials-file modes report configured: true but never claim authenticated: true — presence of a token doesn't prove validity. With --validate, the response includes authenticated, expires_in, and scope from Google.

Bootstrap recipes for agents

Fetch the OAuth client_secret checklist (no failing call needed):

ghealth setup --instructions
# → exit 0, JSON on stdout with status: "instructions" and next_steps[].
# Same six steps an auth error would emit when no client_secret.json is configured:
#   1. Open https://console.cloud.google.com/apis/credentials
#   2. Create or select a Google Cloud project
#   3. Enable the Google Health API
#   4. Create OAuth client ID with Application type: Desktop app
#   5. Download the client_secret JSON
#   6. Run: ghealth setup --client-secret /path/to/client_secret.json

The identical next_steps array is also embedded in every error path where a missing client_secret.json blocks progress: auth login (all modes including --complete), auth status, auth refresh, auth export, setup --no-prompt. Agents should jq -e '.error.next_steps' and relay verbatim.

Fresh install on a workstation (has browser):

ghealth setup    # one interactive run; refresh handles itself afterwards

Fresh install on a headless host (no browser):

ghealth setup --project-id $P --client-secret $CS \
              --scopes-preset readonly --skip-enable-api \
              --no-prompt --non-interactive-auth
# stdout prints status: "setup_pending_auth" + an auth_url on stderr
# human clicks the URL on any browser → URL bar shows ?code=... ; agent copies it
ghealth auth login --complete <code>

Mount tokens into a container / second worker:

# on authenticated host:
ghealth auth export > /secrets/ghealth-creds.json
# in the container (with the same client_secret.json available):
ghealth auth import --file /secrets/ghealth-creds.json

Command Structure

ghealth data <type> <operation> [flags]
ghealth user <subcommand>
ghealth schema <subcommand>
ghealth webhooks <subcommand>

user subcommands: identity, profile get|update, settings get|update, irn-profile, paired-devices list|get --id <id>.

webhooks subcommands: subscribers list|create|update|delete, subscriptions list|create|update|delete --subscriber <id>, verify --url <url>. Requires the cloud-platform scope (ghealth auth login --scopes cloud-platform) and a configured project ID. These are project-level push-notification endpoints; the authenticated identity also needs Health API subscriber IAM permissions on the project.

Global Flags

Flag	Effect
`--format json\|table\|csv`	Output format (default: json)
`-o <file>`	Write data to file; stdout shows only column schema + 3-row preview (not the data)
`--raw`	Bypass response simplification, return original API JSON
`--dry-run`	Print HTTP request without executing
`--profile <name>`	Use named config profile

list also accepts: --limit N (max total results, default 500), --from, --to, --filter, --page-token (resume from a prior response's nextPageToken), --detail (sleep).

Discovery

ghealth schema types              # All types + supported operations
ghealth schema type <name>        # Fields, parameters for one type
ghealth data <type> --help        # Available operations
ghealth data <type> list --help   # Flags for an operation

Output

Responses are simplified by default: flat timestamps with UTC offset, compact source, no empty fields
JSON output always has the same shape for every read (list, get, rollup, daily-rollup, reconcile): an object {"dataPoints": [...]}, with optional _hints and nextPageToken. The rows are always under dataPoints — even for rollups and empty results — so json.load(out)["dataPoints"] always works
--raw returns the full API response
--format csv outputs flat CSV; nested objects are auto-flattened to dot-separated columns (e.g., metricsSummary.caloriesKcal)
-o <file> writes data to the file and prints only a summary to stdout (row count, column names, 3-row preview). Use this instead of piping (> file) — piping gives you the file but no schema on stdout
Errors always JSON on stderr, exit codes 0-5
Timestamps include user's timezone offset (e.g., +01:00)