103 lines
2.9 KiB
Markdown
103 lines
2.9 KiB
Markdown
---
|
|
name: whoopskill
|
|
description: WHOOP health data CLI - sleep, recovery, strain, workouts via OAuth2.
|
|
homepage: https://github.com/koala73/whoopskill
|
|
metadata: {"clawdbot":{"emoji":"💪","requires":{"bins":["whoopskill"],"env":["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:
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
*/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:
|
|
```bash
|
|
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
|