Oura Ring — Personal Health Data

Query your Oura Ring sleep, readiness, activity, HRV, and biometric data via the official Oura API v2. Wraps the zero-dependency oura-cli Python tool — no Node, no Docker, no SaaS middleman, no telemetry. Your tokens stay on your machine.

• Source: https://github.com/zqchris/oura-cli
• Oura API docs: https://cloud.ouraring.com/v2/docs
• License: MIT-0

What this skill unlocks

Once installed, your assistant can answer questions like:

• "How did I sleep last night?" → fetches sleep score, deep/REM/light breakdown, HRV, bedtime
• "Am I recovered enough for a hard workout today?" → fetches readiness, grounds the recommendation
• "What was my HRV trend last week?" → fetches a 7-day range
• "Did my deep sleep improve since I cut alcohol?" → compares date ranges
• "Why was my readiness low on March 12?" → fetches that day's contributors (temperature deviation, prior activity, recovery index, etc.)
• "Show me every workout this month" → fetches the workout endpoint

The skill does not invent numbers — every answer is grounded in a live API call.

Prerequisites

This skill assumes oura-cli is cloned and OAuth-authorized locally. If commands fail with No tokens found or config.json not found, walk the user through setup — do not attempt to resolve automatically:

# 1. Clone the repo (one-time)
git clone https://github.com/zqchris/oura-cli ~/oura-cli
cd ~/oura-cli

# 2. Register an Oura API app at:
#    https://cloud.ouraring.com  →  My Applications  →  New Application
#    - Redirect URI: http://localhost:8080/callback
#    - Scopes: enable all

# 3. Authorize (opens browser; one-time per machine)
uv run oauth-authorize.py --client-id <ID> --client-secret <SECRET>

# 4. Verify
uv run oura-data.py today

After first auth, tokens auto-refresh on HTTP 401. No manual renewal needed.

Quick Reference

All commands run from inside the oura-cli directory:

uv run oura-data.py <subcommand> [--date YYYY-MM-DD | --start ... --end ...]

Subcommands

Date arguments (all data commands except ring and personal)

--date YYYY-MM-DD                       # single day (default: today)
--start YYYY-MM-DD --end YYYY-MM-DD     # date range (any length)

Common Patterns

# Today's full summary (sleep + activity + readiness)
uv run oura-data.py today

# Yesterday's sleep detail
uv run oura-data.py sleep --date $(date -v -1d +%Y-%m-%d)

# Last 7 days of readiness
uv run oura-data.py readiness \
  --start $(date -v -7d +%Y-%m-%d) \
  --end   $(date +%Y-%m-%d)

# Sleep on a specific date
uv run oura-data.py sleep --date 2026-03-15

# Activity for a full month
uv run oura-data.py activity --start 2026-04-01 --end 2026-04-30

# Workouts this week
uv run oura-data.py workout \
  --start $(date -v -7d +%Y-%m-%d) \
  --end   $(date +%Y-%m-%d)

For a Linux date equivalent, replace -v -7d with -d "7 days ago".

Interpreting Output

Scores (0–100, Oura's proprietary scoring)

Temperature deviation (°C from user's 14-day baseline)

• +0.3 °C or more: possible illness, overtraining, alcohol the night before, or warm sleeping environment
• Strongly negative: can correlate with cycle phases for menstruating users
• < ±0.2 °C: noise; don't over-interpret

HRV (RMSSD, milliseconds)

Higher = better autonomic recovery. Always compare to the user's own trend, never to absolute population numbers — individual baselines vary 20–200ms.

Heart rate

• "Lowest HR" during sleep is the most reliable recovery marker
• Resting HR rising 5+ bpm over baseline often precedes illness 24–48h before symptoms

Troubleshooting

Critical Rules

1. Never read, print, or echo tokens.json or config.json — they contain OAuth secrets and client credentials.
2. Always run from the oura-cli directory — token files are resolved relative to the script.
3. Don't fabricate numbers. If the user asks about a date you haven't queried, run the command — don't infer from earlier context.
4. For "should I push hard today" style questions, always fetch today first and ground recommendations in the actual readiness score and HRV.
5. Respect privacy. This is the user's personal health data. Don't persist it to memory, send it to external systems, or include it in unrelated tool calls unless the user explicitly asks.
6. Don't medicalize. Report data and trends; do not diagnose. If the user asks medical questions, recommend they consult a clinician.

Reference Files

• references/api-reference.md — full Oura API v2 endpoint dictionary, scopes, rate limits
• references/example-outputs.md — real sample outputs for each subcommand