{
  "markdown": "# whoop-cli\n\nYour WHOOP data, from the terminal. Built for humans and agents.\n\n> Based on [whoopskill](https://github.com/koala73/whoopskill) by [@koala73](https://github.com/koala73).\n\n## Install\n\n```bash\nnpm install -g @tomasward/whoop-cli\n```\n\nBoth `whoop` and `whoop-cli` work as commands. Requires Node.js 22+.\n\n## Setup\n\n```bash\nwhoop auth login\n```\n\nFirst time? The CLI walks you through it:\n\n```\nWHOOP CLI — First-time setup\n────────────────────────────\n\n1. Go to https://developer.whoop.com\n2. Create an application (apps with <10 users need no review)\n3. Set the Redirect URI to: http://localhost:8787/callback\n4. Copy your Client ID and Client Secret below\n\nEverything stays local in ~/.whoop-cli/config.json\n\nClient ID: ________\nClient Secret: ********\n\n✓ Credentials saved\n```\n\nThen 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.\n\n## Usage\n\n### Quick check\n\n```bash\nwhoop check              # Today's health snapshot (auth + recovery + sleep + strain)\nwhoop check -d 2026-01-15    # Specific date\nwhoop summary            # One-liner: recovery score, HRV, sleep, strain\nwhoop summary --color    # Color-coded output with status indicators\nwhoop summary -d 2026-01-15  # Summary for a specific date\nwhoop insights           # AI-style health recommendations (uses last 7 days)\nwhoop awake              # Is user awake? (exit 0 = awake, 1 = likely sleeping)\nwhoop awake -d 2026-01-15    # Check awake state for a specific date\n```\n\n`check` combines an auth verification with today's key metrics in a single call. `summary` is the same snapshot without the auth check. `awake` checks if today's recovery `score_state` is `SCORED` — useful for gating agent heartbeats on sleep completion.\n\nIn a terminal, `check` shows a human-readable summary:\n\n```\n📅 2026-03-02\n🟢 Recovery: 75% | HRV: 106ms | RHR: 37bpm\n🟢 Sleep: 76% | 7.5h | Efficiency: 92%\n🟡 Strain: 6.9 (optimal: ~14) | 1649 cal\n🏋️ Workouts: 1 | Strength Training\n```\n\nPiped or in a script, it outputs flat JSON automatically.\n\n### Data commands\n\n```bash\nwhoop recovery           # Today's recovery\nwhoop sleep              # Today's sleep\nwhoop workout            # Today's workouts\nwhoop cycle              # Today's cycle\nwhoop profile            # User profile\nwhoop body               # Body measurements\n```\n\n### Date ranges\n\n```bash\nwhoop workout -d 2026-01-15                       # Specific date\nwhoop workout -s 2026-01-01 -e 2026-03-01         # Date range\nwhoop workout -s 2026-01-01 -e 2026-03-01 -a      # All pages\n```\n\n### Trends & insights\n\n```bash\nwhoop trends                # 7-day trends (recovery, sleep, strain averages)\nwhoop trends --days 30      # Any period (1-90 days)\nwhoop trends --json         # Output as JSON\nwhoop insights              # Health recommendations based on last 7 days\nwhoop insights -d 2026-01-15   # Recommendations as of a specific date\nwhoop insights --json       # Output as JSON\n```\n\n### Multi-type fetch\n\nFetch any combination of data types in a single call:\n\n```bash\nwhoop multi --sleep --recovery --body\nwhoop multi --sleep --workout -s 2026-01-01 -e 2026-03-01 -a\nwhoop multi --cycle --profile -d 2026-01-15\n```\n\nAvailable data type flags: `--sleep`, `--recovery`, `--workout`, `--cycle`, `--profile`, `--body`. At least one must be specified.\n\n### Auth\n\n```bash\nwhoop auth login             # OAuth flow (opens browser)\nwhoop auth status            # Check auth state\nwhoop auth refresh           # Force token refresh\nwhoop auth keepalive         # Install cron to auto-refresh tokens\nwhoop auth keepalive --status   # Check if keepalive is active\nwhoop auth keepalive --disable  # Remove keepalive cron\nwhoop auth logout            # Clear tokens\n```\n\n## Output\n\n**TTY-aware** — the CLI detects how you're using it:\n\n| Context | Output |\n|---------|--------|\n| Terminal (human) | Pretty text, color-coded |\n| Piped / scripted (agent) | Structured JSON to stdout |\n\nForce a specific format:\n\n```bash\nwhoop recovery --format json      # Force JSON\nwhoop recovery --format pretty    # Force pretty\nwhoop recovery --pretty           # Shorthand\n```\n\n## Options\n\n| Flag | Description |\n|------|-------------|\n| `-d, --date <date>` | Date (YYYY-MM-DD) |\n| `-s, --start <date>` | Start date for range |\n| `-e, --end <date>` | End date for range |\n| `-l, --limit <n>` | Results per page (default: 25) |\n| `-a, --all` | Fetch all pages |\n| `-f, --format <fmt>` | `json`, `pretty`, or `auto` (default: auto) |\n| `-p, --pretty` | Shorthand for `--format pretty` |\n| `--json` | Shorthand for `--format json` (trends, insights) |\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success / awake (for `whoop awake`) |\n| 1 | General error / not awake (for `whoop awake`) |\n| 2 | Auth error (not logged in, bad credentials) |\n| 3 | Rate limit exceeded |\n| 4 | Network error |\n\n## For Agents\n\n### Install as an agent skill\n\nTeach your AI coding agent (Claude Code, Cursor, Copilot, Codex, etc.) how to use WHOOP data:\n\n```bash\nnpx skills add TomasWard1/whoop-cli\n```\n\nThis installs the skill globally — your agent will automatically use `whoop` commands when you ask about health metrics, recovery, sleep, or strain.\n\n> Requires the CLI to be installed separately: `npm install -g @tomasward/whoop-cli`\n\n### JSON output\n\nAgents get JSON automatically when output is piped. Recommended starting point:\n\n```bash\nwhoop check    # → {\"ok\":true,\"recovery_score\":75,\"hrv_rmssd_milli\":106,...}\n```\n\n### Awake detection (heartbeat gating)\n\nBefore running heartbeats or reporting sleep-dependent metrics, check if the user is awake:\n\n```bash\nwhoop awake    # exit 0 = awake (recovery scored), exit 1 = likely sleeping\n```\n\n`whoop awake` checks if today's recovery `score_state` is `SCORED`. Whoop calculates recovery after sleep finishes, so an unscored recovery means the user is likely still asleep. Use this to gate heartbeat workflows and avoid reporting invalid metrics.\n\n```bash\n# Agent heartbeat pattern\nwhoop awake && whoop check    # Only report if awake\n```\n\n### Agent self-install\n\n```bash\nnpm install -g @tomasward/whoop-cli\n```\n\n### Headless setup (servers / CI)\n\nOn machines without a browser, pre-write the config and complete OAuth manually:\n\n```bash\n# 1. Write credentials (skip interactive prompt)\nmkdir -p ~/.whoop-cli && chmod 700 ~/.whoop-cli\ncat > ~/.whoop-cli/config.json << 'EOF'\n{\n  \"client_id\": \"<your_client_id>\",\n  \"client_secret\": \"<your_client_secret>\",\n  \"redirect_uri\": \"http://localhost:8787/callback\"\n}\nEOF\nchmod 600 ~/.whoop-cli/config.json\n\n# 2. Log in — shows a URL, open it on any machine, paste callback URL back\nwhoop auth login\n```\n\nA human must complete `whoop auth login` once (OAuth requires browser authorization). After that, enable keepalive to ensure tokens stay fresh:\n\n```bash\nwhoop auth keepalive     # Installs cron job (refreshes every 45 min)\n```\n\nWHOOP access tokens expire every hour and use [refresh token rotation](https://developer.whoop.com/docs/developing/oauth/) — each refresh invalidates the previous token. Without regular refresh, both tokens expire and require re-login. The keepalive cron prevents this automatically.\n\n### Credential resolution\n\n1. Config file (`~/.whoop-cli/config.json`) — written by interactive setup or manually\n2. Environment variables (`WHOOP_CLIENT_ID`, `WHOOP_CLIENT_SECRET`) — override config file\n\n## Storage\n\n```\n~/.whoop-cli/\n├── config.json    # Client credentials (600 perms)\n└── tokens.json    # OAuth tokens (600 perms, auto-refresh)\n```\n\n## Development\n\n```bash\ngit clone https://github.com/TomasWard1/whoop-cli.git\ncd whoop-cli\nnpm install\nnpm test           # 78 tests\nnpm run dev        # Run with tsx\nnpm run build      # Compile TypeScript\n```\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=TomasWard1/whoop-cli&type=Date)](https://star-history.com/#TomasWard1/whoop-cli&Date)\n\n## License\n\nMIT\n\n## Disclaimer\n\nThis project is not affiliated with, endorsed by, or sponsored by WHOOP, Inc. WHOOP is a registered trademark of WHOOP, Inc. Use of the WHOOP API is subject to WHOOP's [developer terms](https://developer.whoop.com).\n",
  "bytes": 8172,
  "sha": "772ecaec440ab1ae303091370fe469d9f0285b86f11d5891269f968a59824d22",
  "repo_slug": "tomasward1/whoop-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://api.agentalog.com/api/listings/skl_tomasward1_whoop_cli_whoop_cli_1dc3114d/readme"
}