CLI Reference

`healthsync parse`

Parse an Apple Health export file into the SQLite database.

healthsync parse <file.zip|export.xml> [flags]

Flag	Short	Description	Default
`--verbose`	`-v`	Enable verbose logging with progress rate	`false`
`--db`		Path to SQLite database	`~/.healthsync/healthsync.db`

Examples:

# Parse a zip export
healthsync parse export.zip

# Parse raw XML
healthsync parse export.xml

# Verbose mode with custom DB
healthsync parse export.zip -v --db ./test.db

Behavior:

Accepts .zip (auto-extracts export.xml) or raw .xml
Streams XML with constant memory (~10MB for 950MB files)
Uses INSERT OR IGNORE for deduplication — safe to re-run
Inserts in batches of 1000 rows per transaction

`healthsync query`

Query health data from the local database.

healthsync query <table> [flags]

Flag	Description	Default
`--from`	Filter records from this date (inclusive)	—
`--to`	Filter records to this date (inclusive)	—
`--limit`	Maximum records to return	`50`
`--format`	Output format: `table`, `json`, `csv`	`table`
`--total`	Deduplicated daily totals (`steps`, `active-energy`, `basal-energy`)	`false`
`--db`	Path to SQLite database	`~/.healthsync/healthsync.db`

Available tables:

CLI Name	DB Table	Data
`heart-rate`	`heart_rate`	BPM
`resting-heart-rate`	`resting_heart_rate`	Daily RHR
`hrv`	`hrv`	HRV SDNN (ms)
`heart-rate-recovery`	`heart_rate_recovery`	Post-exercise HR recovery
`respiratory-rate`	`respiratory_rate`	Breaths/min
`blood-pressure`	`blood_pressure`	Systolic + diastolic (mmHg)
`steps`	`steps`	Step counts — `--total` supported
`active-energy`	`active_energy`	Active kcal — `--total` supported
`basal-energy`	`basal_energy`	Resting kcal — `--total` supported
`exercise-time`	`exercise_time`	Exercise minutes
`stand-time`	`stand_time`	Stand minutes
`flights-climbed`	`flights_climbed`	Flights of stairs
`distance-walking-running`	`distance_walking_running`	Walk/run distance
`distance-cycling`	`distance_cycling`	Cycling distance
`body-mass`	`body_mass`	Body weight
`bmi`	`body_mass_index`	BMI
`height`	`height`	Height
`walking-speed`	`walking_speed`	m/s
`walking-step-length`	`walking_step_length`	m
`walking-asymmetry`	`walking_asymmetry`	%
`walking-double-support`	`walking_double_support`	%
`walking-steadiness`	`walking_steadiness`	Score
`stair-ascent-speed`	`stair_ascent_speed`	ft/s
`stair-descent-speed`	`stair_descent_speed`	ft/s
`six-minute-walk`	`six_minute_walk`	m
`running-speed`	`running_speed`	m/s
`running-power`	`running_power`	W
`running-stride-length`	`running_stride_length`	m
`running-ground-contact-time`	`running_ground_contact_time`	ms
`running-vertical-oscillation`	`running_vertical_oscillation`	cm
`spo2`	`spo2`	Blood oxygen (0-1 fraction)
`vo2max`	`vo2_max`	VO2 Max (mL/min·kg)
`sleep`	`sleep`	Sleep stages
`workouts`	`workouts`	All workout types
`wrist-temperature`	`wrist_temperature`	°C deviation
`time-in-daylight`	`time_in_daylight`	Minutes
`dietary-water`	`dietary_water`	mL/L
`physical-effort`	`physical_effort`	MET
`walking-heart-rate`	`walking_heart_rate`	BPM while walking
`mindful-sessions`	`mindful_sessions`	Mindfulness sessions
`stand-hours`	`stand_hours`	Stand hour achievements

Examples:

# Table output (default)
healthsync query heart-rate --limit 10

# JSON output
healthsync query workouts --format json --limit 5

# CSV with date range
healthsync query steps --from 2024-01-01 --to 2024-12-31 --format csv

# No limit (return all)
healthsync query spo2 --limit 0

# Deduplicated daily step totals
healthsync query steps --total --from 2024-01-01

# Deduplicated daily active energy totals
healthsync query active-energy --total --from 2024-01-01

# Blood pressure history
healthsync query blood-pressure --from 2024-01-01 --format json

# Body weight trend
healthsync query body-mass --limit 30

`healthsync server`

Start an HTTP server for receiving health data uploads and serving queries.

healthsync server [flags]

Flag	Description	Default
`--port`	Port to listen on	`8080`
`--host`	Host to bind to	`0.0.0.0`
`--db`	Path to SQLite database	`~/.healthsync/healthsync.db`

Examples:

# Start with defaults
healthsync server

# Custom port and host
healthsync server --port 9090 --host 127.0.0.1

See the Server API page for endpoint documentation.

`healthsync skills`

Manage the healthsync AI agent skill — install, uninstall, or check status.

healthsync skills <subcommand> [flags]

The skill teaches AI coding agents (Claude Code, Codex CLI, OpenClaw, etc.) how to query your Apple Health data. It includes the database schema, CLI reference, and SQL query examples. Once installed, agents pick it up automatically on next session start.

`healthsync skills install`

healthsync skills install [--agent <target>]

Flag	Description	Default
`--agent`	Agent target: `claude`, `codex`, `openclaw`, or `all`	interactive picker

Install destinations:

Agent	Directory
`claude`	`~/.claude/skills/healthsync/`
`codex`	`~/.agents/skills/healthsync/`
`openclaw`	`~/.openclaw/skills/healthsync/`

Examples:

# Interactive picker (detects installed agents)
healthsync skills install

# Install for Claude Code specifically
healthsync skills install --agent claude

# Install for all supported agents
healthsync skills install --agent all

`healthsync skills uninstall`

healthsync skills uninstall [--agent <target>]

Removes the skill directory for the selected agent(s).

healthsync skills uninstall --agent claude

`healthsync skills status`

healthsync skills status

Shows whether the skill is installed for each supported agent, and whether the installed version matches the current binary.

healthsync skill (binary v0.5.0):
  ✓ claude       ~/.claude/skills/healthsync/ (installed v0.5.0)
  ✗ codex        ~/.agents/skills/healthsync/ (not installed)
  ✗ OpenClaw     ~/.openclaw/skills/healthsync/ (not installed)

`healthsync version`

Print version, commit hash, and build date.

healthsync version

healthsync v0.3.0 (commit bc829bc, built 2026-02-25T10:00:00Z)