Healthkit Cli

---
name: healthkit-cli
description: Seed 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:

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

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

Verify connection:

```bash
bunx apple-health status
```

## Seeding Data

### Quick Start

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

```bash
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):

```json
{"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):

```json
{"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**:

```json
{"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:

```json
{"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

```bash
# 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

```bash
# 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:

```bash
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:

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
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:

```bash
bunx apple-health repl
```

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