Health.md started with a simple boundary: read health data on the phone, then put the result in files the user controls. The standalone healthmd CLI extends that boundary to macOS, Linux, and Windows without routing through the Health.md Mac app or a Health.md cloud service.
The paired app performs each Apple Health or Health Connect read. The CLI receives authenticated, encrypted, validated results over Manual IP or Tailscale.
Pair once
healthmd direct pair
The current universal flow displays a QR code and a high-entropy pairing code. Open Health.md → Direct CLI Access on iPhone or Android, scan or enter the handoff, verify the computer, and keep the app open while new work begins. Reconnect trust is stored in the operating system credential service.
Then start small:
healthmd status
healthmd export --yesterday --raw --output yesterday.json
healthmd export --yesterday --destination "$HOME/Documents/HealthVault"
An iPhone source also supports canonical extraction and typed queries:
healthmd extract --category Sleep --last 7 --output sleep.json
healthmd query healthmd_sleep_sessions \
--arguments '{"dates":{"type":"all_available"},"all_pages":true}'
Android preserves provider-native Health Connect snapshots rather than pretending they are HealthKit documents.
Durable rather than disposable
A terminal timeout or network drop does not silently turn accepted work into failure. Direct exports are seven-day durable jobs:
healthmd status --job JOB_UUID
healthmd resume JOB_UUID --timeout 300 --output recovered.json
healthmd cancel JOB_UUID
Resume retains the immutable source, dates, scope, destination, request fingerprint, and committed partition frontier. Cancellation becomes terminal only after the phone acknowledges it.
Connect an agent
For Codex:
healthmd setup codex
For Claude or another local MCP host, configure the absolute healthmd executable with arguments mcp serve. Call healthmd_doctor first, list metric IDs, and request an exact date and metric scope.
The published 0.1.0-alpha.7 portable preview exposes 19 tools. Current development source adds two approval-gated full-corpus raw-artifact tools for a total of 21; those tools are not a released alpha.7 promise. The serve-read-only entry remains limited to 13 readiness and typed-query tools.
What stays private
- The phone performs platform health reads.
- There is no Health.md health-data cloud hop or account.
- Pairing and transport are authenticated and encrypted.
- Query requests carry explicit dates, metrics, sources, and detail.
- Large raw bodies go to validated files or a private durable spool, not automatically into a model conversation.
- Coverage, partial outcomes, missing dates, and unsupported types stay visible.
This is factual data access, not medical advice. Agents should preserve units, evidence, missingness, and limitations rather than diagnosing or calling a direction better or worse.
Preview status
The portable package remains an explicitly unqualified preview. Use the exact healthmd-cli/v<version> release and matching mobile build named by release evidence. Do not use the repository-wide /releases/latest pointer; it remains reserved for Apple app releases.
Install the published preview on macOS or Linux:
brew install CodyBontecou/tap/healthmd
healthmd --version
Windows archives and the PowerShell installer are published per version. Verify the release checksums and signatures before running downloaded binaries.