Your WHOOP data, from the terminal. Built for humans and agents.
Based on whoopskill by @koala73.
git clone https://github.com/TomasWard1/whoop-cli.git
cd whoop-cli && npm install && npm run build && npm linkBoth whoop and whoop-cli work as commands. Requires Node.js 22+.
whoop auth loginFirst time? The CLI walks you through it:
WHOOP CLI — First-time setup
────────────────────────────
1. Go to https://developer.whoop.com
2. Create an application (apps with <10 users need no review)
3. Set the Redirect URI to: http://localhost:8787/callback
4. Copy your Client ID and Client Secret below
Everything stays local in ~/.whoop-cli/config.json
Client ID: ________
Client Secret: ********
✓ Credentials saved
Then it opens your browser for OAuth. Authorize, paste the callback URL, done. Tokens auto-refresh after that — you won't need to log in again.
whoop check # Today's health snapshot
whoop summary --color # Color-coded with status indicators
whoop insights # Personalized recommendationsIn a terminal, check shows a human-readable summary:
📅 2026-03-02
🟢 Recovery: 75% | HRV: 106ms | RHR: 37bpm
🟢 Sleep: 76% | 7.5h | Efficiency: 92%
🟡 Strain: 6.9 (optimal: ~14) | 1649 cal
🏋️ Workouts: 1 | Strength Training
Piped or in a script, it outputs flat JSON automatically.
whoop recovery # Today's recovery
whoop sleep # Today's sleep
whoop workout # Today's workouts
whoop cycle # Today's cycle
whoop profile # User profile
whoop body # Body measurementswhoop workout -d 2026-01-15 # Specific date
whoop workout -s 2026-01-01 -e 2026-03-01 # Date range
whoop workout -s 2026-01-01 -e 2026-03-01 -a # All pageswhoop trends # 7-day trends
whoop trends --days 30 # Any period (1-90 days)
whoop insights # Health recommendationswhoop multi --sleep --recovery --body
whoop multi --sleep --workout -s 2026-01-01 -e 2026-03-01 -awhoop auth login # OAuth flow (opens browser)
whoop auth status # Check auth state
whoop auth refresh # Force token refresh
whoop auth keepalive # Install cron to auto-refresh tokens
whoop auth keepalive --status # Check if keepalive is active
whoop auth keepalive --disable # Remove keepalive cron
whoop auth logout # Clear tokensTTY-aware — the CLI detects how you're using it:
| Context | Output |
|---|---|
| Terminal (human) | Pretty text, color-coded |
| Piped / scripted (agent) | Structured JSON to stdout |
Force a specific format:
whoop recovery --format json # Force JSON
whoop recovery --format pretty # Force pretty
whoop recovery --pretty # Shorthand| Flag | Description |
|---|---|
-d, --date <date> |
Date (YYYY-MM-DD) |
-s, --start <date> |
Start date for range |
-e, --end <date> |
End date for range |
-l, --limit <n> |
Results per page (default: 25) |
-a, --all |
Fetch all pages |
-f, --format <fmt> |
json, pretty, or auto (default: auto) |
-p, --pretty |
Shorthand for --format pretty |
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Auth error (not logged in, bad credentials) |
| 3 | Rate limit exceeded |
| 4 | Network error |
Agents get JSON automatically when output is piped. Recommended starting point:
whoop check # → {"ok":true,"recovery_score":75,"hrv_rmssd_milli":106,...}git clone https://github.com/TomasWard1/whoop-cli.git ~/tools/whoop-cli
cd ~/tools/whoop-cli && npm install && npm run build && npm linkOn machines without a browser, pre-write the config and complete OAuth manually:
# 1. Write credentials (skip interactive prompt)
mkdir -p ~/.whoop-cli && chmod 700 ~/.whoop-cli
cat > ~/.whoop-cli/config.json << 'EOF'
{
"client_id": "<your_client_id>",
"client_secret": "<your_client_secret>",
"redirect_uri": "http://localhost:8787/callback"
}
EOF
chmod 600 ~/.whoop-cli/config.json
# 2. Log in — shows a URL, open it on any machine, paste callback URL back
whoop auth loginA human must complete whoop auth login once (OAuth requires browser authorization). After that, enable keepalive to ensure tokens stay fresh:
whoop auth keepalive # Installs cron job (refreshes every 45 min)WHOOP access tokens expire every hour and use refresh token rotation — each refresh invalidates the previous token. Without regular refresh, both tokens expire and require re-login. The keepalive cron prevents this automatically.
- Config file (
~/.whoop-cli/config.json) — written by interactive setup or manually - Environment variables (
WHOOP_CLIENT_ID,WHOOP_CLIENT_SECRET) — override config file
~/.whoop-cli/
├── config.json # Client credentials (600 perms)
└── tokens.json # OAuth tokens (600 perms, auto-refresh)
git clone https://github.com/TomasWard1/whoop-cli.git
cd whoop-cli
npm install
npm test # 65 tests
npm run dev # Run with tsx
npm run build # Compile TypeScriptMIT