whoop-cli

CLI for fetching WHOOP health data via the WHOOP API v2.

npm install -g whoop-cli

Quick Start

whoop-cli auth login           # Authenticate via browser
whoop-cli summary              # One-liner health snapshot
whoop-cli dashboard            # Full health dashboard with 7-day trends

Setup

1. Register a WHOOP application at developer.whoop.com

   • Apps with <10 users don't need WHOOP review (immediate use)

2. Set environment variables:

export WHOOP_CLIENT_ID=your_client_id
export WHOOP_CLIENT_SECRET=your_client_secret
export WHOOP_REDIRECT_URI=https://your-redirect-uri.com/callback

Or create a .env file in your working directory.

3. Authenticate:

whoop-cli auth login

Tokens are stored in ~/.whoop-cli/tokens.json and auto-refresh when expired.

Commands

Data Commands

| Command | Description | | -------------------- | -------------------------------------------- | | whoop-cli sleep | Sleep stages, efficiency, respiratory rate | | whoop-cli recovery | Recovery score, HRV, RHR, SpO2, skin temp | | whoop-cli workout | Workouts with strain, HR zones, calories | | whoop-cli cycle | Daily physiological cycle (strain, calories) | | whoop-cli profile | User info (name, email) | | whoop-cli body | Body measurements (height, weight, max HR) |

Data commands output JSON by default. Use --pretty for human-readable format.

Analysis Commands

| Command | Description | | --------------------------- | ---------------------------------------------- | | whoop-cli summary | One-liner: Recovery, HRV, RHR, sleep, strain | | whoop-cli summary --color | Color-coded with 🟢🟡🔴 status indicators | | whoop-cli dashboard | Full health dashboard with 7-day trends | | whoop-cli trends | Multi-day trend analysis with direction arrows | | whoop-cli insights | Health recommendations based on your data |

Analysis commands output pretty format by default. Use --json for raw JSON.

Auth Commands

| Command | Description | | ------------------------ | ---------------------------------------- | | whoop-cli auth login | OAuth flow (opens browser) | | whoop-cli auth status | Check token status (does not refresh) | | whoop-cli auth refresh | Refresh access token using refresh token | | whoop-cli auth logout | Clear stored tokens |

Options

Data command flags

| Flag | Description | | -------------------- | ---------------------------------- | | -d, --date <date> | Date in ISO format (YYYY-MM-DD) | | -s, --start <date> | Start date for range query | | -e, --end <date> | End date for range query | | -l, --limit <n> | Max results per page (default: 25) | | -a, --all | Fetch all pages | | -p, --pretty | Human-readable output with emojis |

Analysis command flags

| Flag | Applies to | Description | | --------------------- | ---------------------------- | ----------------------------------------- | | -d, --date <date> | summary, dashboard, insights | Date in ISO format | | -n, --days <number> | trends | Number of days: 7, 14, or 30 only | | --json | dashboard, trends, insights | Output raw JSON | | -c, --color | summary | Color-coded output with status indicators |

Global flags (combine data types)

| Flag | Description | | ------------ | ------------------------- | | --sleep | Include sleep data | | --recovery | Include recovery data | | --workout | Include workout data | | --cycle | Include cycle data | | --profile | Include profile data | | --body | Include body measurements |

Usage: whoop-cli --sleep --recovery --body

Running whoop-cli with no arguments fetches all data types.

Output

Data commands output JSON to stdout by default:

{
  "date": "2025-01-05",
  "fetched_at": "2025-01-05T12:00:00.000Z",
  "profile": { "user_id": 123, "first_name": "John" },
  "body": { "height_meter": 1.83, "weight_kilogram": 82.5, "max_heart_rate": 182 },
  "recovery": [{ "score": { "recovery_score": 52, "hrv_rmssd_milli": 38.9 }}],
  "sleep": [{ "score": { "sleep_performance_percentage": 40 }}],
  "workout": [{ "sport_name": "hiit", "score": { "strain": 6.2 }}],
  "cycle": [{ "score": { "strain": 6.7 }}]
}

Analysis commands output formatted text by default.

Keeping tokens fresh

If you run whoop-cli from cron/systemd, you may occasionally see authentication failures if a token refresh is missed or the token file becomes stale.

Important:

• whoop-cli auth status does not refresh tokens — it only reports whether they're expired.
• For automation, you must call whoop-cli auth refresh periodically.

Recommended pattern:

• Run whoop-cli auth login once interactively (creates ~/.whoop-cli/tokens.json).
• Run a small periodic monitor that calls whoop-cli auth refresh and performs a lightweight fetch.

An example monitor script + systemd timer/cron examples are included here:

• examples/monitor/whoop-refresh-monitor.sh
• examples/monitor/systemd/*
• examples/monitor/cron/README-cron.txt

If refresh fails with an expired refresh token, you must re-authenticate:

whoop-cli auth login

Exit Codes

| Code | Meaning | | ---- | -------------------- | | 0 | Success | | 1 | General error | | 2 | Authentication error | | 3 | Rate limit exceeded | | 4 | Network error |

Development

git clone https://github.com/xonika9/whoop-cli.git
cd whoop-cli
npm install
npm run dev      # Run with tsx
npm run build    # Compile TypeScript

Requirements

• Node.js 22+
• WHOOP membership with API access

License

MIT