WHOOP Skill

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

Install

npm install -g whoopskill

Quick Start

# One-liner health snapshot
whoopskill summary
# Output: 2026-01-05 | Recovery: 52% | HRV: 39ms | RHR: 60 | Sleep: 40% | Strain: 6.7

# Human-readable output
whoopskill --pretty

# JSON output (default)
whoopskill

Setup

Before using, you need to configure WHOOP API credentials:

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.

1. Authenticate:

whoopskill auth login

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

Usage

# Fetch all today's data
whoopskill

# One-liner health snapshot
whoopskill summary

# Human-readable output
whoopskill --pretty

# Specific data type
whoopskill profile
whoopskill body
whoopskill sleep
whoopskill recovery
whoopskill workout
whoopskill cycle

# Multiple types
whoopskill --sleep --recovery --body

# Specific date (ISO format)
whoopskill --date 2025-01-03

# Pagination
whoopskill workout --limit 50
whoopskill workout --all

Auth Commands

whoopskill auth login    # OAuth flow (opens browser)
whoopskill auth status   # Check token status
whoopskill auth refresh  # Refresh access token using refresh token
whoopskill auth logout   # Clear tokens

Keeping tokens fresh (recommended for cron/servers)

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

Important:

• whoopskill auth status does not refresh tokens — it only reports whether they’re expired.
• For automation, you must call whoopskill auth refresh periodically.

Recommended pattern:

• Run whoopskill auth login once interactively (creates ~/.whoop-cli/tokens.json).
• Run a small periodic monitor that calls whoopskill 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:

whoopskill auth login

Data Types

Options

Output

JSON to stdout by default. Use --pretty for human-readable format.

{
  "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 }}]
}

Exit Codes

Requirements

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

Development

git clone https://github.com/koala73/whoopskill.git
cd whoopskill
npm install
npm run dev      # Run with tsx
npm run build    # Compile TypeScript

License

MIT