mirror of
https://github.com/hanzoskill/healthkit-sync.git
synced 2026-10-30 21:09:37 +00:00
3.9 KiB
3.9 KiB
HealthSync CLI Reference
Complete command reference for the healthsync CLI tool.
Commands
healthsync discover [--auto-scan]
Discover HealthSync devices on local network using Bonjour/mDNS.
Options:
--auto-scan- Automatically scan QR from clipboard after discovery
Output:
Searching for HealthSync devices on local network...
Found 1 device(s):
iPhone-Marcus
Host: 192.168.1.42
Port: 8443
Notes:
- Uses
_healthsync._tcpBonjour service type - Timeout: 5 seconds for discovery, 3 seconds per service resolution
- Requires both devices on same Wi-Fi network
healthsync scan [--file <path>] [--name <name>] [--debug-pasteboard]
Scan QR code and pair with iOS device.
Options:
--file <path>- Scan QR from image file instead of clipboard--name <name>- Client name (default: Mac hostname)--debug-pasteboard- Print pasteboard types/sizes to debug Universal Clipboard issues
Clipboard scanning priority:
- JSON text (Universal Clipboard - most reliable)
- PNG image data
- TIFF image data
QR Payload format:
{
"version": "1",
"host": "192.168.1.42",
"port": 8443,
"code": "abc123",
"expiresAt": "2026-01-07T12:05:00Z",
"certificateFingerprint": "a1b2c3..."
}
Validations:
- Version must be "1"
- Host must be local network
- Code must not be expired
- Fingerprint stored for certificate pinning
healthsync pair --host <host> --port <port> --code <code> --fingerprint <fp> [--name <name>]
Manual pairing (alternative to QR scanning).
Options:
--host- iOS device IP address--port- Server port (usually 8443)--code- One-time pairing code--fingerprint- Certificate SHA256 fingerprint--name- Client name (default: Mac hostname)--qr <json>- Full QR payload as JSON string
healthsync status [--dry-run]
Check connection status with paired iOS device.
Options:
--dry-run- Print request without connecting
Output:
Status: ok
Device: iPhone-Marcus
Types: steps, heartRate, sleepAnalysis
Response fields:
status- "ok" or error statedeviceName- iOS device nameenabledTypes- Health data types with permissionserverTime- Server timestamp (for clock sync validation)
healthsync types [--dry-run]
List enabled health data types.
Output:
steps, distanceWalkingRunning, heartRate, sleepAnalysis
healthsync fetch --start <iso> --end <iso> --types <list> [--format csv|json] [--dry-run]
Fetch health data from iOS device.
Required options:
--start- Start date (ISO 8601:2026-01-01T00:00:00Z)--end- End date (ISO 8601:2026-12-31T23:59:59Z)--types- Comma-separated list of types
Optional:
--format- Output format:csv(default) orjson--dry-run- Print request without fetching
CSV output format:
id;type;value;unit;startDate;endDate;sourceName
uuid;steps;1234;count;2026-01-07T08:00:00Z;2026-01-07T09:00:00Z;iPhone
JSON output format:
{
"status": "ok",
"count": 42,
"samples": [
{
"id": "uuid",
"type": "steps",
"value": 1234,
"unit": "count",
"startDate": "2026-01-07T08:00:00Z",
"endDate": "2026-01-07T09:00:00Z",
"sourceName": "iPhone",
"metadata": null
}
]
}
healthsync version
Show version information.
Output:
HealthSyncCLI v1.0.0
Build: 2026-01-07
Platform: macOS (Version 15.3)
Copyright 2026 Marcus Neves
License: Apache-2.0
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Error (message printed to stderr) |
Environment
- Config:
~/.healthsync/config.json(0600 permissions) - Token: macOS Keychain (
org.mvneves.healthsync.cli) - Logs: stderr (errors only)
Build from Source
cd macOS/HealthSyncCLI
swift build
swift test # 39 tests
# Run
.build/debug/healthsync --help