/ghealth-shared

name: ghealth-shared
description: Shared prerequisites for all ghealth skills — auth, setup, global flags, command structure

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