Back to Details

whoo-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

whoo CLI

whoo CLI

whoo
is a CLI for the WHOOP API. Install globally with Bun:
bash
bun add -g whoo   # requires Bun 1.3+
whoo
是一款基于WHOOP API的CLI工具。可通过Bun全局安装：
bash
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:
bash
whoo login                                          # prompts for credentials, opens browser
whoo login --client-id <ID> --client-secret <SEC>  # non-interactive
For SSH or headless environments where 
http://127.0.0.1:8123
is not reachable, use 
--manual
. It prints the auth URL; complete login in any browser, then paste the full callback URL back:
bash
whoo login --manual
whoo login --manual --client-id <ID> --client-secret <SEC>
Tokens persist in the OS config directory and refresh automatically. Check auth state anytime:
bash
whoo status
  1. 前往 https://developer.whoop.com 创建开发者应用，并记录
    client_id
    和
    client_secret
    。
  2. 在应用设置中添加重定向URI：
    http://127.0.0.1:8123/callback
  3. 身份验证：
bash
whoo login                                          # 提示输入凭证，自动打开浏览器
whoo login --client-id <ID> --client-secret <SEC>  # 非交互式验证
对于无法访问
http://127.0.0.1:8123
的SSH或无头环境，请使用
--manual
参数。 该命令会打印授权URL；在任意浏览器中完成登录后，将完整的回调URL粘贴回终端：
bash
whoo login --manual
whoo login --manual --client-id <ID> --client-secret <SEC>
令牌会持久存储在系统配置目录中，并自动刷新。可随时检查身份验证状态：
bash
whoo status

Commands

命令列表

CommandReturnsFlags
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
  • --manual
    — manual login for SSH/headless; paste callback URL instead of browser auto-redirect
命令返回内容可选参数
whoo overview
包含恢复和睡眠数据的当前周期信息
--limit
, 
--json
whoo recovery
恢复分数
--limit
, 
--json
whoo sleep
睡眠会话记录
--limit
, 
--json
whoo user
用户资料及身体测量数据
--json
whoo status
身份验证状态（已登录/凭证是否存在）—
whoo logout
清除存储的凭证—
  • --limit <n>
    — 返回的记录数量（1–100，默认值为1）
  • --json
    — 返回原始JSON数据；适用于程序化访问场景
  • --manual
    — 适用于SSH/无头环境的手动登录模式；需粘贴回调URL而非自动浏览器重定向

Common Workflows

常见工作流

Latest recovery snapshot:
bash
whoo recovery --json
最新恢复数据快照：
bash
whoo recovery --json

key: recoveries[0].score.recovery_score (0–100 %)

关键字段: recoveries[0].score.recovery_score (0–100 %)


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

```bash
whoo overview --json

**当日完整数据（一次调用获取周期+恢复+睡眠数据）：**

```bash
whoo overview --json

keys: cycles[0].cycle.score.strain, cycles[0].recovery.score, cycles[0].sleep.score

关键字段: cycles[0].cycle.score.strain, cycles[0].recovery.score, cycles[0].sleep.score


**7-day sleep trend:**

```bash
whoo sleep --limit 7 --json

**7天睡眠趋势：**

```bash
whoo sleep --limit 7 --json

iterate: sleeps[].score.sleep_performance_percentage

遍历字段: sleeps[].score.sleep_performance_percentage


**30-day history:**

```bash
whoo overview --limit 30 --json
User profile and body stats:
bash
whoo user --json

**30天历史数据：**

```bash
whoo overview --limit 30 --json
用户资料及身体统计数据：
bash
whoo user --json

Error Handling

错误处理

Error messageFix
"Missing login credentials"
Run 
whoo login
Persistent 401 after auto-refreshRun 
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.
错误信息解决方法
"Missing login credentials"
执行
whoo login
命令
自动刷新后仍持续返回401错误重新执行
whoo login
进行身份验证
score_state: "PENDING_MANUAL"
WHOOP尚未完成数据评分 — 可跳过该数据或告知用户
score_state: "UNSCORABLE"
数据不足无法生成评分 — 按空值处理
在解读数值指标前，请务必检查
score_state === "SCORED"
是否成立。

References

参考资料

  • JSON output schemas (field names, types, units): read 
    references/schemas.md
  • Metric interpretation (healthy ranges, score zones, context): read 
    references/metrics.md
  • JSON输出 Schema（字段名称、类型、单位）：请查看
    references/schemas.md
  • 指标解读（健康范围、分数区间、相关背景）：请查看
    references/metrics.md