HealthKit Sync

HealthKit Sync CLI

Securely sync Apple HealthKit data from iPhone to Mac over local network using mTLS.

When to Use This Skill

• -User asks about syncing health data from iPhone
• -User mentions healthsync CLI commands
• -User wants to fetch steps, heart rate, sleep, or workout data
• -User needs to pair a Mac with an iOS device
• -User asks about the iOS Health Sync project architecture
• -User mentions certificate pinning or mTLS patterns

CLI Quick Reference

Pairing Flow (First Time)

1. Discover devices on local network
healthsync discover

2. On iOS app: tap "Share" to generate QR code, then "Copy"
3. Scan QR from clipboard (Universal Clipboard)
healthsync scan

Alternative: scan from image file
healthsync scan --file ~/Desktop/qr.png

Fetching Health Data

Check connection status
healthsync status

List enabled data types
healthsync types

Fetch data as CSV (default)
healthsync fetch --start 2026-01-01T00:00:00Z --end 2026-12-31T23:59:59Z --types steps

Fetch multiple types as JSON
healthsync fetch --start 2026-01-01T00:00:00Z --end 2026-12-31T23:59:59Z \
  --types steps,heartRate,sleepAnalysis --format json | jq

Pipe to file
healthsync fetch --start 2026-01-01T00:00:00Z --end 2026-12-31T23:59:59Z \
  --types steps > steps.csv

Available Health Data Types

Activity: steps, distanceWalkingRunning, distanceCycling, activeEnergyBurned, basalEnergyBurned, exerciseTime, standHours, flightsClimbed, workouts Heart: heartRate, restingHeartRate, walkingHeartRateAverage, heartRateVariability Vitals: bloodPressureSystolic, bloodPressureDiastolic, bloodOxygen, respiratoryRate, bodyTemperature, vo2Max Sleep: sleepAnalysis, sleepInBed, sleepAsleep, sleepAwake, sleepREM, sleepCore, sleepDeep Body: weight, height, bodyMassIndex, bodyFatPercentage, leanBodyMass

Configuration

Config stored at ~/.healthsync/config.json (permissions: 0600):

{
  "host": "192.168.1.x",
  "port": 8443,
  "fingerprint": "sha256-certificate-fingerprint"
}

Token stored in macOS Keychain under service org.mvneves.healthsync.cli.

Security Architecture

Certificate Pinning

The CLI validates server certificates by SHA256 fingerprint (TOFU model):

1. First pairing stores fingerprint from QR code

2. Subsequent connections verify fingerprint matches

3. Mismatch = connection rejected (MITM protection)

Local Network Only

Host validation restricts connections to:

• -localhost, *.local domains
• -Private IPv4: 192.168.*, 10.*, 172.16-31.*
• -IPv6 loopback: ::1, link-local: fe80::

Keychain Storage

Tokens never stored in config file - always in Keychain with:

• -kSecAttrAccessibleWhenUnlocked protection class
• -Service: org.mvneves.healthsync.cli
• -Account: token-{host}

Project Structure

ai-health-sync-ios-clawdbot/
├── iOS Health Sync App/          # Swift 6 iOS app
│   ├── Services/Security/        # CertificateService, KeychainStore, PairingService
│   ├── Services/HealthKit/       # HealthKitService, HealthSampleMapper
│   ├── Services/Network/         # NetworkServer (TLS), HTTPTypes
│   └── Services/Audit/           # AuditService (SwiftData)
└── macOS/HealthSyncCLI/          # Swift Package CLI

Troubleshooting

"No devices found":

• -Ensure iOS app is running with sharing enabled
• -Both devices must be on same Wi-Fi network
• -Check firewall isn't blocking mDNS (port 5353)

"Pairing code expired":

• -Generate new QR code on iOS app (codes expire in 5 minutes)

"Certificate mismatch":

• -Delete ~/.healthsync/config.json and re-pair
• -Server certificate may have been regenerated

"Connection refused":

• -iOS app server may not be running
• -Run healthsync status --dry-run to test without connecting

See Also

• -[CLI Reference](references/CLI-REFERENCE.md) - Detailed command documentation
• -[Security Patterns](references/SECURITY.md) - mTLS and certificate pinning patterns
• -[Architecture](references/ARCHITECTURE.md) - iOS app architecture details