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
• gog CLI 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.

Source

GitHub: https://github.com/mudgesbot/samsung-health-skill