ouracli - Oura Ring Health Data CLI

A clean, deterministic command-line interface for accessing and analyzing your Oura Ring health data.

Zero dependencies • TypeScript • Runs with Bun

Features

✓ Fetch all Oura Ring health metrics (sleep, activity, readiness, workouts, heart rate, SpO2) ✓ Automatic daily sync via cron ✓ Trend analysis and correlations ✓ Weekly health summaries ✓ Anomaly detection ✓ Local JSONL storage (your data stays on your machine) ✓ Backward compatible with PAI integration

Quick Start

1. Installation

# Clone the repository
cd ~/dev/ouracli

# Install globally with bun
bun link

# Verify installation
ouracli --help

2. First-Time Setup

# Run interactive setup
ouracli init

# This will:
# - Create ~/.config/ouracli/ directory structure
# - Prompt for your Oura API token
# - Validate the token

3. Fetch Your Data

# Sync health data (fetches last 7 days)
oura-sync

# View your data
ouracli sleep 2024-12-13 2024-12-20
ouracli activity 2024-12-20
ouracli personal-info

4. Analyze & Summarize

# Analyze trends
oura-analyze trends sleep 30
oura-analyze correlation sleep readiness

# Generate weekly summary
oura-summary

5. Set Up Automatic Sync (Optional)

# Add daily cron job (runs at 8 AM)
bash scripts/setup-cron.sh

Commands

ouracli - Data Fetcher

Fetch data from Oura API:

ouracli init                               # First-time setup
ouracli personal-info                      # Your profile
ouracli sleep [start] [end]                # Sleep metrics
ouracli activity [start] [end]             # Activity & steps
ouracli readiness [start] [end]            # Readiness scores
ouracli workouts [start] [end]             # Workout sessions
ouracli heart-rate [start] [end]           # Heart rate data
ouracli spo2 [start] [end]                 # Blood oxygen levels

oura-sync - Automatic Sync

Fetch and deduplicate last 7 days of data:

oura-sync

oura-analyze - Analysis Tools

Statistical analysis and insights:

oura-analyze trends <metric> [days]         # Trend analysis (default: 30 days)
oura-analyze correlation <m1> <m2>          # Correlation between metrics
oura-analyze anomalies <metric>             # Detect outliers (>2σ from mean)

Metrics: sleep, activity, readiness, spo2, workouts, heart-rate

oura-summary - Weekly Health Summary

Generate comprehensive weekly report:

oura-summary              # This week
oura-summary 2024-12-13   # Specific week (Monday)

Configuration

Directory Structure

~/.config/ouracli/
├── .env                 # API token (never committed!)
├── data/                # JSONL health data
│   ├── sleep.jsonl
│   ├── activity.jsonl
│   ├── readiness.jsonl
│   ├── workouts.jsonl
│   ├── heart-rate.jsonl
│   └── spo2.jsonl
├── logs/                # Sync logs
└── reports/             # Generated summaries

Environment Variables

# Required
OURA_API_TOKEN=your_personal_access_token

# Optional overrides
OURACLI_CONFIG=~/.config/ouracli    # Config directory
OURACLI_DATA=/path/to/data          # Data directory
PAI_DIR=~/.claude                   # Backward compatibility with PAI

Data Format

All data is stored in JSONL format (JSON Lines):

• One JSON object per line
• One record per day/event
• Easy to query with jq, grep, or any text tool

# Example queries
cat ~/.config/ouracli/data/sleep.jsonl | jq '.score'
cat ~/.config/ouracli/data/activity.jsonl | jq '.steps'
cat ~/.config/ouracli/data/sleep.jsonl | jq 'select(.score < 70)'

Migration from PAI

If you're migrating from the PAI-integrated version:

# Run migration script
bash scripts/migrate-from-pai.sh

# This will:
# - Copy data from ~/.claude/data/health/oura/
# - Migrate your API token
# - Update cron job
# - Create backups of everything

Note: Migration is non-destructive. Your PAI data remains untouched.

Examples

Analyze Sleep Trends

$ oura-analyze trends sleep 30

SLEEP TRENDS (Last 30 days)
==================================================
Records: 30
Average: 72.5
Median: 74
Range: 54 - 89
Std Dev: 8.2
Trend: ↑ +0.5/day

Recent (7d): 74.2 (+2)

Find Correlations

$ oura-analyze correlation sleep readiness

CORRELATION: SLEEP vs READINESS
==================================================
Data points: 30
Coefficient: 0.842
Strength: strong
Direction: positive

Interpretation:
  Strong positive relationship detected.
  As sleep increases, readiness tends to increase.

Weekly Summary

$ oura-summary

╔════════════════════════════════════════════════════════════╗
║           WEEKLY HEALTH SUMMARY - Oura Ring               ║
╚════════════════════════════════════════════════════════════╝

Week: 2025-12-15 to 2025-12-21

METRICS OVERVIEW

Sleep
  Average: 68.8/100  ↓
  Range: 54 - 82
  Days: 5/7

KEY INSIGHTS
• ⚠ Sleep needs attention (68.8/100 avg)
• Moderate activity levels (75.4/100 avg)

RECOMMENDATIONS
• Prioritize sleep: Aim for 8+ hours
• Add 2-3 workouts next week

Development

Requirements

• Bun >= 1.0.0 (or Node.js >= 18.0.0)
• TypeScript (included in package)
• Oura Ring & Personal Access Token

Project Structure

~/dev/ouracli/
├── src/
│   ├── ouracli.ts          # Main CLI - data fetcher
│   ├── sync.ts             # Automatic sync daemon
│   ├── analyze.ts          # Statistical analysis
│   └── weekly-summary.ts   # Report generator
├── scripts/
│   ├── setup-cron.sh       # Cron job installation
│   └── migrate-from-pai.sh # Migration helper
├── package.json
├── tsconfig.json
└── README.md

Run Locally

cd ~/dev/ouracli

# Run commands directly
bun run src/ouracli.ts --help
bun run src/sync.ts
bun run src/analyze.ts trends sleep 30
bun run src/weekly-summary.ts

Security & Privacy

• Local Storage: All data stays on your machine
• Token Security: .env file has 600 permissions (user read/write only)
• Never Committed: .env is in .gitignore
• No Cloud: Oura API → Your Computer (no intermediaries)

Troubleshooting

Command not found: ouracli

# Ensure bun bin directory is in PATH
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Or re-link
cd ~/dev/ouracli && bun link

API token error

# Check token is set
cat ~/.config/ouracli/.env

# Or reconfigure
rm ~/.config/ouracli/.env
ouracli init

Data not found

# Run sync first
oura-sync

# Check data location
ls -la ~/.config/ouracli/data/

License

MIT

Author

Jose Valle

Get Your Oura API Token

1. Visit: https://cloud.ouraring.com/personal-access-tokens
2. Click "Create New Personal Access Token"
3. Copy the token
4. Run ouracli init and paste when prompted

Note: OAuth2 migration coming end of 2025 (Oura is deprecating Personal Access Tokens)

Philosophy

This CLI follows these principles:

• Deterministic: Same input → Same output
• Clean: Single responsibility (Oura data access)
• Composable: JSON output pipes to jq, grep, etc.
• Documented: Full help and examples
• Testable: Predictable behavior
• Local-First: Your data, your machine

Zero dependencies. Pure TypeScript. Your health data, under your control.