ghealth-shared

ghealth — 共通の前提条件

セットアップ

ghealth setup                       # interactive wizard, run once

6 つの手順：GCP プロジェクト ID、OAuth client_secret JSON（デスクトップアプリケーション）、Health API の有効化、スコープの選択、ブラウザーを使った OAuth、プロファイルの保存。

スクリプトから実行する場合（プロンプトをスキップします）：

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

--non-interactive-auth を追加するとブラウザーの手順をスキップでき、後で ghealth auth login --complete <code> を実行して完了できます。

作成されるファイル

すべて ~/.config/ghealth/ の下に作成されます（GHEALTH_CONFIG_DIR で変更できます）：

ファイル	内容	モード
client_secret.json	GCP OAuth クライアント	0600
credentials.json	アクセストークン＋リフレッシュトークン（平文 JSON）	0600
pending_auth.json	進行中の非対話型フローの状態	0600
config.toml	アクティブなプロファイル（プロジェクト、スコープ、形式）	0600

認証

方法	使用方法
保存済みの認証情報	ghealth auth login（セットアップ後のデフォルト）
ヘッドレス（ブラウザーなし）	ghealth auth login --non-interactive → URL をクリック → ghealth auth login --complete <code>
マシン間でトークンを移動	ghealth auth export > creds.json → 移動先で：ghealth auth import --file creds.json
アクセストークン（更新なし）	export GHEALTH_ACCESS_TOKEN=ya29...
認証情報ファイル	export GHEALTH_CREDENTIALS_FILE=/path/to.json
ADC（GCP 環境）	利用可能な場合は自動で使用

優先順位：環境変数のトークン > 認証情報ファイル > 保存済みの認証情報 > ADC。リフレッシュトークンは credentials.json に保存され、自動的に更新されます（アクセストークンの有効期間は 1 時間）。API から 401 が返された場合は、エラーになる前に 1 回強制的に更新します。

確認：ghealth auth status。終了コード：

• 0 — ローカルで設定済み。ネットワーク呼び出しは行いません。保存済みのトークンが期限切れでも終了コードは 0 です — JSON は authenticated: false / expired: true を返します
• 2 — client_secret.json はありますが、保存済みのトークンがありません（credentials.json がありません）。ghealth auth login を実行してください
• 5 — client_secret.json がありません。ブートストラップ用の next_steps[] を含むエラーが返されます（下記を参照）

アクセストークンを Google の tokeninfo エンドポイントで検証するには、--validate を追加してください。指定しない場合、環境変数のトークン／認証情報ファイルのモードでは configured: true が返されますが、authenticated: true とは報告されません — トークンが存在するだけでは有効性の証明にならないためです。--validate を指定すると、レスポンスに Google からの authenticated、expires_in、scope が含まれます。

エージェント向けブートストラップ手順

OAuth クライアントの client_secret チェックリストを取得する（失敗する呼び出しは不要）：

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

同一の next_steps 配列は、client_secret.json がないために処理を進められないすべてのエラーパスにも埋め込まれています：auth login（--complete を含むすべてのモード）、auth status、auth refresh、auth export、setup --no-prompt。エージェントは jq -e '.error.next_steps' を実行し、その内容をそのまま伝えてください。

ワークステーションでの新規インストール（ブラウザーあり）：

ghealth setup    # one interactive run; refresh handles itself afterwards

ヘッドレスホストでの新規インストール（ブラウザーなし）：

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>

コンテナ／2 台目のワーカーにトークンをマウントする：

# 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 のサブコマンド：identity、profile get|update、settings get|update、irn-profile、paired-devices list|get --id <id>。

webhooks のサブコマンド：subscribers list|create|update|delete、subscriptions list|create|update|delete --subscriber <id>、verify --url <url>。**cloud-platform スコープ（ghealth auth login --scopes cloud-platform）と、設定済みのプロジェクト ID が必要です。**これらはプロジェクトレベルのプッシュ通知エンドポイントです。認証された ID にも、プロジェクト上の Health API subscriber IAM 権限が必要です。

グローバルフラグ

フラグ	効果
--format json|table|csv	出力形式（デフォルト：json）
-o <file>	データをファイルに書き込みます。標準出力には列スキーマと3行のプレビューのみを表示し、データは表示しません
--raw	レスポンスの簡略化を回避し、元のAPI JSONを返します
--dry-run	HTTPリクエストを実行せずに表示します
--profile <name>	名前付きの設定プロファイルを使用します

list では、--limit N（結果の最大合計数、デフォルトは500）、--from、--to、--filter、--page-token（以前のレスポンスの nextPageToken から再開）、--detail（睡眠）も指定できます。

検出

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

出力

• デフォルトではレスポンスを簡略化します。UTCオフセット付きのフラットなタイムスタンプ、簡潔なソース、空フィールドなしの形式です
• JSON出力は、すべての読み取り操作（list、get、rollup、daily-rollup、reconcile）で常に同じ形状になります。任意の _hints と nextPageToken を含む {"dataPoints": [...]} オブジェクトです。ロールアップや空の結果でも、行は常に dataPoints の下にあるため、json.load(out)["dataPoints"] は常に機能します
• --raw はAPIレスポンス全体を返します
• --format csv はフラットなCSVを出力します。ネストされたオブジェクトはドット区切りの列名に自動でフラット化されます（例：metricsSummary.caloriesKcal）
• -o <file> はデータをファイルに書き込み、標準出力には要約（行数、列名、3行のプレビュー）のみを表示します。パイプ（> file）の代わりにこちらを使用してください。パイプではファイルは作成できますが、標準出力にスキーマが表示されません
• エラーは常に標準エラー出力にJSON形式で出力され、終了コードは0～5です
• タイムスタンプにはユーザーのタイムゾーンオフセットが含まれます（例：+01:00）