Menú
Shared prerequisites for all ghealth skills — auth, setup, global flags, command structure
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
| 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)