Menu
Shared prerequisites for all ghealth skills — auth, setup, global flags, command structure
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | ghealth-shared |
| description | Shared prerequisites for all ghealth skills — auth, setup, global flags, command structure |
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>.
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 |
| 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:
authenticated: false / expired: trueclient_secret.json present but no stored tokens (credentials.json missing); run ghealth auth loginclient_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.
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
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.
| 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).
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
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+01:00)