healthkit-cli

Seed and verify HealthKit data in running Expo apps using the apple-health CLI

⭐20stars🔀1forks📁View on GitHub🕐Updated Jan 6, 2026⬇️2downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive interface for seeding and verifying Apple HealthKit data in running Expo applications via the apple-health CLI. It enables developers to streamline the testing of health and fitness apps by facilitating batch data injection, realistic health profile simulations, and precise data querying, ensuring that app logic and visualizations handle HealthKit data accurately.

Use Cases

  • UI/UX Testing: Seed diverse health metrics such as heart rate, step counts, and sleep analysis to verify that the app's dashboards and charts render realistic data correctly.
  • User Profile Simulation: Inject specific data patterns representing different personas (e.g., 'Elite Athlete' vs. 'Sedentary Office Worker') to test personalized app features and health recommendations.
  • Data Logic Verification: Query and aggregate HealthKit samples directly through the CLI to ensure the app is correctly reading, writing, and processing health data.
  • Complex Data Modeling: Simulate intricate health scenarios like realistic sleep cycles or symptom progressions to validate the app's handling of multi-state category samples.
  • Environment Cleanup: Quickly delete specific types of test data within defined time ranges to maintain a clean and predictable development environment.
namehealthkit-cli
descriptionSeed and verify HealthKit data in running Expo apps using the apple-health CLI

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

  1. Include variations: Not every day should have identical values
  2. Consider correlations: Poor sleep → higher resting HR, lower step count
  3. Use appropriate ranges: Elite athletes have lower resting HR than sedentary individuals
  4. Add realistic patterns: Heart rate higher during workouts, lower during sleep
  5. 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