---
name: "apple_healthkit"
title: "Apple Health"
description: "The user's synced Apple Health (HealthKit) data: daily metrics (steps, distance, calories, heart rate, HRV, VO2max), sleep sessions (stages, quality, efficiency), and workouts."
metadata: { "includeInPrompt": true }
---
# Apple Health
Read the user's synced Apple HealthKit data with the `health-cli` binary. Every
command below takes `--provider healthkit`.
This skill serves iOS devices only. If the user's paired device is not an
iPhone, it has no data for them — check the `platform` field
returned by `device.list` when you are unsure.
# Data Source
Despite syned from apple healthkit, do not assume the data is originated from ios devices only. It could come from other sources/devices which share data with Apple Healthkit.
## When to Use
When the user asks about their synced HealthKit data, sync status, or sources:
- All-day metrics/vitals: steps, distance, calories, heart rate, HRV, VO2max.
- Sleep sessions: stages, quality, efficiency, awakenings.
- Workouts: type, duration, calories, distance, HR.
## Tooling
Binary: `health-cli`. **`--provider healthkit` is required on every command
below** — it is not optional and has no default; omitting it is a usage error.
Commands group by data *shape* under `query`:
- `query metrics --provider healthkit` — all-day metric rollups
- `query samples --provider healthkit` — raw, unbucketed data points (intraday HR/steps, GPS, sleep stages)
- `query sessions --provider healthkit` — discrete sessions: sleep, workout
- `status --provider healthkit` — data-sync status
- `auth connect --provider healthkit`, `auth disconnect --provider healthkit`
- `delete` — **erase stored records** (destructive; see below)
**Multi-device (rare):** when a window spans >1 device the envelope adds
`"multi_node": true` — `query metrics` returns per-device `node_groups`;
`query samples`/`sessions` add a `node_id` to each record (samples CSV gains a
leading `node_id` column). Single-device output is unchanged; never sum or
double-count across devices.
### query metrics — all-day metric rollups
```bash
health-cli query metrics --provider healthkit \
--start-date <YYYY-MM-DD> [--end-date <YYYY-MM-DD>] \
[--interval hourly|daily|weekly] [--fields a,b,c] [--timeout-secs N]
```
`daily-metrics` is the only domain so there is **no `--category`**. One row per
`--interval` bucket (default `daily`). `--start-date` required; `--end-date`
defaults to today. Output is an envelope `{ "coverage": {...}, "records": [...] }`
(see Coverage below).
`--list-fields` reads the metric field names from the synced data →
`{ ok, provider, category, observed_count, fields: [{ name, observed, count? }] }`.
`observed: true` (with a row `count`) means the name is present in this user's
data — those are exactly the names `--fields` matches. `observed: false` means
the build knows the field but nothing has synced yet. If the field set can't be
read the response carries `degraded: true` and every `observed` is `null`.
### query sessions — discrete sessions
```bash
health-cli query sessions --provider healthkit --category sleep|workout \
--start-date <YYYY-MM-DD> [--end-date <YYYY-MM-DD>] [--fields a,b,c]
```
- `sleep` — one row per sleep session.
- `workout` — one row per workout/activity.
Sessions are never bucketed (no `--interval`). Discovery: `--list-categories` →
`{ ok, provider, categories }`; `--list-fields` (needs `--category`) →
`{ ok, provider, category, fields }` (e.g. workout has `is_indoor`).
**Output:** normalized snake_case records; the same concept uses the same field
name (e.g. workout `average_speed_mps`, `elevation_gain_meters`,
`hr_average_bpm`). Session records carry a provider-prefixed `id`
(`healthkit_…`) + `start_datetime`/`end_datetime`/`timezone`; metric buckets
carry `date`/`hour`/`week_start` + `record_count`.
**Coverage:** queries return an envelope `{ "coverage": {...}, "records": [...] }`.
`coverage.complete` is `false` when days in the window aren't synced from the
device; `coverage.warning` then holds the exact `health.backfill` command to backfill the missing data. Results remain partial until the backfill completes.
### query samples — raw, unbucketed data points
```bash
health-cli query samples --provider healthkit --start-date <YYYY-MM-DD> \
[--end-date <YYYY-MM-DD>] [--start-time <HH:MM[:SS]>] [--end-time <HH:MM[:SS]>] \
[--fields <type1,...>] [--limit <n>] [--format stdout|csv] [--output <path>]
health-cli query samples --provider healthkit --list-fields # discover sample types
```
Individual samples — finer than the `query metrics` rollups (intraday HR/steps,
GPS, sleep-stage timelines; `query sessions` gives stage totals only). `--fields`
selects sample **types** (not output columns) — run `--list-fields` to see the
types this user has synced. GPS is `location` (raw lat/lon — don't infer place
names from it). For dense reads use `--output <path>`: it writes CSV into the
agent filesystem for a later script step and prints only a summary, keeping
thousands of rows out of context.
## User Permission Status
Run the `device.describe` tool command and look for the `is_permission_granted`
field for health data, which indicates whether you can sync data from the
user's phone (the device must be online as well). If the user hasn't granted
permission and the phone is online, use
```bash
health-cli auth connect --provider healthkit [--timeout-secs N]
```
and follow the instructions to ask for permission to sync health data.
### Revoke Permission
Apple Health cannot be disconnected through this CLI or an in-chat widget.
Tell the user to go to **settings of the Health app** and edit **data
access for the Muse app**.
### Data Sync Status
After the user grants permission, data can be synced from the iOS device
via the `health.backfill` device command but only when `device.describe` reports
`connection_state: online`.
```bash
health-cli status --provider healthkit [--timeout-secs N] \
[--start-date <YYYY-MM-DD>] [--end-date <YYYY-MM-DD>] [--check-missing-entries]
```
Shows how many records are synced from the device already. With
`--check-missing-entries` (requires `--start-date`):
a deep per-30-min-interval gap report (`unsynced_dates`, `missing_intervals`, …).
### delete — erase stored Apple Health (HealthKit) records
```bash
health-cli delete --provider healthkit --all # every Apple Health record
health-cli delete --provider healthkit --device NODE_ID # one paired device
health-cli delete --provider healthkit --start-date 2026-03-01 --end-date 2026-03-31
```
Use for any request to delete, remove, erase, wipe, or clear HealthKit data.
Never improvise it by moving files, disconnecting the connector, or writing to
the database — those neither remove records nor leave an audit trail. A delete
never spans providers; to clear both, run it once per provider.
`--all` takes no other filter; `--device`/`--start-date`/`--end-date` are used
instead of it. All record kinds go at once — no per-category or per-record-ID
delete. Dates are `YYYY-MM-DD` in `JARVIS_USER_TIMEZONE` or epoch seconds; a
record is in range when it starts before the end and ends after the start, so a
session straddling a bound is included. `--start-date` alone deletes from that
day onward, `--end-date` alone up to and including it.
**Destructive and irreversible**, behind a fresh one-time approval showing the
normalized filters. Run it **once per request** — settle provider, device and
dates in conversation first. Denial exits **code 3** with nothing deleted; that
is final, so report it rather than retrying other filters or the other provider.
**Zero is a success**, not a miss — nothing matched, so say so and stop rather
than widening dates or re-running with `--all`. Report `deleted.records`, not
`total_rows`, which also counts child value rows. Apple Health is device-synced,
so records still on the device can return on a later sync.
## Operating Rules
1. Always check device connect status, user permission status with `device.describe` and data sync status
with `health-cli status --provider healthkit` before querying the data.
2. Pick the command by data shape: `query metrics` (all-day rollups),
`query samples` (raw points — only when individual samples matter; prefer
`metrics` for trends), or `query sessions --category sleep|workout` (discrete
events).
3. Always pass `--provider healthkit` and `--start-date`; `--end-date`
defaults to today. Use current-date context for relative asks ("today",
"last week"); use sample time bounds for narrow intraday windows.
4. **Coverage:** Even after the user grants permission, data from some time
ranges may not be synced yet. If a `query metrics`/`sessions` returns
`coverage.complete: false`, relay/act on `coverage.warning` (run the
`health.backfill` to sync the data, then re-query). Note if the connected device is offline in `device.describe` results, you will not be able to backfill new data.
5. `query metrics` defaults to `--interval daily`; sleep spans midnight (include
both evening start and morning end dates).