WHOOP CLI for Agents

whoop-cli

Use the installed whoop command.

Security + Credential Handling

• Never ask users to paste long-lived client secrets or tokens into chat.
• For first-time auth, have the user run login locally in their own shell.
• macOS default secret storage is macOS Keychain.
• Linux/OpenClaw preferred secret storage is 1Password CLI with a service account.
• Linux/OpenClaw simple fallback is explicit local-vps storage with --accept-local-vps-risk.
• Profile JSON at ~/.whoop-cli/profiles/.json stores non-secret metadata only.
• Keychain access uses macOS Security APIs through /usr/bin/swift; do not replace this with command-line secret arguments.
• If /usr/bin/swift is unavailable, tell the user to install Apple Command Line Tools with xcode-select --install.
• If a sandboxed agent shell cannot access macOS Keychain, rerun the whoop command with normal user permissions; do not use secret-bearing command-line arguments as a fallback.
• After login, regular read commands should not need passwords or Touch ID.
• If macOS asks for "password data for new item" during login, stop and update or reinstall whoop; the CLI should write Keychain items non-interactively.
• On Linux, do not silently fall back to plaintext profile JSON. Use onepassword or explicit local-vps.
• Do not send long-lived 1Password service-account tokens through Telegram. In simple local-vps setup, the expected Telegram handoff is the short-lived WHOOP auth URL and redirected callback URL.
• Prefer read-only operational commands in agent flows: summary, day-brief, health, trend, and sync pull.
• Do not run whoop auth login unless the user explicitly asks for login help.

Install / Bootstrap

If whoop is missing:

npm install -g @andreasnlarsen/whoop-cli@0.5.2

Install this bundled skill for local Codex/agent use:

whoop skill install --target agents --force

That writes ~/.agents/skills/whoop-cli/SKILL.md and links it into ~/.codex/skills/whoop-cli.

Install for OpenClaw when needed:

whoop skill install --target openclaw --force

Install to another skill directory:

whoop skill install --target path --skill-dir /path/to/skills/whoop-cli --force

Core Checks

1. whoop auth status --json
2. If unauthenticated, ask the user to run local login:
   • macOS: whoop auth login
   • Linux/OpenClaw recommended: whoop auth login --secret-storage onepassword --op-vault ... --op-item ...
   • Telegram-only/simple Linux VPS: whoop auth login --secret-storage local-vps --accept-local-vps-risk
   • Prefer the interactive hidden client-secret prompt when a human is present.
   • Use one-time env/secret-manager injection only when automation requires it.
3. Validate:
   • whoop summary --json --pretty
   • whoop day-brief --json --pretty

Useful Commands

• Daily:
  • whoop summary --json --pretty
  • whoop day-brief --json --pretty
  • whoop strain-plan --json --pretty
  • whoop health flags --days 7 --json --pretty
• Activity analysis:
  • whoop activity list --days 30 --json --pretty
  • whoop activity trend --days 30 --json --pretty
  • whoop activity types --days 30 --json --pretty
  • training-only: whoop activity trend --days 30 --labeled-only --json --pretty
• Export:
  • whoop sync pull --start YYYY-MM-DD --end YYYY-MM-DD --out ./whoop.jsonl --json --pretty

Activity Interpretation Guardrail

• WHOOP generic activity rows, often sport_id=-1, are auto-detected and may be unlabeled movement such as housework or incidental activity, not intentional training.
• Do not treat generic activity as confirmed training volume by default.
• For coaching or training recommendations, default to --labeled-only and report total versus filtered counts.

Agent Filtering Pattern

• Canonical source: whoop activity list --json
• Prefer built-in filters first: --labeled-only, --generic-only, --sport-id, --sport-name.
• If custom slicing is needed and jq is available, filter shell-side from raw JSON:

whoop activity list --days 30 --json | jq '.data.records | map(select(.sport_id != -1))'

Experiment Protocol

• Canonical state: ~/.whoop-cli/experiments.json only.
• Plan experiments with context at creation time:
  • whoop experiment plan --name ... --behavior ... --start-date YYYY-MM-DD [--end-date YYYY-MM-DD] --description ... --why ... --hypothesis ... --success-criteria ... --protocol ... --json --pretty
• Update context without creating duplicate state:
  • whoop experiment context --id ... [--description ... --why ... --hypothesis ... --success-criteria ... --protocol ...] --json --pretty
• Check lifecycle/status with:
  • whoop experiment status [--status planned|running|completed] [--id ...] --json --pretty
• Evaluate outcomes with:
  • whoop experiment report --id ... --json --pretty
• Profile scope is strict by default: active --profile only.
• Use --all-profiles only when cross-profile visibility is explicitly needed.
• Prefer output field sourceOfTruth; experimentsFile is kept as compatibility alias.
• Avoid duplicating experiment state into other files unless the user explicitly asks for separate notes.

Safety

• Never print client secrets or raw tokens.
• Treat local-vps as a deliberate lower-security mode: it prevents accidental repo/chat/log exposure but not VPS compromise.
• Keep API errors concise and actionable.
• Treat this integration as unofficial and not affiliated with WHOOP.