whoop-up

Fetch, analyze, and visualize WHOOP health metrics via CLI: sleep, recovery, HRV, strain, workouts, and interactive charts.

Quick start

whoop summary --color                            # color-coded daily snapshot
whoop dashboard                                  # full dashboard + 7-day trends
whoop trends --days 14                           # 14-day trend analysis
whoop chart dashboard -n 30 -o /tmp/whoop.html  # interactive HTML chart

Commands

Chart types: sleep · recovery · strain · hrv · dashboard Get types: sleep (UUID string) · workout (UUID string) · cycle (integer)

Flags

Key behaviors

• •Data commands → JSON by default; add --pretty for formatted output
• •Analysis commands → pretty by default; add --json for raw data
• •WHOOP day boundary is 4:00 AM, not midnight
• •Tokens stored at ~/.whoop-up/tokens.json, auto-refresh 15 min before expiry
• •trends --days only accepts 7, 14, or 30
• •chart commands open browser automatically; use -o file.html to save instead
• •get sleep <id> — id is a UUID string; get cycle <id> — id is an integer
• •Rate limits: 100 req/min, 10,000 req/day — avoid rapid repeated calls

Answering questions

Key metrics

• •Recovery (0–100%): Green ≥67%, Yellow 34–66%, Red <34%
• •Strain (0–21): Daily exertion. Optimal target: Green day ~14, Yellow ~10, Red ~6
• •HRV (ms): Higher = better recovery. Track vs personal baseline, not population norms
• •RHR (bpm): Lower = better fitness. Rising RHR signals fatigue or illness
• •Sleep Performance (%): Actual sleep vs. sleep needed. Green ≥85%, Yellow ≥70%
• •Sleep Efficiency (%): Time asleep / time in bed. Target ≥85%
• •SpO2 (%): Blood oxygen. Normal 95–100%. Values <94% warrant attention
• •Skin temp (°C): Deviation from personal baseline — elevation may signal illness

Health analysis

When the user asks about health, trends, or wants deeper interpretation, use references/health_analysis.md for:

• •Science-backed interpretation of HRV, RHR, sleep stages, recovery, strain, SpO2
• •Normal ranges by age and fitness level
• •Pattern detection (sleep debt, overtraining signals, day-of-week effects)
• •Actionable recommendations based on data
• •Red flags that suggest medical consultation

Analysis workflow

1. •Status — whoop summary --color (today's snapshot)
2. •Trends — whoop trends --days 14 --json (direction of key metrics)
3. •Patterns — correlate: late workouts → poor sleep, high strain → low HRV next day
4. •Insights — whoop insights (automated recommendations)
5. •Flags — RHR rising >5 bpm, HRV <80% of 7-day average, SpO2 <94%

Always include: "This is not medical advice."

God mode: composite commands for deep insights

Best single command for LLM analysis:

whoop dashboard --json

Most data-dense: today's full snapshot (profile + recovery + sleep + cycle + workout) plus 7-day arrays of recovery, sleep, and cycle history — all in one JSON blob.

Full daily picture (formatted for human reading):

whoop dashboard        # today + 7-day terminal dashboard
whoop insights         # health recommendations

30-day deep dive (maximum historical context):

whoop trends --days 30 --json
whoop sleep -n 30 --all --pretty
whoop recovery -n 30 --all --pretty
whoop workout -n 30 --all --pretty

Visual analysis (save charts to files):

whoop chart dashboard -n 30 -o /tmp/whoop-dashboard.html
whoop chart hrv -n 90 -o /tmp/whoop-hrv.html
whoop chart sleep -n 30 -o /tmp/whoop-sleep.html
whoop chart recovery -n 30 -o /tmp/whoop-recovery.html

Drill into a specific record (use IDs from dashboard --json output):

whoop get sleep <uuid>          # full detail for one sleep record
whoop get cycle <id>            # full detail for one day's cycle
whoop cycle-sleep <cycleId>     # sleep linked to that cycle
whoop cycle-recovery <cycleId>  # recovery linked to that cycle

Recommended god mode workflow:

1. •whoop dashboard --json — current state + 7-day history
2. •whoop trends --days 30 --json — 30-day trend context
3. •whoop --sleep --recovery --workout --cycle -n 30 --all — raw data for all key metrics
4. •Feed all JSON to LLM: correlate HRV↔sleep, recovery↔strain, sleep duration↔workout performance
5. •whoop chart dashboard -n 30 -o /tmp/whoop.html — visual confirmation

Example output

whoop summary --color:

📊 7-Day Summary

🔴 Avg Recovery:  31.5%
💓 Avg HRV:       124.4ms
❤️  Avg RHR:       56.1bpm
🔴 Avg Sleep:     44.8% | 4.0h
🔥 Avg Strain:    6.8

whoop dashboard:

📅 2026-02-17 | YOUR_NAME

── Recovery ──────────────────────────
🔴 13% | HRV: 129ms (↑ vs 124 avg) | RHR: 60bpm (↑ vs 56 avg)
   SpO2: 96% | Skin: 33.1°C | Resp: 15.6/min

── Sleep ─────────────────────────────
😴 27% | 2.0h total | Efficiency: 100%
   Deep: 1.0h (49%) | REM: 0.6h (30%) | Light: 0.4h
   Disturbances: 1 | Consistency: 66%
   💤 Sleep debt: 2.1h | Need tonight: 9.7h

── Strain ────────────────────────────
🔥 4.1 / 6 optimal | 767 cal

── 7-Day Trends ──────────────────────
   HRV:      148 → 129ms ↓  (range 66-179)
   RHR:      49 → 60bpm ↑  (range 49-64)
   Recovery: 44 → 13% ↓
   Sleep:    4.6 → 2.0h ↓
   Strain:   6.8 avg (range 4.1-16.4)

whoop trends --days 7:

📊 7-Day Trends

💚 Recovery: 31.5% avg (5-85) ↓
💓 HRV: 124.4ms avg (66-179) ↓
❤️ RHR: 56.1bpm avg (49-64) ↑
😴 Sleep: 44.8% avg (25-78) ↓
🛏️ Hours: 4.3h avg (1.3-7.2) ↓
🔥 Strain: 6.8 avg (4.1-16.4) ↓

whoop insights:

💡 Insights & Recommendations

🔴 Red Recovery
   Recovery at 13% — body needs rest.
   → Prioritize rest, hydration, and sleep tonight.

🔴 Significant Sleep Debt
   You have 2.1 hours of accumulated sleep debt.
   → Try to get to bed 30-60 min earlier for the next few days.

References

• •references/health_analysis.md — science-backed health data interpretation guide