Samsung Health Connect CLI
Analyze health data from Samsung Health Connect exported to Google Drive.
Prerequisites
- Samsung Galaxy Watch or Galaxy Ring with Samsung Health
- Samsung Health Connect app with Google Drive backup enabled
gogCLI for Google Drive access (part of Clawdbot)
Installation
cd /path/to/workspace/projects
git clone https://github.com/mudgesbot/samsung-health-skill.git
cd samsung-health-skill
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
Configuration
Create ~/.config/samsung-health/config.yaml:
google_drive:
folder_id: "YOUR_FOLDER_ID" # From Google Drive URL
account: "your.email@gmail.com" # Google account for gog CLI
file_name: "Health Connect.zip"
goals:
daily_steps: 10000
sleep_hours: 8
timezone: "Europe/Copenhagen"
Commands
All commands require activating the venv first:
cd /path/to/samsung-health-skill && source .venv/bin/activate
Sync Data
shealth sync # Download latest from Google Drive
shealth sync --force # Force re-download
Quick Daily View
shealth today # Today's snapshot (steps, sleep, HR, SpO2)
Status
shealth status # Data freshness, record counts, date range
Sleep Analysis
shealth sleep # Last 7 days
shealth sleep --days 14 # Custom period
Shows: duration, stage breakdown (Light/Deep/REM/Awake), trends.
Step Tracking
shealth steps # Last 7 days
shealth steps --week # Weekly view
shealth steps --month # Monthly view
Shows: daily counts, goal progress, streaks.
Heart Rate
shealth heart # Last 7 days
shealth heart --days 14 # Custom period
Shows: average, min/max, daily trends.
Blood Oxygen (SpO2)
shealth spo2 # Last 7 days
shealth spo2 --days 14 # Custom period
Shows: average, range, trend. Normal: 95-100%.
Workouts
shealth workout # Last 30 days
shealth workout --days 90 # Custom period
Shows: session count, duration, types (Walking, Running, Swimming, etc.)
Health Report
shealth report # Comprehensive 7-day summary
shealth report --days 14 # Custom period
Shows: Energy Score, sleep summary, activity, heart rate.
JSON Output
Add --json flag to any command for machine-readable output:
shealth --json today
shealth --json sleep --days 7
shealth --json report
Sleep Stage Codes
| Code | Stage |
|---|---|
| 1 | Light Sleep |
| 4 | Deep Sleep |
| 5 | Awake |
| 6 | REM Sleep |
Exercise Types
| Code | Type |
|---|---|
| 53 | Walking |
| 33 | Running |
| 61 | Hiking |
| 21 | Cycling |
| 58 | Swimming |
| 4 | Weight Training |
| 66 | Yoga |
Troubleshooting
"Database not found" — Run shealth sync first.
"Google Drive not configured" — Create config.yaml with folder_id and account.
SpO2/HRV shows 0 records — Requires Galaxy Watch 4+ or Galaxy Ring; may need enabling in Samsung Health settings.
