CLI téléphone directe

La CLI healthmd se connecte directement à une app Health.md ouverte sur un iPhone ou un téléphone Android. La CLI autonome ne nécessite jamais Health.md for Mac, ne passe jamais par lui et n’offre aucune sélection de back-end. Le téléphone lit le magasin de santé de sa plateforme — HealthKit sur iPhone, Health Connect sur Android —, prépare le résultat dans un stockage protégé et transfère des partitions validées vers la 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

Aperçu · CLI directe portable

Le back-end Swift direct intégré est disponible sur macOS et se jumelle avec l’iPhone. Android avec protocole applicatif v2 fait partie de l’aperçu publiquement distribué du client Rust multiplateforme. Les versions iOS et Android actuelles utilisent le même sélecteur 3 et le même QR universel pour les nouveaux jumelages portables. La connectivité physique de base est confirmée sur les deux plateformes mobiles, mais la matrice de publication complète avec les builds exacts reste en attente ; ce flux demeure donc explicitement non qualifié.

Compatibilité mobile pour 0.1.0-alpha.6

Ce tableau autonome est la matrice applicable à l’aperçu explicitement non qualifié. La connectivité de base avec iPhone et Android est confirmée physiquement ; aucune paire CLI/mobile publique n’a encore terminé et conservé toute la matrice de qualification.

Source mobile	Protocole	Contrepartie tag-SHA exacte / seuil non qualifié	Opérations Rust portables	Statut public
iPhone avec export	sélecteur 3 actuel (1 ancien) / application v1	iOS 3.3.0 (build 202609032317) / iOS 3.0.3	État, brut, extraction, fichiers, reprise, annulation	Connectivité confirmée ; qualification complète en attente
iPhone avec requêtes	sélecteur 3 actuel (1 ancien) / application v1 + requête v3	iOS 3.3.0 (build 202609032317) / iOS 3.0.3	V1 plus MCP/requête locale à 19 outils	Connectivité confirmée ; qualification complète en attente
Android	sélecteur 3 actuel (2 ancien) / application v2	Android 1.8.2 (`versionCode 31`) / Android 1.5.4 (`versionCode 25`)	État, brut natif, fichiers, reprise, annulation	Connectivité confirmée ; qualification complète en attente
Requête MCP typée Android	Non disponible	Non implémentée	Les outils exigent iPhone v3	Non pris en charge

Ce que le mode direct prend en charge

le jumelage unique avec le sélecteur partagé 3 et la reconnexion de confiance avec des sources iPhone (protocole applicatif v1) ou Android (protocole applicatif v2) ;
l’inspection locale des appareils de confiance et la suppression du jumelage ;
l’état de préparation du téléphone en direct ;
l’export brut strict — healthmd.health_data au schéma v8 sur iPhone, instantanés Health Connect natifs du fournisseur sur Android ;
l’extraction canonique sélectionnée (iPhone uniquement) ;
l’export de fichiers générés en production sur les deux plateformes de téléphone ;
l’état et la reprise des tâches locales persistantes ;
l’annulation explicite ;
le serveur stdio healthmd mcp serve dans le même exécutable, avec requêtes typées directes, catalogue de métriques, preuves, interface MCP Apps et repli PNG (iPhone uniquement).

L’utilitaire Swift intégré à Health.md for Mac propose aussi un mode direct compatible, sélectionné avec --backend direct ; la CLI Rust autonome présentée sur cette page est exclusivement directe et n’accepte aucun indicateur de back-end. Les sous-commandes orientées Mac doctor, query, evidence et refresh appartiennent à cet utilitaire intégré et renvoient backend_unsupported dans son mode direct ; elles n’existent pas dans la grammaire Rust autonome et ne basculent jamais vers l’app Mac. Utilisez healthmd mcp serve pour une analyse typée à partir de données actualisées provenant directement de l’iPhone, ou exécutez healthmd setup codex pour configurer et jumeler Codex automatiquement. healthmd mcp schema [TOOL] affiche localement le schéma d’entrée MCP imbriqué exact et des exemples ; utilisez directement healthmd_sleep_sessions pour le sommeil au lieu de traiter la sortie canonique de extract comme l’API de requête typée.

Prérequis

Un binaire healthmd compatible direct et une version Health.md correspondante : iPhone (protocole applicatif v1) ou Android (protocole applicatif v2). Le jumelage Android exige le client Rust portable ; l’utilitaire macOS intégré ne se jumelle qu’avec l’iPhone.
Health.md ouverte au premier plan sur le téléphone pour le jumelage et les nouvelles commandes.
Settings > Mac Sync > Direct CLI Access activé sur l’iPhone, ou Settings → Direct CLI sur Android.
Autorisation de santé de la plateforme (HealthKit ou Health Connect), données protégées, autorisation réseau local et quota d’export disponibles.
Une adresse d’ordinateur joignable et le port TCP 17647 pour Manual IP. Une adresse Tailscale fonctionne.
Une destination absolue existante pour le mode fichiers générés.

La CLI est l’écouteur. Le téléphone se connecte à l’adresse de l’ordinateur saisie dans Direct CLI Access.

Prise en charge des transports

Transport	Utilitaire Swift intégré sur macOS	Client Rust portable
Manual IP sur un LAN	Oui	macOS, Linux, Windows
Adresse Tailscale	Oui	macOS, Linux, Windows
Nearby / MultipeerConnectivity	Oui	Non

Nearby utilise la session Multipeer chiffrée d’Apple, avec les mêmes mécanismes d’authentification et de chiffrement applicatifs Health.md que Manual IP. Le client portable renvoie transport_unsupported pour Nearby.

Jumeler une fois avec Manual IP

Démarrez l’écouteur sur l’ordinateur :

healthmd direct pair --transport manual-ip

Le client Rust portable affiche un QR universel pour iOS et Android et écrit sur stderr son code partagé à 20 chiffres, les adresses candidates de l’ordinateur, le port d’écoute et un code de secours à six chiffres pour les anciennes versions iOS. L’utilitaire macOS intégré continue de n’afficher que son ancien code iPhone à six chiffres. stdout reste réservé au résultat JSON final.

Sur l’iPhone :

Ouvrez Health.md > Settings > Mac Sync > Direct CLI Access et activez l’accès.
Touchez Scanner le QR d’appariement et scannez le QR universel ; le jumelage commence immédiatement après ce scan explicite.
Si le scan est indisponible, sélectionnez Manual IP et saisissez l’adresse, le port et le code partagé à 20 chiffres. Une ancienne CLI peut encore utiliser le code à six chiffres.
Gardez l’app ouverte jusqu’à ce que les deux côtés indiquent la réussite.

Jumeler un téléphone Android

Ouvrez Health.md > Settings → Direct CLI sur le téléphone Android.
Touchez Scanner le QR d’appariement et scannez le QR universel ; le jumelage commence immédiatement après ce scan explicite.
Sans caméra ou autorisation, saisissez manuellement l’adresse, le port et le même code partagé à 20 chiffres.
Gardez l’app ouverte ; Android exécute un service de premier plan de synchronisation de données, visible et démarré par l’utilisateur, pour une session directe active.

Les codes uniques ne sont jamais envoyés sur le réseau ni conservés. Après le jumelage, Keychain ou Android Keystore protège la confiance de reconnexion.

Utilisez un autre port si nécessaire :

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

Continuez à utiliser le même port explicite pour les commandes ultérieures d’état, d’export, de reprise et d’annulation.

Jumeler avec Nearby

Nearby est disponible uniquement dans l’utilitaire Swift intégré :

healthmd direct pair --transport nearby

Sélectionnez Nearby dans Direct CLI Access sur l’iPhone, saisissez le code affiché et gardez les deux appareils ouverts jusqu’à la fin du jumelage. Aucune opération Nearby échouée ne bascule vers Manual IP.

Appareils de confiance

Le jumelage crée une relation de confiance distincte de la synchronisation avec Health.md for Mac.

healthmd direct devices
healthmd direct unpair DEVICE_UUID

Ces commandes lisent ou modifient la confiance locale et ne contactent pas le téléphone. Sur l’iPhone, utilisez Forget Paired CLI pour supprimer l’autre côté ; sur Android, supprimez le jumelage depuis Settings → Direct CLI.

Lorsque plusieurs téléphones sont de confiance, sélectionnez explicitement l’installation voulue :

healthmd --device DEVICE_UUID status

Utilisez healthmd direct reset-trust --confirm uniquement lorsque la confiance locale est corrompue ou appartient à une installation remplacée. Cette commande supprime tous les jumelages directs locaux. Oubliez ces jumelages sur le téléphone avant de recommencer.

Vérifier l’état de préparation en direct

healthmd --transport manual-ip status

Une réponse d’état direct indique l’état de connexion et de sécurité sans valeurs de santé. Le client portable signale la source sous source avec une platform valant ios ou android ; ainsi que les mêmes données sous iphone pour les sources iPhone. Vérifiez ces champs avant de commencer (source iPhone affichée) :

Champ	État prêt
`direct_cli.paired`	`true`
`iphone.connected`	`true`
`iphone.app_active`	`true` pour un nouveau travail
`iphone.protected_data_available`	`true`
`iphone.can_trigger_raw_exports`	`true` pour raw et extract
`iphone.can_trigger_exports`	`true` pour les fichiers générés

L’état direct ne signale aucune destination sélectionnée. Le mode fichier utilise uniquement le --destination explicite fourni à la commande.

Une source Android signale platform: "android" avec app_active, protected_data_available, export_in_progress et ses produits bruts disponibles, à la place des indicateurs de déclenchement iPhone.

Export brut strict (iPhone)

Choisissez un seul sélecteur de plage :

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

Omettez --output pour diffuser le JSON validé vers stdout. Un fichier de sortie est plus sûr pour les réponses sensibles ou volumineuses.

L’export brut strict iPhone renvoie healthmd.raw_result v1 contenant des journées ordinaires healthmd.health_data au schéma v8 et leurs archives sources canoniques. Il demande temporairement le détail sans perte sans modifier les réglages iPhone enregistrés. La CLI valide les dates exactes, le profil, le schéma, l’archive, les manifestes, la chaîne d’empreintes, l’empreinte finale du corps et l’état d’achèvement avant d’exposer le résultat.

Une journée complète-vide est réussie. Les données demandées manquantes, partielles, échouées, annulées, non prises en charge ou ignorées produisent partial_success et une sortie non nulle, sauf si --allow-partial est explicite.

Export brut natif du fournisseur (Android)

Le client Rust portable n’a pas d’indicateur de back-end ; les commandes brutes Android utilisent donc la même grammaire :

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

--provider désigne un fournisseur explicite unique et vaut health_connect par défaut. --raw-format vaut NDJSON par défaut, la forme recommandée pour les instantanés volumineux ; la validation JSON en mémoire est plafonnée à 64 Mio. La sélection de métriques prend en charge --metric et --all-metrics, mais pas les sélecteurs canoniques ou de fichiers générés — ceux-ci restent des capacités iPhone.

Les instantanés bruts Android conservent leur contrat natif Health Connect du fournisseur. Ils ne sont jamais convertis en journées healthmd.health_data façon HealthKit, et les statistiques liées mais différentes conservent leurs propres identités.

Extraction canonique

L’extraction directe utilise le même transport brut persistant, mais renvoie des données structurées comme la source sélectionnée au lieu de l’enveloppe de transport. C’est une capacité iPhone :

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

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

La sélection de métrique, catégorie, source et détail atteint l’iPhone avant les lectures HealthKit. Consultez Extraction canonique pour les sélecteurs d’objets, JSON Pointers, JSONL et reçus.

Tant que l’app reste au premier plan, une session directe approuvée peut se reconnecter automatiquement après une coupure transitoire, avec un nombre et des délais bornés. Cela ne réveille pas une app en arrière-plan et n’en promet pas l’accès ; rouvrez Health.md avant de reprendre.

Fichiers générés en production

Le mode fichier direct demande au téléphone d’exécuter les exportateurs de production de Health.md, puis transfère les fichiers résultants vers une destination explicite sur l’ordinateur.

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"

La destination doit déjà exister, être absolue et ne pas se résoudre via un lien symbolique. Le mode direct ne devine jamais et n’utilise jamais de signet de l’app Mac. --output sert à la sortie brute ou d’extraction ; --destination sert aux fichiers générés.

Par défaut, une requête conserve les formats enregistrés, le sous-dossier Health, les noms de fichiers, les modèles, le mode d’écriture, Daily Note Injection et Daily Notes Only. Elle supprime les roll-ups et le mode résumé seul pour cette tâche. Les options répétables --metric ou --category, plus --detail, remplacent uniquement la portée des métriques et du détail de la tâche. --use-iphone-settings reflète tous les réglages enregistrés et ne peut pas être combiné avec des sélecteurs.

L’iPhone peut préparer JSON, CSV, Markdown, ZIP, dictionnaires de données, agrégations, enregistrements individuels, notes quotidiennes et fichiers annexes de fournisseurs. La CLI valide chaque chemin relatif, nombre d’octets, empreinte et manifeste de fichiers, identité de destination et empreinte de requête avant validation. Elle rejette les traversées, les ancêtres sous forme de liens symboliques, les mutations de racine, les collisions de chemins et les changements d’empreinte. L’écrasement est atomique. L’ajout et la fusion Markdown utilisent des plans persistés afin qu’une relecture ne duplique pas le contenu.

Les destinations de fichiers générés fonctionnent avec le protocole iPhone v1 comme avec le protocole Android v2 sur tous les systèmes d’exploitation de la CLI — macOS, Linux et Windows. Android limite chaque tâche à 4 096 fichiers.

Les tâches de fichiers du protocole Android v2 tirent leurs réglages de sortie des sélections enregistrées sur l’appareil ou de --profile PROFILE_ID ; les sélecteurs CLI de métrique, de catégorie et de détail sont rejetés. Sur les deux plateformes de téléphone, --profile résout des réglages de sortie figés, tandis que le paramètre --destination obligatoire continue de désigner le dossier explicite sur l’ordinateur. Pour les identifiants stables et l’échec sûr, voir Profils d’exportation.

Comportement au premier plan et en arrière-plan

Le jumelage et les nouveaux travaux exigent que l’app du téléphone soit au premier plan. Direct CLI Access ne transforme pas le téléphone en serveur d’export sans interface et ne peut pas réveiller l’app à la demande.

Sur l’iPhone, si un export est déjà connecté lorsque l’app passe en arrière-plan, Health.md demande un temps d’exécution iOS en arrière-plan limité. L’export peut se terminer pendant cette allocation. Si iOS l’expire, la connexion se ferme et la tâche persistante se met en pause. Rouvrez Health.md et reprenez la même tâche.

Sur Android, une session directe active exécute un service de premier plan de synchronisation de données, visible et démarré par l’utilisateur. Gardez l’app au premier plan pour le jumelage et les nouveaux travaux.

Sur l’iPhone, une bannière d’activité globale pendant le travail direct comprend la phase de capture et de transfert, les jours terminés, la progression en octets et l’état en pause ou terminé, sans afficher de valeurs de santé.

Tant que l’application du téléphone reste au premier plan, une session directe approuvée peut se reconnecter automatiquement après une coupure passagère. Les nouvelles tentatives utilisent des délais croissants plafonnés à une courte durée. Cela ne réveille pas une application en arrière-plan et n’en garantit pas l’accès ; rouvrez Health.md avant de reprendre si elle n’est plus au premier plan.

La fenêtre d’attente bornée de 120 secondes conserve la même requête pendant que la personne déverrouille le téléphone et ouvre Health.md. Réglez-la avec --wake-timeout SECONDS ; 0 la désactive. MCP utilise HEALTHMD_WAKE_TIMEOUT. Les binaires alpha.6 publiés se limitent à l’attente. Dans les builds officiels suivants, un iPhone inscrit reçoit aussi une unique notification APNs sans garantie via le service de réveil exclusivement réservé aux notifications de Health.md ; Android et les iPhone non inscrits restent limités à l’attente. La notification peut rétablir la présence de la personne, mais n’autorise jamais une lecture HealthKit et n’envoie aucun périmètre de santé via le Worker.

Reprise d’une tâche persistante et annulation

Les tâches directes expirent sept jours après leur création. Délai d’expiration, Ctrl-C, mort du processus, déconnexion et expiration en arrière-plan ne les annulent pas.

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

La reprise conserve les dates, réglages, destination, empreinte de requête, appareil et limite de partition d’origine. Vous ne pouvez pas pointer une tâche fichier vers une autre destination lors de la reprise.

La commande d’annulation enregistre une requête persistante, mais l’annulation ne devient définitive qu’après accusé de réception par le téléphone jumelé. Si le téléphone est indisponible, l’état reste cancellation_pending. Rouvrez le même téléphone et renouvelez la demande d’annulation.

Modèle de sécurité

Les jumelages portables actuels utilisent un accord de clés éphémère et des preuves de transcription du sélecteur 3 liées à un code partagé iOS/Android à haute entropie de 20 chiffres (~66 bits). Les anciens flux Apple sélecteur 1 et Android sélecteur 2 restent compatibles octet pour octet.
Les transferts QR ne sont acceptés que par les scanners explicites de l’application pour des adresses privées LAN/Tailscale canoniques ; l’ouverture d’une URL personnalisée externe ne peut pas autoriser le jumelage.
La reconnexion prouve un secret aléatoire stocké et les deux identités d’installation.
Chaque connexion dérive de nouvelles clés et de nouveaux nonces.
Les messages et trames binaires utilisent ChaCha20-Poly1305 avec des contrôles de séquence monotones.
Les partitions utilisent des manifestes SHA-256 et une chaîne d’empreintes entre les partitions.
La confiance iPhone est stockée dans Keychain ; la confiance de reconnexion Android s’appuie sur le Keystore.
La confiance portable utilise Keychain, Secret Service ou Windows Credential Manager et ne retombe jamais sur du texte brut.
Les spools et journaux utilisent le stockage privé de l’application et excluent les sauvegardes lorsque la plateforme le permet.

Manual IP reste chiffré sur un réseau local ou Tailscale. Tailscale protège aussi le chemin réseau, mais ne remplace pas l’authentification applicative de Health.md.

Erreurs courantes

Erreur	Action
`direct_not_paired`	Jumelez cette installation CLI avec la source mobile prévue.
`direct_device_selection_required`	Passez le `--device` de confiance voulu.
`direct_trust_invalid`	Conservez les diagnostics. Réinitialisez la confiance uniquement si la récupération est impossible.
`direct_iphone_unavailable`	Vérifiez l’état au premier plan de l’app, le commutateur d’accès, l’adresse, le port, l’autorisation et la joignabilité LAN ou Tailscale.
`direct_export_paused`	Inspectez la tâche, rouvrez le téléphone jumelé et reprenez-la.
`direct_cancellation_pending`	Rouvrez le téléphone jumelé et renouvelez la demande d’annulation.
`transport_unsupported`	Utilisez Manual IP ou Tailscale dans le client portable.
`backend_unsupported`	Utilitaire Swift intégré uniquement : utilisez son mode loopback Mac par défaut pour query, evidence, doctor ou metrics. La CLI autonome utilise `healthmd mcp serve` à la place.
`invalid_direct_raw_response`	Ne consommez pas la sortie. Conservez les diagnostics de validation.
`invalid_direct_file_receipt`	Ne réparez pas les fichiers manuellement. Inspectez et reprenez la tâche.
`job_expired`	La durée de vie de sept jours de l’état est terminée. Confirmez avant de commencer un nouveau travail.