スマートフォン直接接続CLI

healthmd CLIは、開いているiPhoneまたはAndroidのHealth.mdアプリへ直接接続します。スタンドアロンCLIはHealth.md for Macを一切必要とせず、経由せず、バックエンド選択も存在しません。スマートフォンは各プラットフォームのヘルスデータストア（iPhoneではHealthKit、AndroidではHealth Connect）を読み取り、結果を保護されたストレージへ準備して、検証済みのパーティションをCLIへ転送します。

healthmd on the computer
  <-> authenticated encrypted Manual IP, Tailscale, or supported Nearby channel
Health.md on iPhone or Android -> HealthKit / Health Connect -> protected bounded spool
  -> raw snapshots, production-generated files, or (iPhone) canonical and typed query data

プレビュー · ポータブル直接接続CLI

同梱のSwift直接接続バックエンドはmacOSで利用でき、iPhoneとペアリングします。アプリケーションプロトコルv2のAndroidは、公開パッケージ化されたクロスプラットフォームRustプレビューの一部です。現在のiOSとAndroidは、新しいポータブルペアリングで同じセレクター3と共通QRを使用します。両方のスマートフォンプラットフォームで基本的な実機接続は確認済みですが、正確なビルドによる完全なリリースマトリックスは未完了のため、引き続き明示的に未認定のワークフローです。

0.1.0-alpha.6のモバイル互換性

この独立した表が、明示的に未認定のプレビューで使用する互換性マトリックスです。iPhoneとAndroidの基本的な実機接続は確認済みですが、完全な認定マトリックスを完了し証跡を保持した公開CLI／モバイルの組み合わせはまだありません。

モバイルソース	プロトコル	正確なtag-SHA対応版／未認定の互換性下限	ポータブルRust操作	公開状態
エクスポート対応iPhone	現行セレクタ3（旧1）/ アプリケーションv1	iOS 3.3.0（ビルド202609032317）/ iOS 3.0.3	状態、生データ、抽出、ファイル、再開、キャンセル	接続確認済み、完全認定待ち
クエリ対応iPhone	現行セレクタ3（旧1）/ アプリケーションv1 + クエリv3	iOS 3.3.0（ビルド202609032317）/ iOS 3.0.3	V1に加えて19ツールのローカルMCP／クエリ	接続確認済み、完全認定待ち
Android	現行セレクタ3（旧2）/ アプリケーションv2	Android 1.8.2 (`versionCode 31`) / Android 1.5.4 (`versionCode 25`)	状態、ネイティブ生データ、ファイル、再開、キャンセル	接続確認済み、完全認定待ち
Android型付きMCPクエリ	該当なし	未実装	クエリツールにはiPhone v3が必要	非対応

直接接続モードの対応機能

共有セレクター3による1回限りのペアリングと、iPhone（アプリケーションプロトコルv1）またはAndroid（アプリケーションプロトコルv2）のソースとの信頼済み再接続
ローカルの信頼済みデバイスの確認とペアリング解除
スマートフォンのリアルタイムな準備状況
厳密な生データエクスポート。iPhoneではschema-v8 healthmd.health_data、AndroidではプロバイダネイティブなHealth Connectスナップショット
選択範囲の正規抽出（iPhoneのみ）
両方のスマートフォンプラットフォームでの本番エクスポーターによるファイル生成
ローカル永続ジョブの状態確認と再開
明示的なキャンセル
同じ実行ファイルによるhealthmd mcp serve stdioサーバー。iPhone直接接続の型付きクエリ、指標カタログ、エビデンス、MCP Apps UI、PNGフォールバックに対応（iPhoneのみ）

Health.md for Macに同梱のSwiftヘルパーも--backend directで選択できる互換ダイレクトモードを提供します。このページで示すスタンドアロンRust CLIは直接接続専用で、バックエンドフラグを受け付けません。Mac向けのdoctor、query、evidence、refreshサブコマンドはその同梱ヘルパーに属し、そのダイレクトモードではbackend_unsupportedを返します。スタンドアロンRustの文法には存在せず、Macアプリへ切り替えることもありません。iPhone直接接続で新規の型付き分析を行うにはhealthmd mcp serveを使用します。Codexの設定とペアリングを自動で行うには、healthmd setup codexを実行します。healthmd mcp schema [TOOL]は、ネストしたMCP入力スキーマと例をローカルに正確に出力します。睡眠にはhealthmd_sleep_sessionsを直接使用し、正規のextract出力を型付きクエリAPIとして扱わないでください。

要件

直接接続に対応するhealthmdバイナリと、対応するHealth.mdのビルド（iPhoneはアプリケーションプロトコルv1、Androidはアプリケーションプロトコルv2）。AndroidのペアリングにはポータブルRustクライアントが必要です。同梱のmacOSヘルパーがペアリングできるのはiPhoneだけです。
ペアリング時と新しいコマンドの開始時に、スマートフォンでHealth.mdが前面表示されていること
iPhoneでは設定 > Mac同期 > Direct CLI Access、Androidでは設定 → Direct CLIが有効であること
プラットフォームのヘルス権限（HealthKitまたはHealth Connect）、保護されたデータ、ローカルネットワーク権限、エクスポート利用枠を使用できること
Manual IPでは、到達可能なコンピューターのアドレスとTCPポート17647。Tailscaleアドレスも使用可能
生成ファイルモードでは、既存の絶対パスの保存先

CLIがリスナーになります。スマートフォンは、Direct CLI Accessに入力したコンピューターのアドレスへ接続します。

対応する転送方式

転送方式	macOS同梱のSwiftヘルパー	ポータブルRustクライアント
LAN上のManual IP	対応	macOS、Linux、Windows
Tailscaleアドレス	対応	macOS、Linux、Windows
Nearby / MultipeerConnectivity	対応	非対応

Nearbyでは、Appleの暗号化されたMultipeerセッションに加え、Manual IPと同じHealth.mdアプリケーション認証および暗号化を使用します。ポータブルクライアントでNearbyを指定すると、transport_unsupportedが返されます。

Manual IPで一度ペアリングする

コンピューターでリスナーを起動します。

healthmd direct pair --transport manual-ip

ポータブルRustクライアントは、iOSとAndroidで共通のQRコードを表示し、その共有20桁コード、候補となるコンピューターのアドレス、リスナーポート、旧iOS向けの6桁フォールバックを標準エラー出力へ出力します。同梱のmacOSヘルパーは、従来の6桁iPhoneコードだけを引き続き表示します。標準出力は最終的なJSON結果のために空けておきます。

iPhoneでは、次の手順を行います。

Health.md >設定 > Mac同期 > Direct CLI Accessを開いて、アクセスを有効にします。
ペアリングQRをスキャンをタップし、共通QRを読み取ります。明示的なスキャンの直後にペアリングが始まります。
スキャンできない場合はManual IPを選び、アドレス、ポート、共有20桁コードを入力します。旧CLIでは6桁コードも引き続き使用できます。
両方で成功が報告されるまで、アプリを開いたままにします。

Androidスマートフォンをペアリングする

AndroidスマートフォンでHealth.md >設定 → Direct CLIを開きます。
ペアリングQRをスキャンをタップし、共通QRを読み取ります。明示的なスキャンの直後にペアリングが始まります。
カメラや権限がない場合は、アドレス、ポート、同じ共有20桁コードを手動で入力します。
アプリを開いたままにします。Androidでは、アクティブな直接接続セッションの間、ユーザーが開始した可視のデータ同期フォアグラウンドサービスが実行されます。

1回限りコードはネットワーク経由で送信されず、保存もされません。ペアリング後の再接続の信頼は、KeychainまたはAndroid Keystoreによって保護されます。

必要に応じて別のポートを使用します。

healthmd --port 18000 direct pair --transport manual-ip
healthmd --port 18000 status

以後のstatus、export、resume、cancelコマンドでも、同じポートを明示してください。

Nearbyでペアリングする

Nearbyは、同梱のSwiftヘルパーでのみ利用できます。

healthmd direct pair --transport nearby

iPhoneのDirect CLI AccessでNearbyを選択し、表示されたコードを入力して、ペアリングが終わるまで両方のデバイスを開いたままにします。Nearbyの操作に失敗しても、Manual IPへ切り替わることはありません。

信頼済みデバイス

ペアリングでは、Health.md Macアプリの同期関係とは別の信頼関係が作成されます。

healthmd direct devices
healthmd direct unpair DEVICE_UUID

これらのコマンドはローカルの信頼情報を読み取り、または変更するだけで、スマートフォンには接続しません。iPhone側では、ペアリング済みCLIを削除を使用して相手側を削除します。Androidでは、設定 → Direct CLIからペアリングを削除します。

複数のスマートフォンを信頼している場合は、対象のインストールを明示的に選択します。

healthmd --device DEVICE_UUID status

healthmd direct reset-trust --confirmは、ローカルの信頼情報が破損しているか、交換前のインストールに属している場合にだけ使用してください。ローカルの直接ペアリングがすべて削除されます。最初からやり直す前に、スマートフォン側でもそれらのペアリングを削除してください。

リアルタイムの準備状況を確認する

healthmd --transport manual-ip status

直接接続のstatusレスポンスは、ヘルスデータの値を含めず、接続状態と安全性の状態を報告します。ポータブルクライアントは、ソースをsourceとして報告し、platformはiosまたはandroidになります。iPhoneソースでは同じデータがiphoneにも報告されます。作業を始める前に、次のフィールドを確認してください（iPhoneソースの例）。

フィールド	準備完了の値
`direct_cli.paired`	`true`
`iphone.connected`	`true`
`iphone.app_active`	新しい処理では`true`
`iphone.protected_data_available`	`true`
`iphone.can_trigger_raw_exports`	生データと抽出では`true`
`iphone.can_trigger_exports`	生成ファイルでは`true`

直接接続のstatusは選択済みの保存先を報告しません。ファイルモードで使用するのは、コマンドに明示した--destinationだけです。

Androidのソースでは、iPhoneのトリガーフラグの代わりに、platform: "android"と、app_active、protected_data_available、export_in_progress、利用可能な生データ製品が報告されます。

厳密な生データエクスポート（iPhone）

範囲セレクターを1つ選択します。

healthmd export --yesterday --raw --output yesterday.json
healthmd export --last 7 --raw --output week.json
healthmd export \
  --from 2026-07-01 --to 2026-07-07 --raw --output range.json
healthmd export --all --raw --output complete-health-corpus.json

検証済みJSONを標準出力へストリームするには、--outputを省略します。機密性の高いレスポンスや大きなレスポンスでは、出力ファイルを使用する方が安全です。

iPhoneの厳密な生データエクスポートはhealthmd.raw_result v1を返します。この結果には、通常のschema-v8 healthmd.health_data日次データと、その正規ソースアーカイブが含まれます。iPhoneに保存済みの設定を変更せず、一時的にロスレス詳細を要求します。CLIは結果を公開する前に、正確な日付、プロファイル、スキーマ、アーカイブ、マニフェスト、ダイジェストチェーン、最終本文ダイジェスト、完了状態を検証します。

完全だが空の日は成功です。要求したデータが欠損、一部完了、失敗、キャンセル、未対応、スキップの場合は、partial_successとゼロ以外の終了コードになります。--allow-partialを明示した場合に限り、この終了動作を許容できます。

プロバイダネイティブな生データエクスポート（Android）

ポータブルRustクライアントにバックエンドフラグはないため、Androidの生データコマンドも同じ文法を使用します。

healthmd export --last 7 --raw --provider health_connect \
  --raw-format ndjson --output health-connect.ndjson

--providerは1つの明示的なプロバイダを指定し、既定値はhealth_connectです。--raw-formatの既定値はNDJSONで、大きなスナップショットに推奨される形式です。メモリ内でのJSON検証は64 MiBが上限です。指標の選択では--metricと--all-metricsに対応しますが、正規抽出や生成ファイルのセレクターには対応しません。それらはiPhoneの機能として残ります。

Androidの生スナップショットは、Health Connectのプロバイダネイティブなコントラクトを維持します。HealthKit形式のhealthmd.health_data日次データへ変換されることはなく、関連はするが異なる統計は独自の識別情報を持ち続けます。

正規抽出

直接抽出は、同じ永続的な生データ転送を使用しますが、転送ラッパーではなく、選択したソースに近い形式のデータを返します。これはiPhoneの機能です。

healthmd extract \
  --category Sleep --last 7 --output sleep.json

healthmd extract \
  --metric workouts --last 14 --object records \
  --detail lossless --output workout-records.json

指標、カテゴリ、ソース、詳細レベルの選択は、HealthKitを読み取る前にiPhoneへ到達します。オブジェクトセレクター、JSON Pointer、JSONL、レシートについては、正規抽出を参照してください。

スマートフォンアプリが前面にある間は、一時的な切断後に信頼済み直接接続セッションが回数と待ち時間を制限して自動再接続する場合があります。バックグラウンドのアプリを起こしたりアクセスを保証したりはしません。前面にない場合はHealth.mdを再度開いてから再開してください。

本番エクスポーターによる生成ファイル

直接ファイルモードでは、スマートフォンへHealth.mdの本番エクスポーターを実行するよう要求し、生成されたファイルを明示したコンピューターの保存先へ転送します。

mkdir -p "$HOME/Documents/HealthVault"

healthmd export --yesterday \
  --destination "$HOME/Documents/HealthVault"

healthmd export --last 7 \
  --category Sleep --detail summary \
  --destination "$HOME/Documents/HealthVault"

healthmd export --yesterday --use-iphone-settings \
  --destination "$HOME/Documents/HealthVault"

保存先は、既存の絶対パスで、シンボリックリンクを経由して解決されないものに限ります。直接接続モードは、Macアプリのブックマークを推測したり使用したりしません。--outputは生データまたは抽出結果の出力に、--destinationは生成ファイルの保存先に使用します。

既定のリクエストでは、保存済みの形式、Healthサブフォルダ、ファイル名、テンプレート、書き込みモード、デイリーノートへの挿入、デイリーノートのみの設定を維持します。そのジョブでは、ロールアップとサマリーのみのモードを抑制します。繰り返し指定できる--metricまたは--categoryと--detailは、そのジョブの指標スコープと詳細スコープだけを置き換えます。--use-iphone-settingsは保存済み設定をすべて反映し、セレクターとは併用できません。

iPhoneは、JSON、CSV、Markdown、ZIP、データ辞書、ロールアップ、個別レコード、デイリーノート、プロバイダサイドカーを準備できます。CLIはコミット前に、各相対パス、バイト数、ダイジェスト、ファイルマニフェスト、保存先ID、リクエストフィンガープリントを検証します。パストラバーサル、シンボリックリンクを含む祖先パス、ルートの変更、パスの衝突、ダイジェストの変化を拒否します。上書きはアトミックです。追記とMarkdownマージでは保存済みの計画を使用するため、リプレイで内容が重複することはありません。

生成ファイルの保存先は、iPhoneプロトコルv1とAndroidプロトコルv2の両方で、すべてのCLIオペレーティングシステム（macOS、Linux、Windows）に対応します。Androidでは各生成ジョブの上限は4,096ファイルです。

Androidプロトコルv2のファイルジョブは、デバイスに保存済みの選択または--profile PROFILE_IDから出力設定を取得し、CLIの指標、カテゴリ、詳細セレクターは拒否します。どちらのスマートフォンプラットフォームでも、--profileは固定された出力設定を解決し、必須の--destinationは引き続きコンピュータ上の明示的なフォルダを指定します。安定IDと安全な失敗についてはエクスポートプロファイル.

前面表示とバックグラウンドでの動作

ペアリングと新しい処理の開始時は、スマートフォンのアプリを前面に表示する必要があります。Direct CLI Accessによってスマートフォンがヘッドレスなエクスポートサーバーになることはなく、必要に応じてアプリを起動することもできません。

iPhoneでは、エクスポートが接続済みの状態でアプリがバックグラウンドへ移動すると、Health.mdは、限られたiOSバックグラウンド実行時間を要求します。その時間内にエクスポートが完了する場合があります。iOSによって実行時間が終了されると、接続が閉じ、永続ジョブが一時停止します。Health.mdを再度開き、同じジョブを再開してください。

Androidでは、アクティブな直接接続セッションの間、ユーザーが開始した可視のデータ同期フォアグラウンドサービスが実行されます。ペアリングと新しい処理の開始時は、アプリを前面に表示してください。

iPhoneでは、直接接続の処理中に表示される全体アクティビティバナーが、ヘルスデータの値を表示せずに、取得と転送のフェーズ、完了した日数、バイト単位の進捗、一時停止または完了の状態を示します。

スマートフォンアプリが前面にある間は、信頼済みの直接接続セッションが一時的な切断後に自動再接続することがあります。再試行間隔は徐々に増え、短い上限で止まります。バックグラウンドのアプリを起動したり、アクセスを保証したりするものではありません。アプリが前面にない場合は、再開前にHealth.mdを開き直してください。

120 秒の制限付き待機ウィンドウは、ユーザーが端末のロックを解除して Health.md を開くまで同じリクエストを保持します。--wake-timeout SECONDS で変更でき、0 で無効になります。MCP は HEALTHMD_WAKE_TIMEOUT を使用します。公開済みの alpha.6 バイナリは待機のみです。それ以降の公式ビルドでは、登録済みの iPhone に Health.md の通知専用ウェイクサービスを介してベストエフォートの APNs 通知を 1 回送ります。Android と未登録の iPhone は待機のみのままです。通知はユーザーの操作を促せますが、HealthKit の読み取りを許可したり、Worker を介して健康データの範囲を送信したりすることはありません。

永続ジョブの再開とキャンセル

直接接続ジョブは、作成から7日後に期限切れになります。タイムアウト、Ctrl-C、プロセス終了、切断、バックグラウンド実行時間の終了によって、ジョブがキャンセルされることはありません。

healthmd status --job JOB_UUID
healthmd resume JOB_UUID --timeout 300 --output recovered.json
healthmd cancel JOB_UUID

再開時には、元の日付、設定、保存先、リクエストフィンガープリント、デバイス、パーティションの進行地点を維持します。ファイルジョブの再開時に、別の保存先を指定することはできません。

キャンセル要求は永続的に記録されますが、キャンセルが終端状態になるのはペアリング済みのスマートフォンが確認応答した後だけです。スマートフォンを利用できない場合、statusはcancellation_pendingのままです。同じスマートフォンを再度開き、cancelを再試行してください。

セキュリティモデル

現在のポータブルペアリングは、一時的な鍵共有と、iOS/Android共通の高エントロピーな20桁（約66ビット）コードに紐づくセレクター3のトランスクリプト証明を使用します。従来のAppleセレクター1とAndroidセレクター2のフローは、バイト単位の互換性を維持します。
QRの受け渡しは、正規のプライベートLAN／Tailscaleアドレスを対象に、明示的なアプリ内スキャナーだけが受け付けます。外部のカスタムURLを開いてもペアリングを許可できません。
再接続では、保存済みのランダムなシークレットと両方のインストールIDを証明します。
接続ごとに新しい鍵とnonceを導出します。
メッセージとバイナリフレームでは、単調増加するシーケンス検証を備えたChaCha20-Poly1305を使用します。
パーティションでは、SHA-256マニフェストと連鎖ダイジェストの進行地点を使用します。
iPhoneの信頼情報はKeychainに保存され、Androidの再接続の信頼はKeystoreによって保護されます。
ポータブル版の信頼情報はKeychain、Secret Service、またはWindows Credential Managerを使用し、平文へフォールバックしません。
スプールとジャーナルはアプリ専用ストレージを使用し、プラットフォームが対応している場合はバックアップから除外します。

Manual IPは、ローカルネットワークまたはTailscale上でも暗号化されます。Tailscaleはネットワーク経路も保護しますが、Health.mdのアプリケーション認証を置き換えるものではありません。

一般的なエラー

エラー	対処方法
`direct_not_paired`	このCLIインストールを目的のモバイルソースとペアリングします。
`direct_device_selection_required`	対象の信頼済み`--device`を指定します。
`direct_trust_invalid`	診断情報を保持します。復旧できない場合に限り、信頼情報をリセットします。
`direct_iphone_unavailable`	アプリの前面表示状態、アクセストグル、アドレス、ポート、権限、LANまたはTailscaleの到達可能性を確認します。
`direct_export_paused`	ジョブを確認し、ペアリング済みのスマートフォンを再度開いて再開します。
`direct_cancellation_pending`	ペアリング済みのスマートフォンを再度開き、cancelを再試行します。
`transport_unsupported`	ポータブルクライアントではManual IPまたはTailscaleを使用します。
`backend_unsupported`	同梱Swiftヘルパーのみ：query、evidence、doctor、metricsには既定のMacループバックモードを使用します。スタンドアロンCLIは代わりに`healthmd mcp serve`を使用します。
`invalid_direct_raw_response`	出力を使用しないでください。検証の診断情報を保持します。
`invalid_direct_file_receipt`	ファイルを手作業で修復しないでください。ジョブを確認して再開します。
`job_expired`	7日間の状態保持期間が終了しました。新しい処理を始める前に確認します。