Use bunx apple-health to interact with HealthKit through a running Expo app's devtools connection.

Prerequisites

The app must have the devtools hook enabled:

import { useHealthKitDevTools } from "apple-health/dev-tools";

export default function App() { useHealthKitDevTools(); // ... }

Verify connection:

bunx apple-health status

Seeding Data

Quick Start

Use batch mode for efficient bulk writes. Create NDJSON data and pipe to the CLI:

cat << 'EOF' | bunx apple-health batch {"kind":"quantity","type":"heartRate","value":72,"start":"today 8am"} {"kind":"quantity","type":"stepCount","value":8500,"start":"yesterday","duration":"1d"} {"kind":"category","type":"sleepAnalysis","value":4,"start":"-8h","duration":"2h"} {"kind":"workout","activityType":"running","start":"-2h","duration":"45m","energy":450} EOF

Sample Types

Quantity samples (measurements with values):

{"kind":"quantity","type":"heartRate","value":72,"start":"today 8am"} {"kind":"quantity","type":"stepCount","value":10000,"start":"yesterday","duration":"1d"} {"kind":"quantity","type":"dietaryCaffeine","value":150,"start":"today 7am"} {"kind":"quantity","type":"activeEnergyBurned","value":350,"start":"today","duration":"1d"} {"kind":"quantity","type":"bodyMass","value":75,"unit":"kg","start":"today 7am"}

Category samples (events/states with enum values):

{"kind":"category","type":"sleepAnalysis","value":3,"start":"-7h","duration":"6h"} {"kind":"category","type":"headache","value":2,"start":"today 2pm"} {"kind":"category","type":"mindfulSession","value":0,"start":"-1h","duration":"15m"}

Workouts:

{"kind":"workout","activityType":"running","start":"-1h","duration":"30m","energy":300,"distance":5000} {"kind":"workout","activityType":"cycling","start":"today 7am","duration":"1h","energy":500,"distance":25000} {"kind":"workout","activityType":"yoga","start":"yesterday 6am","duration":"45m","energy":150}

Sleep Values

Value Meaning

0 In Bed

2 Awake

3 Core Sleep (light)

4 Deep Sleep

5 REM Sleep

Realistic sleep pattern example:

{"kind":"category","type":"sleepAnalysis","value":0,"start":"-8h","duration":"8h"} {"kind":"category","type":"sleepAnalysis","value":3,"start":"-7h45m","duration":"45m"} {"kind":"category","type":"sleepAnalysis","value":4,"start":"-7h","duration":"1h"} {"kind":"category","type":"sleepAnalysis","value":5,"start":"-6h","duration":"30m"} {"kind":"category","type":"sleepAnalysis","value":3,"start":"-5h30m","duration":"2h"} {"kind":"category","type":"sleepAnalysis","value":5,"start":"-3h30m","duration":"45m"} {"kind":"category","type":"sleepAnalysis","value":3,"start":"-2h45m","duration":"2h"}

Symptom Values

Value Meaning

0 Not Present

1 Mild

2 Moderate

3 Severe

Date Formats

Format Example Description

now

"start":"now"

Current time

today

"start":"today"

Start of today

yesterday

"start":"yesterday"

Start of yesterday

Relative days "start":"-1d"

1 day ago

Relative hours "start":"-2h"

2 hours ago

Relative minutes "start":"-30m"

30 minutes ago

Day + time "start":"today 8am"

Today at 8:00 AM

ISO8601 "start":"2026-01-04T08:00:00Z"

Exact timestamp

Duration uses same format: "duration":"1h30m" , "duration":"1d" , etc.

Data Profiles

Reference values for realistic data generation:

Healthy Active Person

• Resting HR: 55-65 bpm

• Steps: 8,000-12,000/day

• Sleep: 7-8 hours, good quality

• Workouts: 4-5x/week

• Water: 2-3L/day

Sedentary Office Worker

• Resting HR: 70-80 bpm

• Steps: 2,000-4,000/day

• Sleep: 5-6 hours, fragmented

• Workouts: 0-1x/week

• Caffeine: 300-500mg/day

Elite Athlete

• Resting HR: 45-55 bpm

• Steps: 15,000-25,000/day

• Sleep: 8-9 hours, high quality

• Workouts: 10-14x/week (doubles)

Stressed Individual

• Resting HR: 80-95 bpm

• Steps: 2,000-3,500/day

• Sleep: 4-5 hours, poor quality

• Symptoms: headaches, fatigue

• Caffeine: 400-600mg/day

Verifying Data

Query Samples

Query recent samples

bunx apple-health query quantity heartRate --limit 10 bunx apple-health query category sleepAnalysis --limit 5 bunx apple-health query workouts --limit 5

With date range

bunx apple-health query quantity stepCount --start "-7d" --end "now" --limit 100

Get Statistics

Single stat

bunx apple-health stats stepCount

With aggregations

bunx apple-health stats heartRate --aggregations "discreteAverage,discreteMin,discreteMax"

Time-bucketed (daily, weekly, etc.)

bunx apple-health stats stepCount --interval day --start "-7d" bunx apple-health stats heartRate --interval hour --start "today"

JSON Output

Add --json flag for machine-readable output:

bunx apple-health query quantity heartRate --limit 5 --json bunx apple-health stats stepCount --interval day --start "-7d" --json

Individual Writes

For single samples without batch mode:

Quantity samples

bunx apple-health write quantity heartRate 72 bunx apple-health write quantity heartRate 85 --start "today 8am" bunx apple-health write quantity stepCount 5000 --start "yesterday" --duration "1d"

Category samples

bunx apple-health write category sleepAnalysis 3 --start "-8h" --duration "7h" bunx apple-health write category headache 2 --start "-2h"

Workouts

bunx apple-health write workout running bunx apple-health write workout cycling --start "today 7am" --duration "1h" --energy 450 --distance 25000

Deleting Test Data

Delete specific type within time range

bunx apple-health delete stepCount --start "-30d" --end "now" bunx apple-health delete heartRate --start "-30d" --end "now"

Authorization

Check and request permissions before writing:

Check authorization status

bunx apple-health auth status stepCount heartRate

Request authorization

bunx apple-health auth request --read "stepCount,heartRate" --write "stepCount,heartRate"

Available Types

List all available types:

bunx apple-health types

Filter by category

bunx apple-health types --category Vitals bunx apple-health types --category Nutrition

Common quantity types:

• Body: bodyMass , height , bodyFatPercentage , bodyMassIndex

• Fitness: stepCount , distanceWalkingRunning , activeEnergyBurned , flightsClimbed

• Vitals: heartRate , restingHeartRate , bloodPressureSystolic , oxygenSaturation

• Nutrition: dietaryCaffeine , dietaryWater , dietaryEnergyConsumed , dietaryProtein

Common category types:

• Sleep: sleepAnalysis

• Symptoms: headache , fatigue , nausea , dizziness

• Mindfulness: mindfulSession

Workout types: running , walking , cycling , swimming , yoga , hiking , highIntensityIntervalTraining , traditionalStrengthTraining , and 70+ more.

Tips for Realistic Data

• Include variations: Not every day should have identical values

• Consider correlations: Poor sleep → higher resting HR, lower step count

• Use appropriate ranges: Elite athletes have lower resting HR than sedentary individuals

• Add realistic patterns: Heart rate higher during workouts, lower during sleep

• Distribute over time: Use relative time formats to spread data across days

Interactive Mode

For exploratory testing, use the REPL:

bunx apple-health repl

apple-health> write quantity heartRate 72 apple-health> query quantity heartRate 5 apple-health> stats stepCount day apple-health> exit