npm package: @joselvalle/ouracli
Description: Oura Ring Health Data Command-Line Interface - Standalone health data fetcher and analyzer
Author: Jose Valle
Latest version: 1.0.0

# 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

```bash
# Clone the repository
cd ~/dev/ouracli

# Install globally with bun
bun link

# Verify installation
ouracli --help
```

### 2. First-Time Setup

```bash
# 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

```bash
# 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

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

# Generate weekly summary
oura-summary
```

### 5. Set Up Automatic Sync (Optional)

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

---

## Commands

### `ouracli` - Data Fetcher

Fetch data from Oura API:

```bash
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:

```bash
oura-sync
```

### `oura-analyze` - Analysis Tools

Statistical analysis and insights:

```bash
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:

```bash
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

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
$ 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

```bash
$ 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

```bash
$ 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

```bash
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`

```bash
# 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

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

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

### Data not found

```bash
# 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.**