Healthmd CLI Operator

Health.md CLI Operator

Use the installed standalone healthmd. Do not use the monorepo's apps/apple/scripts/healthmd; it runs the legacy Swift compatibility client. The Health.md macOS app is not required.

Rules

• Direct Manual IP/Tailscale is the only portable transport. Never add --transport nearby.
• On macOS/Linux use NO_COLOR=1 TERM=dumb, a hard timeout, and stdin from /dev/null. Give exports longer bounds than status.
• Parse stdout JSON or the explicit output artifact. Add global --json whenever automation requires a structured result; interactive terminals otherwise render readable text. Pairing instructions and health-free progress may use stderr.
• For an unfamiliar shape, run the incomplete command first: healthmd export, extract, resume, cancel, or a selected query returns local healthmd.cli_guidance/1 with requirements and request_sent: false; it does not contact iPhone.
• Never infer execution success from exit status alone. A zero exit may be non-network guidance; require the expected result schema/status before reporting completion. Failures use healthmd.cli_error/1 with help_command and bounded next_actions.
• Ask for physical iPhone actions when needed: open/unlock Health.md, scan a pairing QR with its in-app Direct CLI scanner (which connects automatically), enable Direct CLI Access, enter a fallback code, approve local-network access, or grant HealthKit read access.
• Never print health values unless explicitly requested. Counts, dates, paths, statuses, and diagnostics are enough.
• Never retry an unknown-outcome export blindly. Inspect its durable job first.

user/agent → standalone healthmd listener :17647
  ← authenticated encrypted LAN/Tailscale connection →
open paired iPhone → HealthKit → protected spool → output/destination

The Mac app, loopback port 17645, Mac destination bookmark, and Mac app connection state are irrelevant.

Preflight

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

direct devices reads local trust without contacting iPhone. Pair if the intended iPhone is absent.

Pair

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

While it waits, tell the user to:

1. In foreground Health.md, open Sync → CLI, tap Scan Pairing QR under Direct CLI Access, and scan the displayed image. The in-app scan starts pairing automatically; no second Pair tap is required. Do not open the QR as a custom URL.
2. Keep Health.md foregrounded through success.
3. If in-app scanning is unavailable, open Sync → CLI, enable Direct CLI Access, select Manual IP, and enter the printed LAN/Tailscale address, port, and shared 20-digit code. Use the six-digit Apple code only with a legacy iOS release.

Confirm stdout has healthmd.direct_pairing_result, status: success, and the intended device. After an unknown outcome, inspect healthmd direct devices rather than pairing again.

Pairing is normally one-time. Keep Direct CLI Access enabled and Health.md open for later commands. If several devices are trusted, add global --device DEVICE_UUID. If iPhone saved a non-default port, add global --port PORT to every network operation.

Live readiness

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

Require:

• the source reports connected and a platform of ios or android with readiness fields;
• iphone.connected == true;
• iphone.app_active == true for new work;
• iphone.protected_data_available == true;
• iphone.can_trigger_raw_exports == true for raw/extract;
• iphone.can_trigger_exports == true for generated files;
• no conflicting iphone.active_job_id.

Status reports no destination: direct file mode uses the command's explicit destination. wake_window reports the shared local wait policy plus this device's truthful wake enrollment: unavailable/wait_only without a stored wake credential (no push is sent), available/enrolled when the paired iPhone enrolled wake material. Published alpha.6 binaries are still wait-only; in subsequent official builds an enrolled locked-phone wait sends one best-effort APNs notification. Android remains wait-only until FCM ships. If status fails, report its JSON and ask for the minimum action. Never switch device, port, or transport silently.

Waiting for an unavailable phone

Query, export, extract, resume, and cancel wait up to 120 seconds by default. When health-free progress says the phone is unavailable, ask the user to unlock it and open Health.md; do not stop and re-run the command. Set --wake-timeout SECONDS when a different bounded window is needed, or --wake-timeout 0 for explicit fail-fast behavior. Set the shell's outer timeout longer than the wake window plus the command's operation timeout.

For MCP, configure HEALTHMD_WAKE_TIMEOUT; cancellation interrupts the wait immediately. Only tell the user to expect a notification when a post-alpha.6 build reports the selected iPhone as available/enrolled; delivery is best effort. Otherwise ask them to open Health.md while the P1 window waits. Wake expiry preserves direct_source_unavailable and adds wake_window_seconds. Neither expiry nor local cancellation is terminal phone-side job cancellation.

Strict raw

Prefer output files so health data does not enter logs:

NO_COLOR=1 TERM=dumb timeout 300 \
  healthmd export --yesterday --raw --output yesterday.json </dev/null

NO_COLOR=1 TERM=dumb timeout 600 \
  healthmd export --last 7 --raw --output week.json </dev/null

NO_COLOR=1 TERM=dumb timeout 600 \
  healthmd export --from 2026-07-01 --to 2026-07-07 \
    --raw --output range.json </dev/null

Use --all only when explicitly requested, with a protected path and a large outer timeout. Afterward inspect only status, job ID, requested/retained days, capture summary, missing dates, schema versions, and counts. Never dump the corpus.

A strict partial result exits nonzero unless --allow-partial is explicit. Do not add that flag merely to make automation green.