whoo CLI

whoo is a CLI for the WHOOP API. Install globally with Bun:

bun add -g whoo   # requires Bun 1.3+

Prerequisites (one-time setup, done once by the user)

1. Create a developer app at https://developer.whoop.com — note client_id and client_secret.
2. Add redirect URI in the app settings: http://127.0.0.1:8123/callback
3. Authenticate:

whoo login                                          # prompts for credentials, opens browser
whoo login --client-id <ID> --client-secret <SEC>  # non-interactive

Tokens persist in the OS config directory and refresh automatically. Check auth state anytime:

whoo status

Commands

Command	Returns	Flags
whoo overview	Active cycle with nested recovery and sleep	--limit, --json
whoo recovery	Recovery scores	--limit, --json
whoo sleep	Sleep sessions	--limit, --json
whoo user	Profile and body measurements	--json
whoo status	Auth state (logged in / credential presence)	—
whoo logout	Clear stored credentials	—

• --limit <n> — records to return (1–100, default 1)
• --json — raw JSON payload; use this for programmatic access

Common Workflows

Latest recovery snapshot:

whoo recovery --json
# key: recoveries[0].score.recovery_score  (0–100 %)

Full today (cycle + recovery + sleep in one call):

whoo overview --json
# keys: cycles[0].cycle.score.strain, cycles[0].recovery.score, cycles[0].sleep.score

7-day sleep trend:

whoo sleep --limit 7 --json
# iterate: sleeps[].score.sleep_performance_percentage

30-day history:

whoo overview --limit 30 --json

User profile and body stats:

whoo user --json

Error Handling

Error message	Fix
"Missing login credentials"	Run whoo login
Persistent 401 after auto-refresh	Run whoo login again to re-authenticate
score_state: "PENDING_MANUAL"	WHOOP hasn't scored yet — skip or surface to the user
score_state: "UNSCORABLE"	Insufficient data for scoring — treat as null

Always check score_state === "SCORED" before interpreting numeric metrics.

References

• JSON output schemas (field names, types, units): read references/schemas.md
• Metric interpretation (healthy ranges, score zones, context): read references/metrics.md