@andreasnlarsen/whoop-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,339 @@
+# whoop-cli
+
+Simple WHOOP command-line tool for humans and agents.
+
+It gives you:
+- easy OAuth login
+- daily readiness commands (`day-brief`, `summary`, `health flags`)
+- machine-safe JSON output (`{data,error}`)
+- export + webhook verification tools
+
+---
+
+## Important: auth model (for now)
+
+This project is currently **BYO WHOOP app credentials**.
+
+That means each user (or each installer/agent) must create a WHOOP Developer app and use its:
+- Client ID
+- Client Secret
+- Redirect URI
+
+There is **no managed/shared auth service** in this repo right now.
+
+## Important legal / brand notice
+
+- This project is **unofficial** and is **not affiliated with, endorsed by, or sponsored by Whoop, Inc.**
+- **WHOOP** is a trademark of Whoop, Inc., used here for compatibility/reference only.
+- This CLI is built to work with the WHOOP developer API, but you are responsible for complying with:
+  - WHOOP API Terms of Use
+  - WHOOP brand/design guidelines
+  - applicable privacy and data-protection laws
+- Do **not** embed or publish client secrets/tokens in source code, examples, or public logs.
+- If WHOOP requests naming/branding/compliance changes, maintainers should address them promptly and cooperatively.
+
+---
+
+## One-line options (no clone)
+
+If you want agents/users to run it immediately without cloning:
+
+### Current (works now via GitHub source)
+
+Run once (ephemeral):
+
+```bash
+npm exec --yes --package=github:andreasnlarsen/whoop-cli -- whoop summary --json --pretty
+```
+
+Install globally:
+
+```bash
+npm install -g github:andreasnlarsen/whoop-cli
+```
+
+### After npm publish (recommended)
+
+Run once (ephemeral):
+
+```bash
+npx -y @andreasnlarsen/whoop-cli summary --json --pretty
+```
+
+Install globally:
+
+```bash
+npm install -g @andreasnlarsen/whoop-cli
+```
+
+Then use:
+
+```bash
+whoop --help
+```
+
+### OpenClaw skill install (optional)
+
+After global install, copy bundled skill into OpenClaw workspace:
+
+```bash
+whoop openclaw install-skill --force
+```
+
+(Default target: `~/.openclaw/workspace/skills/whoop-cli/SKILL.md`)
+
+---
+
+## Quick start
+
+## 1) Install
+
+```bash
+npm install
+npm run build
+```
+
+Run help:
+
+```bash
+node dist/index.js --help
+```
+
+(If installed globally later, use `whoop ...` directly.)
+
+### Command name
+
+The executable is `whoop` (not `whoop-cli`).
+
+## 2) Create WHOOP app
+
+Open: https://developer-dashboard.whoop.com/
+
+Create an app and set these fields:
+
+- **App name:** anything (example: `whoop-cli`)
+- **Redirect URI:** use one value and keep it consistent
+  - recommended: `http://localhost:1234/callback`
+  - accepted alternative: `https://localhost:1234/callback`
+- **Scopes:** include at least
+  - `read:recovery`
+  - `read:cycles`
+  - `read:workout`
+  - `read:sleep`
+  - `read:profile`
+  - `read:body_measurement`
+  - `offline` (for refresh token)
+
+Then copy these 3 values from WHOOP dashboard:
+- client id
+- client secret
+- redirect URI
+
+## 3) Login
+
+```bash
+whoop auth login \
+  --client-id "<CLIENT_ID>" \
+  --client-secret "<CLIENT_SECRET>" \
+  --redirect-uri "<REDIRECT_URI>"
+```
+
+Then test:
+
+```bash
+whoop auth status --json --pretty
+whoop day-brief --json --pretty
+```
+
+---
+
+## Redirect URI: what to use
+
+This is the #1 setup confusion, so here is the practical rule:
+
+- The redirect URI in WHOOP Dashboard and CLI must **match exactly**.
+- `whoop-cli` currently uses a **manual paste flow** (it does not require a running callback server).
+
+### Recommended default
+
+Use:
+
+`http://localhost:1234/callback`
+
+Set this in WHOOP Dashboard, and pass the same value to `whoop auth login`.
+
+### If localhost is blocked by your policy
+
+Use any stable URI you control, for example:
+
+`https://your-domain.com/whoop/callback`
+
+Again, pass the exact same value in CLI.
+
+### What happens during login?
+
+After WHOOP consent, browser redirects to that URI with `?code=...&state=...`.
+Copy the **full redirected URL** from the browser address bar and paste it into the CLI prompt.
+
+(If localhost page fails to load, that is usually fine—just copy the URL.)
+
+---
+
+## For non-technical users
+
+If an agent/dev is installing for you, send them these 3 values only:
+1. Client ID
+2. Client Secret
+3. Redirect URI
+
+They run login once, then you can use ready commands like:
+
+```bash
+whoop summary --json --pretty
+whoop day-brief --json --pretty
+```
+
+---
+
+## For agents/installers (recommended setup flow)
+
+1. Verify auth:
+
+```bash
+whoop auth status --json
+```
+
+2. If not authenticated, run `whoop auth login ...`
+3. Validate with:
+
+```bash
+whoop profile show --json
+whoop day-brief --json
+```
+
+4. For unattended systems, schedule:
+
+```bash
+scripts/whoop-refresh-monitor.sh
+```
+
+---
+
+## Most useful commands
+
+### Daily coaching
+- `whoop summary`
+- `whoop day-brief`
+- `whoop strain-plan`
+- `whoop health flags`
+
+### Core data
+- `whoop profile show`
+- `whoop recovery latest|list`
+- `whoop sleep latest|list|trend`
+- `whoop cycle latest|list`
+- `whoop workout list|trend`
+
+### Ops
+- `whoop sync pull --start YYYY-MM-DD --end YYYY-MM-DD --out ./whoop.jsonl`
+- `whoop webhook verify --secret ... --timestamp ... --signature ... --body-file ...`
+- `whoop activity map-v1-id --id <legacyV1ActivityId>`
+- `whoop openclaw install-skill --force`
+
+### Behavior/experiments
+- `whoop behavior impacts --file ~/.whoop-cli/journal-observations.jsonl`
+- `whoop experiment start --name ... --behavior ...`
+- `whoop experiment list`
+- `whoop experiment report --id ...`
+
+---
+
+## JSON output contract
+
+With `--json`, every command returns:
+
+```json
+{ "data": {"...": "..."}, "error": null }
+```
+
+or
+
+```json
+{
+  "data": null,
+  "error": {
+    "code": "AUTH_ERROR",
+    "message": "...",
+    "details": {"...": "..."}
+  }
+}
+```
+
+Exit codes:
+- `0` success
+- `2` usage/config/feature-unavailable
+- `3` auth
+- `4` api/network
+- `1` unexpected internal
+
+---
+
+## Security
+
+- Tokens saved in `~/.whoop-cli/profiles/<name>.json` with strict file permissions
+- Refresh-token flow supported for automation
+- CLI avoids printing secrets by default
+
+---
+
+## Maintainer release (npm)
+
+### Option A: Trusted publisher (recommended)
+
+This repo includes: `.github/workflows/npm-publish.yml`.
+
+One-time setup on npmjs.com (**required**):
+
+1. Go to package settings for `@andreasnlarsen/whoop-cli`
+2. Add trusted publisher:
+   - Provider: GitHub Actions
+   - Organization/User: `andreasnlarsen`
+   - Repository: `whoop-cli`
+   - Workflow filename: `npm-publish.yml`
+   - Environment name: leave empty (or set if you enforce GitHub Environment)
+3. Optional hardening (recommended): package Settings → Publishing access →
+   - "Require two-factor authentication and disallow tokens"
+
+Release flow:
+
+```bash
+# bump version first (example)
+npm version patch
+
+git push origin main --follow-tags
+# OR manually tag: git tag v0.1.1 && git push origin v0.1.1
+```
+
+The GitHub workflow will publish automatically on `v*` tags via OIDC.
+
+### Bootstrap note (first publish)
+
+npm currently requires the package to exist before trusted publisher can be configured in package settings.
+If this is your very first publish for this package, do one manual publish first:
+
+```bash
+npm login
+./scripts/publish-npm.sh
+```
+
+Then enable trusted publisher and use tag-based releases going forward.
+
+## Sources
+
+- https://developer.whoop.com/api/
+- https://developer.whoop.com/docs/developing/oauth/
+- https://developer.whoop.com/docs/developing/webhooks/
+- https://developer.whoop.com/docs/developing/getting-started/
+- https://developer.whoop.com/api-terms-of-use/
+- https://developer.whoop.com/docs/developing/design-guidelines/
+- https://developer.whoop.com/docs/developing/app-approval/

package/dist/auth/oauth.js

@@ -0,0 +1,88 @@
+import { randomBytes } from 'node:crypto';
+import { authError, networkError, usageError } from '../http/errors.js';
+export const generateState = () => randomBytes(16).toString('hex').slice(0, 16);
+export const buildAuthUrl = (config, scopes, state) => {
+    const url = new URL('/oauth/oauth2/auth', config.baseUrl);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', config.clientId);
+    url.searchParams.set('redirect_uri', config.redirectUri);
+    url.searchParams.set('scope', scopes.join(' '));
+    url.searchParams.set('state', state);
+    return url.toString();
+};
+const tokenEndpoint = (baseUrl) => new URL('/oauth/oauth2/token', baseUrl).toString();
+const exchange = async (config, payload) => {
+    const body = new URLSearchParams(payload);
+    let res;
+    try {
+        res = await fetch(tokenEndpoint(config.baseUrl), {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/x-www-form-urlencoded',
+            },
+            body: body.toString(),
+        });
+    }
+    catch (err) {
+        throw networkError('Failed to reach WHOOP token endpoint', {
+            cause: err instanceof Error ? err.message : String(err),
+        });
+    }
+    const raw = await res.text();
+    let parsed = raw;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // keep raw
+    }
+    if (!res.ok) {
+        throw authError('WHOOP token exchange failed', {
+            status: res.status,
+            response: parsed,
+        });
+    }
+    const token = parsed;
+    if (!token.access_token || !token.expires_in || !token.token_type) {
+        throw authError('WHOOP token response missing required fields', { response: parsed });
+    }
+    return token;
+};
+export const exchangeAuthCode = async (config, code) => {
+    if (!code)
+        throw usageError('Authorization code is required');
+    return exchange(config, {
+        grant_type: 'authorization_code',
+        code,
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+        redirect_uri: config.redirectUri,
+    });
+};
+export const refreshAuthToken = async (config, refreshToken, scope) => {
+    if (!refreshToken)
+        throw usageError('Refresh token is required');
+    return exchange(config, {
+        grant_type: 'refresh_token',
+        refresh_token: refreshToken,
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+        ...(scope ? { scope } : {}),
+    });
+};
+export const parseAuthInput = (input) => {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        throw usageError('Empty authorization input');
+    }
+    if (trimmed.startsWith('http://') || trimmed.startsWith('https://')) {
+        const url = new URL(trimmed);
+        const code = url.searchParams.get('code');
+        const state = url.searchParams.get('state') ?? undefined;
+        if (!code) {
+            throw usageError('Redirect URL did not contain code parameter');
+        }
+        return { code, state };
+    }
+    return { code: trimmed };
+};

package/dist/auth/refresh-lock.js

@@ -0,0 +1,19 @@
+const locks = new Map();
+export const withRefreshLock = async (key, fn) => {
+    const current = locks.get(key);
+    if (current) {
+        await current;
+    }
+    let resolve;
+    const gate = new Promise((r) => {
+        resolve = r;
+    });
+    locks.set(key, gate);
+    try {
+        return await fn();
+    }
+    finally {
+        locks.delete(key);
+        resolve();
+    }
+};

package/dist/auth/token-service.js

@@ -0,0 +1,59 @@
+import { refreshAuthToken } from './oauth.js';
+import { withRefreshLock } from './refresh-lock.js';
+import { loadProfile, saveProfile } from '../store/profile-store.js';
+import { authError, configError } from '../http/errors.js';
+import { tokenRefreshSkewSeconds } from '../util/config.js';
+const nowEpochSeconds = () => Math.floor(Date.now() / 1000);
+const expiresAtToEpoch = (iso) => Math.floor(new Date(iso).getTime() / 1000);
+export const isTokenExpired = (token, skewSeconds = tokenRefreshSkewSeconds) => {
+    const exp = expiresAtToEpoch(token.expiresAt);
+    return exp - nowEpochSeconds() <= skewSeconds;
+};
+export const tokenFromOAuth = (payload, previousRefreshToken) => {
+    const expiresAt = new Date(Date.now() + payload.expires_in * 1000).toISOString();
+    return {
+        accessToken: payload.access_token,
+        refreshToken: payload.refresh_token ?? previousRefreshToken,
+        tokenType: payload.token_type,
+        scope: payload.scope,
+        expiresAt,
+    };
+};
+export const requireProfile = async (profileName) => {
+    const profile = await loadProfile(profileName);
+    if (!profile) {
+        throw configError(`Profile "${profileName}" was not found. Run whoop auth login first.`);
+    }
+    if (!profile.clientId || !profile.clientSecret || !profile.redirectUri) {
+        throw configError(`Profile "${profileName}" is missing OAuth client settings.`);
+    }
+    return profile;
+};
+const toOAuthConfig = (profile) => ({
+    clientId: profile.clientId,
+    clientSecret: profile.clientSecret,
+    redirectUri: profile.redirectUri,
+    baseUrl: profile.baseUrl,
+});
+export const refreshProfileToken = async (profileName) => withRefreshLock(profileName, async () => {
+    const profile = await requireProfile(profileName);
+    const refreshToken = profile.tokens?.refreshToken;
+    if (!refreshToken) {
+        throw authError('No refresh token available. Re-run whoop auth login with offline scope.');
+    }
+    const refreshed = await refreshAuthToken(toOAuthConfig(profile), refreshToken, profile.tokens?.scope);
+    profile.tokens = tokenFromOAuth(refreshed, refreshToken);
+    await saveProfile(profileName, profile);
+    return profile;
+});
+export const ensureFreshToken = async (profileName) => {
+    const profile = await requireProfile(profileName);
+    const token = profile.tokens;
+    if (!token?.accessToken) {
+        throw authError('No access token found. Run whoop auth login.');
+    }
+    if (!isTokenExpired(token)) {
+        return profile;
+    }
+    return refreshProfileToken(profileName);
+};

package/dist/cli.js

@@ -0,0 +1,37 @@
+import { Command } from 'commander';
+import { registerAuthCommands } from './commands/auth.js';
+import { registerProfileCommands } from './commands/profile.js';
+import { registerRecoveryCommands } from './commands/recovery.js';
+import { registerSleepCommands } from './commands/sleep.js';
+import { registerCycleCommands } from './commands/cycle.js';
+import { registerWorkoutCommands } from './commands/workout.js';
+import { registerSummaryCommands } from './commands/summary.js';
+import { registerHealthCommands } from './commands/health.js';
+import { registerSyncCommands } from './commands/sync.js';
+import { registerWebhookCommands } from './commands/webhook.js';
+import { registerBehaviorCommands } from './commands/behavior.js';
+import { registerExperimentCommands } from './commands/experiment.js';
+import { registerActivityCommands } from './commands/activity.js';
+import { registerOpenClawCommands } from './commands/openclaw.js';
+export const program = new Command()
+    .name('whoop')
+    .description('WHOOP CLI for human + agent workflows')
+    .option('--json', 'Output JSON envelope', false)
+    .option('--pretty', 'Pretty print JSON', false)
+    .option('--profile <name>', 'Profile name', 'default')
+    .option('--base-url <url>', 'WHOOP API base URL', 'https://api.prod.whoop.com')
+    .option('--timeout-ms <n>', 'HTTP timeout in ms', '10000');
+registerAuthCommands(program);
+registerProfileCommands(program);
+registerRecoveryCommands(program);
+registerSleepCommands(program);
+registerCycleCommands(program);
+registerWorkoutCommands(program);
+registerSummaryCommands(program);
+registerHealthCommands(program);
+registerSyncCommands(program);
+registerWebhookCommands(program);
+registerBehaviorCommands(program);
+registerExperimentCommands(program);
+registerActivityCommands(program);
+registerOpenClawCommands(program);

package/dist/commands/activity.js

@@ -0,0 +1,44 @@
+import { WhoopApiClient } from '../http/client.js';
+import { getGlobalOptions, printData, printError } from './context.js';
+import { WhoopCliError, usageError } from '../http/errors.js';
+export const registerActivityCommands = (program) => {
+    const activity = program.command('activity').description('Activity migration and lookup helpers');
+    activity
+        .command('map-v1-id')
+        .description('Lookup v2 activity UUID from legacy v1 activity ID')
+        .requiredOption('--id <activityV1Id>', 'legacy v1 activity id')
+        .action(async function mapV1IdAction(opts) {
+        const globals = getGlobalOptions(this);
+        const id = Number(opts.id);
+        try {
+            if (Number.isNaN(id) || id <= 0) {
+                throw usageError('id must be a positive integer', { value: opts.id });
+            }
+            const client = new WhoopApiClient(globals.profile);
+            const data = await client.requestJson({
+                path: `/developer/v1/activity-mapping/${id}`,
+                timeoutMs: globals.timeoutMs,
+            });
+            printData(this, {
+                activityV1Id: id,
+                activityV2Id: data.v2_activity_id ?? null,
+                found: Boolean(data.v2_activity_id),
+            });
+        }
+        catch (err) {
+            if (err instanceof WhoopCliError &&
+                err.code === 'HTTP_ERROR' &&
+                typeof err.details === 'object' &&
+                err.details !== null &&
+                err.details.status === 404) {
+                printData(this, {
+                    activityV1Id: id,
+                    activityV2Id: null,
+                    found: false,
+                });
+                return;
+            }
+            printError(this, err);
+        }
+    });
+};