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):
- First pairing stores fingerprint from QR code
- Subsequent connections verify fingerprint matches
- 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 - Detailed command documentation
- Security Patterns - mTLS and certificate pinning patterns
- Architecture - iOS app architecture details
