clawdbot/skills/whoopskill/SKILL.md

name, description, homepage, metadata

name	description	homepage	metadata
whoopskill	WHOOP health data CLI - sleep, recovery, strain, workouts via OAuth2.	https://github.com/koala73/whoopskill	clawdbot emoji requires 💪 bins env whoopskill WHOOP_CLIENT_ID WHOOP_CLIENT_SECRET WHOOP_REDIRECT_URI

whoopskill

CLI for fetching WHOOP health data (sleep, recovery, strain, workouts).

Setup

1. Create a WHOOP developer app at https://developer.whoop.com
2. Set environment variables:

   export WHOOP_CLIENT_ID=your_client_id
   export WHOOP_CLIENT_SECRET=your_client_secret
   export WHOOP_REDIRECT_URI=https://your-callback-url
   

3. Install: npm install -g whoopskill
4. Login: whoopskill auth login

Commands

Authentication

whoopskill auth login     # OAuth login flow
whoopskill auth logout    # Clear tokens
whoopskill auth status    # Check token status (shows expiry)
whoopskill auth refresh   # Proactively refresh token (for cron jobs)

Data Fetching

whoopskill sleep --pretty --limit 7      # Last 7 sleep records
whoopskill recovery --pretty             # Today's recovery
whoopskill workout --pretty --limit 5    # Recent workouts
whoopskill cycle --pretty                # Current cycle (strain)
whoopskill summary                       # One-liner snapshot
whoopskill profile                       # User profile
whoopskill body                          # Body measurements

Options

• -d, --date <YYYY-MM-DD> — Specific date
• -l, --limit <n> — Max results (default: 25)
• -a, --all — Fetch all pages
• -p, --pretty — Human-readable output

Token Refresh (Important!)

WHOOP access tokens expire in 1 hour. The CLI auto-refreshes when making API calls, but if you don't use it for a while, the refresh token can also expire (typically 7-30 days).

Best Practice: Keep Tokens Fresh

Set up a cron job to refresh tokens regularly:

# Every 30 minutes - runs an API call which triggers auto-refresh
*/30 * * * * WHOOP_CLIENT_ID=xxx WHOOP_CLIENT_SECRET=yyy whoopskill cycle --limit 1 > /dev/null 2>&1

Or use the explicit refresh command:

*/30 * * * * WHOOP_CLIENT_ID=xxx WHOOP_CLIENT_SECRET=yyy whoopskill auth refresh > /dev/null 2>&1

If Refresh Token Expires

You'll need to re-authenticate:

whoopskill auth login

Example Outputs

Summary

2026-01-07 | Recovery: 68% | Sleep: 74% | Strain: 6.8 | Workouts: 1

Sleep (pretty)

Date: 2026-01-07
Performance: 74%
Duration: 6h 16m
Efficiency: 86%
Stages:
  - Light: 3h 7m
  - Deep: 1h 28m
  - REM: 1h 41m
Disturbances: 2

Token Storage

Tokens are stored in ~/.whoop-cli/tokens.json with 600 permissions.

Troubleshooting

"Missing WHOOP_CLIENT_ID..." — Set env vars before running "Token refresh failed" — Refresh token expired, run whoopskill auth login Empty data — WHOOP API may be delayed; data syncs from device periodically