whoop-cli

whoop-cli

WHOOP 健康数据命令行工具。通过管道输出时，所有命令均输出 JSON；在交互模式下则输出格式化文本。

whoop 和 whoop-cli 均可用作命令。

安装

npm install -g @tomasward/whoop-cli

需要 Node.js 22+。

身份验证

用户必须完成一次 OAuth 授权（需要浏览器）。之后令牌会自动刷新。

whoop auth login      # Opens browser for OAuth
whoop auth status     # Check auth (exit code 2 = not authenticated)
whoop auth refresh    # Force token refresh
whoop auth logout     # Clear tokens
whoop auth keepalive  # Install cron for auto-refresh (every 45 min)

首次设置

首次登录时，CLI 会提示输入 WHOOP API 凭据：

1. 前往 https://developer.whoop.com
2. 创建应用（用户少于 10 人的应用无需审核）
3. 将重定向 URI 设置为 http://localhost:8787/callback
4. 按提示输入 Client ID 和 Client Secret

凭据存储在 ~/.whoop-cli/config.json 中。环境变量 WHOOP_CLIENT_ID 和 WHOOP_CLIENT_SECRET 会覆盖配置文件中的设置。

无头设置（服务器 / CI）

mkdir -p ~/.whoop-cli && chmod 700 ~/.whoop-cli
cat > ~/.whoop-cli/config.json << 'EOF'
{"client_id":"<id>","client_secret":"<secret>","redirect_uri":"http://localhost:8787/callback"}
EOF
chmod 600 ~/.whoop-cli/config.json
whoop auth login       # Shows URL — open on any machine, paste callback back
whoop auth keepalive   # Keep tokens fresh automatically

Agent 快速入门

# Single-call health snapshot (flat JSON)
whoop check
# → {"ok":true,"checked_at":"...","recovery_score":72,"hrv_rmssd_milli":45.2,"sleep_hours":7.1,"strain":8.3}

# Auth pre-flight
whoop auth status
echo $?  # 0 = ok, 2 = needs login

命令

check — 单次调用生成健康快照

whoop check                    # today's metrics
whoop check --date 2026-03-01  # specific date

返回：{ok, checked_at, date, recovery_score, hrv_rmssd_milli, resting_heart_rate, sleep_performance, sleep_hours, sleep_efficiency, strain, calories, workout_count}

summary — 单行状态

whoop summary                  # JSON when piped, text when interactive
whoop summary --color          # color-coded with status indicators
whoop summary --format json    # force JSON

数据命令 — sleep、recovery、workout、cycle、profile、body

whoop recovery                                          # today
whoop sleep --date 2026-03-01                           # specific date
whoop workout -s 2026-01-01 -e 2026-03-01 -a           # date range, all pages
whoop cycle --format json                               # force JSON

multi — 一次调用获取多种数据类型

whoop multi --sleep --recovery --workout                            # today
whoop multi --sleep --recovery -s 2026-01-01 -e 2026-03-01 -a      # date range

trends — 多日分析

whoop trends              # 7-day trends
whoop trends --days 30    # 30-day trends (1-90)
whoop trends --json       # force JSON

insights — 健康建议

whoop insights                            # today
whoop insights --date 2026-03-01 --json   # specific date, JSON

输出行为

• 通过管道传输（无 TTY）：将 JSON 输出到 stdout。错误以 {"error":"...","code":2} 的形式输出到 stdout。
• 交互模式（TTY）：输出人类可读的文本。错误以纯文本形式输出到 stderr。
• 所有数据命令均支持 --format json|pretty|auto（默认：auto）。
• --pretty 是 --format pretty 的简写。
• --json 是 trends/insights 的简写。

退出代码

代码	含义
0	成功
1	一般错误
2	身份验证错误（未登录、令牌过期）
3	请求过于频繁
4	网络错误

Agent 错误处理

• 退出代码 2：身份验证失败。告知用户手动运行 whoop auth login（需要浏览器）。
• 退出代码 3：请求过于频繁。等待后重试。
• 退出代码 4：网络问题。几秒后重试。
• 如果找不到 whoop，告知用户安装：npm install -g @tomasward/whoop-cli。

日期处理

• 默认：WHOOP 日（以当地时间凌晨 4 点为分界）。
• 使用 --date YYYY-MM-DD 指定日期。
• 在 data 和 multi 命令中使用 --start / --end 查询日期范围。
• 使用 --all / -a 分页获取所有结果。

不适用场景

• 此工具要求已安装并完成身份验证的 CLI。它无法直接查询 WHOOP API。
• 如果用户需要实时流式数据或 webhook 集成，此 CLI 不支持。

链接

• GitHub
• WHOOP 开发者门户