Introduction
# 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)
```bash # 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
```bash # 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): ```json { "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