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)

ghealth-shared

ghealth — Shared Prerequisites

Setup