codybontecou/health-md/agentskills

Health.md CLI User Guide

The standalone CLI connects directly to iPhone. The Health.md macOS app is not required.

healthmd on macOS / Linux / Windows
  ← authenticated encrypted Manual IP or Tailscale connection →
open Health.md iPhone app → HealthKit → protected spool
  → validated canonical JSON or production-generated files

The CLI listens on the computer; the phone connects to the address entered in Direct CLI Access. Platform health reads always happen on the phone. Published alpha.6 binaries are wait-only; subsequent official builds can send one best-effort APNs notification when the selected iPhone is enrolled, while Android remains wait-only. A notification cannot authorize health access or bypass app activity, protected-data, permission, local-network, or quota controls.

Direct is the portable default. Do not add --backend mac-app: that adapter is reserved but unimplemented. The portable client supports Manual IP, including Tailscale addresses. Nearby is unsupported.

Basic physical iPhone and Android connectivity is confirmed, but no public CLI/mobile pair is fully qualified yet. Query v3 does not replace application v1 pairing/exports and Android never downgrades to v1. Record exact mobile build IDs during QA; matching versions alone are not full qualification evidence.

Bounded commands

On macOS/Linux, run the unfamiliar CLI non-interactively:

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
NO_COLOR=1 TERM=dumb timeout 300 healthmd export --last 7 --raw --output week.json </dev/null

On Windows, use the automation host's process timeout. Pairing needs enough time for the user to enter the code on iPhone.

Install or verify

healthmd --version
healthmd --help
 
# Explicitly unqualified macOS/Linux public preview
brew install CodyBontecou/tap/healthmd

The formula installs matching healthmd and healthmd-mcp binaries. It does not qualify a CLI/mobile pair; use the exact mobile build named by release evidence. GitHub Releases also provide checksummed archives and installers. To build the same preview 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 install the old helper from the Mac app or use the monorepo's apps/apple/scripts/healthmd wrapper for normal operation; those target 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.

For release archives, use the exact healthmd-cli/v<version> page rather than repository /releases/latest. Verify sha256.sum with its Sigstore bundle and expected workflow identity; require Developer ID/notarization on macOS. On Windows, require the documented Authenticode publisher/timestamp when the signing ledger is qualified; while it is deferred, verify the Sigstore-signed checksum closure and expect one SmartScreen prompt.

Upgrade both binaries together with brew update && brew upgrade healthmd, the exact versioned installer, or cargo install --locked --force healthmd-cli. Before uninstalling, finish/cancel jobs, unpair both sides, and use healthmd direct reset-trust --confirm only when all trust should be erased. brew uninstall healthmd, cargo uninstall healthmd-cli, or binary removal does not delete native credentials, durable state/spools, or exported files. Never erase unknown-outcome job state. Normal signed upgrades retain trust; moving from ad-hoc/unsigned macOS code to Developer ID requires one explicit unpair/re-pair.

For support, share only CLI/OS/architecture and exact mobile build versions, health-free error/status codes, job/request IDs, counts, and artifact digests. Never share raw health output, user paths, credentials, source records, routes, or user-data dates.

Pair once

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

While it waits:

1. Read the six-digit code, candidate computer addresses, and port from stderr.
2. On iPhone open Health.md → Sync → CLI.
3. Enable Direct CLI Access, select Manual IP, and enter the computer's LAN/Tailscale address, port, and code.
4. Keep Health.md foregrounded until stdout returns healthmd.direct_pairing_result with status: success for the intended iPhone.

The default port is 17647. If another port is saved on iPhone, pass it globally on every network command:

healthmd --port 18000 status
healthmd --port 18000 export --yesterday --raw --output yesterday.json

Pairing is one-time. Leave Direct CLI Access enabled and Health.md open for later commands. Use --device DEVICE_UUID when multiple iPhones are trusted.

Local trust commands do not contact iPhone:

healthmd direct devices
healthmd direct unpair DEVICE_UUID

Use healthmd direct reset-trust --confirm only to recover unusable local trust. It removes every local pairing; forget the paired CLI on each iPhone too.

Check readiness

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

Read the JSON:

• backend == "direct" and mac_app == "bypassed": standalone path is active.
• iphone.connected == true: the intended iPhone authenticated.
• iphone.app_active == true: new work can begin.
• iphone.protected_data_available == true: protected export data is accessible.
• iphone.can_trigger_raw_exports == true: raw and extract are ready.
• iphone.can_trigger_exports == true: generated files are ready.
• iphone.active_job_id: another job may already own the service.
• direct_cli.paired == true: direct trust exists.

The direct status destination is intentionally unselected. File mode uses the explicit --destination; it never uses a Mac app bookmark.

Strict raw export

Choose exactly one range: --yesterday, --last N, --from/--to, or --all.

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

Without --output, validated health JSON streams to stdout. Prefer a protected output file. Strict raw returns healthmd.raw_result v1 with public schema-v7 healthmd.health_data documents and temporarily requests lossless records without changing saved iPhone settings.

Complete-empty is success. Missing, failed, cancelled, unsupported, skipped, or partial capture yields partial_success and a nonzero exit unless --allow-partial is explicit. That flag changes only exit status; diagnostics remain.

Canonical extraction

Use extract for selected health objects:

healthmd extract --category Sleep --last 7 --output sleep.json
healthmd extract --metric workouts --last 14 --object workouts --output workouts.json
healthmd extract --metric workouts --last 14 \
  --object records --detail lossless --output workout-records.json
healthmd extract --category Sleep --last 7 --format jsonl --output sleep.jsonl

Extraction requires --metric, --category, a category-implying --object, or --all-metrics. Repeatable --object and --field /JSON/POINTER narrow output. Summary is default; archive/record selectors imply lossless. The canonical source is currently apple_health only.

JSON returns canonical documents or honest projections plus a receipt. JSONL writes its receipt to stderr, or OUTPUT.receipt.json with --output. Never interpret omitted fields as zero. Incomplete extraction emits no retained data unless --allow-partial is explicit.

Production-generated files

On macOS, Linux, or Windows, use an existing absolute non-symlink destination:

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"

The iPhone uses production JSON/CSV/Markdown/ZIP/data-dictionary/roll-up/individual-record/Daily Note/provider exporters. The CLI validates manifests, digests, paths, symlinks, destination identity, and restart-safe overwrite/append/Markdown merge commits.

Default requested-date jobs keep saved formats, subfolder, templates, filenames, write mode, and Daily Note behavior while suppressing roll-ups and summary-only mode. Metric/category/detail selectors replace only that job's acquisition scope. --use-iphone-settings mirrors all saved behavior and cannot combine with selectors.

Protocol v1 treats the destination as an opaque immutable label on iPhone. The receiving host validates and durably binds the native absolute path before sending the request.

Codex and Claude MCP

For Codex, run healthmd setup codex. It safely preserves unrelated Codex settings, configures the absolute healthmd executable with arguments mcp serve, applies approval prompts to export mutations, and opens iPhone pairing when needed. Pairing and MCP deliberately use the same installed executable identity so native credentials never require a second Keychain ACL. healthmd-mcp remains a compatibility launcher: it execs the sibling healthmd on Unix, while Windows serves in-process and supervises its own same-file helper against the same fixed Credential Manager service/account. Do not run MCP serve mode as an interactive shell command.

The server exposes 19 fixed tools for direct readiness, Apple metric catalog, bounded typed queries, charts, sleep, workouts, comparison, coverage, evidence, and durable generated-file exports. Every query runs against the paired foreground iPhone; Health.md for Mac is not involved. Export, resume, and cancel calls require explicit user approval and an export needs an existing destination.

MCP Apps hosts negotiate io.modelcontextprotocol/ui and text/html;profile=mcp-app for the self-contained interactive view. Text/image hosts retain authoritative JSON and a portable PNG metric-chart fallback. Call healthmd_doctor first. Use all_pages: true for bounded automatic cursor traversal, or continue opaque cursors manually.

Use the fixed typed operation directly for analysis: healthmd_sleep_sessions for sleep, healthmd_workouts for workouts, and healthmd_metric_chart for metric series. tools/list supplies complete nested selectors and examples. The shell can run the identical operation as healthmd query TOOL_NAME --arguments 'JSON_OBJECT'; its canonical payload matches MCP before the MCP content envelope is added. Never substitute healthmd extract, which returns a different canonical source-data projection. healthmd mcp schema TOOL_NAME prints the generated shared schema without credentials, a listener, or iPhone access.

Durable jobs

Jobs persist for seven days. Timeout, Ctrl-C, process exit, network loss, or exhausted iOS background time does not cancel them.