Healthmd CLI

Health.md CLI

Use the standalone healthmd command. Health.md for Mac is not required.

agent/user → healthmd on macOS, Linux, or Windows
  ← authenticated encrypted Manual IP or Tailscale connection →
foreground Health.md mobile app → HealthKit or Health Connect
  → bounded typed results, canonical data, or generated files

The CLI listens on the computer; the phone connects to the displayed address. It can keep an unavailable request waiting while the user opens Health.md. Published alpha.7 binaries send one best-effort APNs notification when the selected iPhone has enrolled wake material; alpha.6 binaries were wait-only. Android and unenrolled phones remain wait-only. A notification can restore user presence but never authorizes background health access or bypasses app activity, permissions, protected-data controls, quotas, or OS background limits. The CLI is direct-only and has no backend option; it never requires or contacts the Health.md Mac app. Do not add --transport nearby.

Authorization and privacy first

Treat the user's request as authority only for its stated device, operation, metrics/categories, dates, sources, detail, destination, and disclosure level. Ask before widening any of them.

• Default to the smallest useful date and metric scope.
• Get explicit approval before pairing, returning health values in chat, using --all, requesting lossless records, enabling --allow-partial, writing generated files, changing trust, or deleting state.
• Use a user-approved private absolute path outside a repository for health artifacts. Do not assume a synced or shared folder is private.
• Pairing QR images and fallback codes contain short-lived secrets. Render them only to the user; never transcribe, reconstruct, upload, or log them.
• Local stdio means Health.md itself needs no health-data cloud. It does not guarantee local model inference: the MCP host or model provider may process returned values under its own policies.
• Do not diagnose, recommend treatment, infer causation, or label a result healthy, harmful, better, or worse. Preserve exact metric IDs, statistics, units, dates/timezone, source, coverage, missingness, evidence, and limitations.
• Never merge HealthKit HRV SDNN with Health Connect or WHOOP HRV RMSSD.

Verify release compatibility

The 0.1.0-alpha.7 package is an explicitly unqualified public preview. Physical QA has confirmed basic iPhone and Android connectivity, but no public CLI/mobile pair has completed and retained the full release qualification matrix yet. Its source snapshot contains these exact counterparts:

The unqualified protocol floors remain iOS 3.0.3 and Android 1.5.4 (versionCode 25), but protocol implementation and basic connectivity are not release qualification. Check the exact package and mobile build before live work. Do not claim App Store or Play Store compatibility from a marketing version alone.

Authoritative ledger: https://github.com/CodyBontecou/health-md/blob/main/apps/cli/docs/mobile-compatibility.md

Install or verify

healthmd --version
healthmd --help

On macOS or Linux, install the matching preview binaries together:

brew install CodyBontecou/tap/healthmd

For Windows or direct archive installation, use the exact healthmd-cli/v<version> GitHub Release—not repository /releases/latest—and follow that release's checksum, Sigstore, and publisher-verification instructions. Do not mix healthmd and healthmd-mcp versions.

Authorized preview testers may build the exact tag from source:

git clone https://github.com/CodyBontecou/health-md.git
cd health-md
git checkout healthmd-cli/v0.1.0-alpha.7
cd apps/cli
cargo install --locked --path crates/healthmd-cli

Do not use apps/apple/scripts/healthmd; it runs the legacy Swift compatibility client. Linux requires an unlocked freedesktop Secret Service provider such as GNOME Keyring or KWallet. The CLI never falls back to plaintext credentials.

Bound unfamiliar commands

Use the CLI's non-network discovery mode instead of guessing required flags. These commands exit successfully with healthmd.cli_guidance/1, status: guidance, and request_sent: false without opening credentials or contacting a phone:

healthmd export
healthmd extract
healthmd query
healthmd query healthmd_sleep_sessions
healthmd resume
healthmd cancel
healthmd direct
healthmd mcp

A selected query operation returns its complete input_schema, JSON examples, and an argv array. Malformed or runtime failures return healthmd.cli_error/1 with help_command and bounded next_actions; follow those fields instead of scraping message or retrying blindly.

On macOS/Linux use non-interactive execution and a hard process timeout:

NO_COLOR=1 TERM=dumb timeout 15 healthmd --version </dev/null
NO_COLOR=1 TERM=dumb timeout 30 healthmd direct devices </dev/null
NO_COLOR=1 TERM=dumb timeout 30 healthmd status </dev/null

On Windows, use the automation host's process timeout. Give pairing and exports longer bounds than status. Interactive terminals render command guidance, failures, and structured results as readable text; non-interactive pipes and explicit --json emit JSON. Use --json whenever an agent must parse the result. Explicit health streams/artifacts retain their exact bytes, and MCP server startup/transport diagnostics cannot use stdout because MCP reserves it for JSON-RPC. Health-free progress and pairing instructions may use stderr. Parse schema and status or the receipt; never infer execution success from exit status alone—a zero exit can intentionally mean non-network guidance.

Pair once

Pairing creates durable export authority, so obtain approval first:

NO_COLOR=1 TERM=dumb timeout 180 healthmd direct pair </dev/null

For iPhone:

1. In foreground Health.md, open Sync → CLI and enable Direct CLI Access.
2. Tap Scan Pairing QR and scan the displayed image. The in-app scan starts pairing; do not ask for a second Pair tap or open the QR as a custom URL.
3. If scanning is unavailable, select Manual IP and enter the printed address, port, and shared 20-digit code. The six-digit Apple code is only a legacy-CLI fallback.

For Android, open Settings → Direct CLI, tap Scan pairing QR, and scan the same universal image, or enter the same address, port, and shared 20-digit code manually. Camera access is optional. Keep the selected app active through success.

Confirm stdout is healthmd.direct_pairing_result with status: success for the intended phone. After an unknown outcome, inspect healthmd direct devices; do not pair again blindly. Use global --device DEVICE_UUID when several phones are trusted and global --port PORT when the app saved a non-default port.

Local trust commands do not contact the phone:

healthmd direct devices
healthmd direct unpair DEVICE_UUID

Run healthmd direct reset-trust --confirm only with explicit approval. It removes every local pairing; the user must forget the CLI on each phone too.

Bounded wake window

Live query, export, extract, resume, and cancel commands wait up to 120 seconds for the selected phone to become active. Tell the user that the request is waiting and ask them to unlock the phone and open Health.md; the same in-flight command should continue without a re-run. Use --wake-timeout SECONDS for a different command window or --wake-timeout 0 only when fail-fast behavior is explicitly needed. Keep any outer process timeout longer than the wake window plus the operation timeout.

MCP uses HEALTHMD_WAKE_TIMEOUT (0 disables) and may emit notifications/progress. Inspect the selected device's wake_window: alpha.6 binaries do not send push, even if enrollment metadata exists. In alpha.7 and later, available/enrolled for an enrolled iPhone means the wait sends one best-effort APNs notification through Health.md's health-free wake service. Only tell the user to expect a notification when both the build and enrollment support it. Android and unenrolled iPhones remain wait-only. A local timeout or MCP cancellation ends only the waiter; it is not phone-side durable-job cancellation.

Check readiness

NO_COLOR=1 TERM=dumb timeout 30 healthmd status </dev/null

Require the selected phone to be authenticated, active enough for new work, and ready for the requested operation. Respect active_job_id and all protected-data, permission, and capability fields. Status contains no backend or Mac fields; the standalone path is the only path. Direct generated-file mode always uses the explicit --destination; it never uses a Mac bookmark.

Query typed health data

Typed queries currently require a compatible foreground iPhone. For least privilege, pair outside the MCP host and configure:

healthmd mcp serve-read-only

This local stdio profile exposes only readiness, catalog, and typed-query tools. Use full healthmd mcp serve only when the user also approves in-host pairing, generated-file jobs, or full-corpus raw jobs and bounded artifact reads. For Codex, healthmd setup codex configures the full local profile and can open iPhone pairing; review that broader authority with the user first. Android pairing remains an explicit healthmd direct pair workflow.

Query workflow:

1. Call healthmd_doctor before reading health values.
2. Use healthmd_metrics to obtain canonical IDs instead of guessing.
3. Resolve relative dates to exact inclusive dates in the user's intended calendar/timezone.
4. Prefer healthmd_metric_chart for metric series, healthmd_sleep_sessions for sleep, and healthmd_workouts for workouts. Use fixed comparison, coverage, alignment, or evidence tools when they match the question.
5. Set all_pages: true only when complete bounded traversal is needed, or continue the exact opaque next_cursor unchanged.
6. Report requested-scope completion separately from unrelated corpus warnings.

Inspect the exact schema offline before constructing shell arguments. The query OPERATION form returns the same nested schema plus an executable argv example:

healthmd query healthmd_metric_chart
healthmd query healthmd_sleep_sessions
healthmd mcp schema healthmd_metric_chart
healthmd mcp schema healthmd_sleep_sessions

The shell can execute the identical fixed operation without an MCP envelope:

healthmd query healthmd_metric_chart \
  --arguments '{"metrics":{"type":"explicit","metric_ids":["resting_heart_rate"]},"dates":{"type":"exact","range":{"start_date":"2026-07-01","end_date":"2026-07-07"}},"all_pages":true}'

Dates are illustrative; resolve the user's actual request. healthmd extract is a source-data projection, not the typed query API.