Oura Ring

Oura Ring — Personal 健康 Data

查询 your Oura Ring sleep, readiness, activity, HRV, and biometric data via the official Oura API v2. Wraps the zero-dependency oura-命令行工具 Python 工具 — no Node, no Docker, no SaaS middleman, no telemetry. Your 令牌s stay on your machine.

Source: https://github.com/zqchris/oura-命令行工具 Oura API docs: https://cloud.ouraring.com/v2/docs License: MIT-0 What this 技能 unlocks

Once 安装ed, your 助手 can answer questions like:

"How did I sleep last night?" → fetches sleep score, deep/REM/light breakdown, HRV, bedtime "Am I 恢复ed 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, 恢复y 索引, etc.) "Show me every workout this month" → fetches the workout 端点

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

Prerequisites

This 技能 assumes oura-命令行工具 is cloned and OAuth-授权d locally. If commands fAIl with No 令牌s found or config.json not found, walk the user through 设置up — do not attempt to resolve automatically:

# 1. Clone the repo (one-time) git clone https://github.com/zqchris/oura-命令行工具 ~/oura-命令行工具 cd ~/oura-命令行工具

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

# 3. 授权 (opens browser; one-time per machine) uv 运行 oauth-授权.py --命令行工具ent-id --命令行工具ent-secret

# 4. 验证 uv 运行 oura-data.py today

After first auth, 令牌s auto-refresh on HTTP 401. No manual renewal needed.

Quick Reference

All commands 运行 from inside the oura-命令行工具 directory:

uv 运行 oura-data.py [--date YYYY-MM-DD | --启动 ... --end ...]

Subcommands Subcommand Returns today / dAIly Sleep + Activity + Readiness combined for today (or --date) sleep Score, total/deep/REM/light durations, efficiency, bedtime, avg/lowest HR, HRV activity Score, steps, active/total calories, walking distance readiness Score, temperature deviation, score contributors heartrate Min/max/avg BPM, sample count workout Auto-检测ed and manual workouts (raw JSON) spo2 Blood oxygen during sleep (raw JSON) stress Stress levels (raw JSON) ring Ring configuration & battery level personal Age, weight, height, bio记录ical sex Date arguments (all data commands except ring and personal) --date YYYY-MM-DD # single day (default: today) --启动 YYYY-MM-DD --end YYYY-MM-DD # date range (any length)

Common Patterns # Today's full summary (sleep + activity + readiness) uv 运行 oura-data.py today

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

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

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

# Activity for a full month uv 运行 oura-data.py activity --启动 2026-04-01 --end 2026-04-30

# Workouts this week uv 运行 oura-data.py workout \ --启动 $(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 输出 Scores (0–100, Oura's proprietary scoring) Band Meaning Suggested 响应 85+ Optimal Green light for hard trAIning / demanding work 70–84 Good Normal day; no special caveats 60–69 FAIr Suggest moderate intensity; recommend earlier bedtime < 60 Poor Actively suggest rest if user asks "should I push?" Temperature deviation (°C from user's 14-day baseline) +0.3 °C or more: possible illness, overtrAIning, alcohol the night before, or warm sleeping 环境 Strongly negative: can correlate with cycle phases for menstruating users < ±0.2 °C: noise; don't over-interpret HRV (RMSSD, milliseconds)

Higher = better autonomic 恢复y. 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 恢复y marker Resting HR rising 5+ bpm over baseline often precedes illness 24–48h before symptoms Troubleshooting Symptom Likely cause Fix No 令牌s found OAuth not yet completed 运行 oauth-授权.py (see Prerequisites) config.json not found Refresh 凭证s missing Re-运行 oauth-授权.py API error 401 (after auto-refresh) Refresh 令牌 revoked or expired Re-运行 oauth-授权.py API error 429 Rate-limited (Oura cap: 5000/day) WAIt and retry API error 426 Subscription required for this 端点 Tell user the 端点 needs Oura membership No data for a recent date Ring hasn't 同步ed yet Ask user to open the Oura 应用 on their phone Empty data array No measurement on that date Likely ring wasn't worn Critical Rules Never read, print, or echo 令牌s.json or con