Printed by @gregvanhorn (Greg Van Horn).
Quick Start
1. Install
See Install above.
2. Set Up Credentials
Whoop uses OAuth 2.0 — there is no static API key. You first create an OAuth
app at developer.whoop.com, then exchange a
browser-based authorization code for a Bearer token. The CLI automates the
browser flow.
One-time: register a redirect URI in the Whoop dashboard
The CLI's auth login command starts a tiny local web server that catches the
OAuth callback. By default it listens on http://localhost:8085/callback,
and Whoop will reject the flow unless that exact URI is pre-registered on your
OAuth app.
- Go to developer.whoop.com → your OAuth app.
- Under Redirect URIs, add:
http://localhost:8085/callback
- Save.
If you'd rather use a different port, register http://localhost:<port>/callback
in the dashboard and pass --port <port> on auth login.
Run the login flow
whoop-pp-cli auth login \
--client-id <your-client-id> \
--client-secret <your-client-secret>
The CLI will open your browser, you approve the requested scopes, Whoop
redirects back to localhost:8085/callback, and the access + refresh tokens
are stored in the local config. From then on, every command authenticates
automatically.
If you already have a Bearer token, you can also set it directly:
export WHOOP_OAUTH="your-token-here"
Troubleshooting: redirect_uri does not match
If you see "The OAuth2 request resulted in an error… The 'redirect_uri'
parameter does not match any of the OAuth 2.0 Client's pre-registered
redirect urls", the URI you used at login is not registered on the Whoop
dashboard. Either:
- Register
http://localhost:8085/callback in the Whoop OAuth app, or
- Pick a port that's already registered, e.g.
auth login --port 9000 if
http://localhost:9000/callback is what you registered.
3. Verify Setup
whoop-pp-cli doctor
This checks your configuration and credentials.
4. Try Your First Command
whoop-pp-cli activity-mapping mock-value
Usage
Run whoop-pp-cli --help for the full command reference and flag list.
Commands
activity
Manage activity
whoop-pp-cli activity get-sleep-by-id - Get the sleep for the specified IDwhoop-pp-cli activity get-sleep-collection - Get all sleeps for a user, paginated. Results are sorted by start time in descending order.whoop-pp-cli activity get-workout-by-id - Get the workout for the specified IDwhoop-pp-cli activity get-workout-collection - Get all workouts for a user, paginated. Results are sorted by start time in descending order.
activity-mapping
Manage activity mapping
whoop-pp-cli activity-mapping get - Lookup the V2 UUID for a given V1 activity ID
cycle
Manage cycle
whoop-pp-cli cycle get-by-id - Get the cycle for the specified IDwhoop-pp-cli cycle get-collection - Get all physiological cycles for a user, paginated. Results are sorted by start time in descending order.
partner
Endpoints for trusted WHOOP partner operations
whoop-pp-cli partner add-test-data - Generates test user and lab requisition data for partner integration testing. This endpoint is only available in non-production environmentswhoop-pp-cli partner get-lab-requisition-by-id - Retrieves a lab requisition with its associated service requests by its unique identifier. The requesting partner must be an owner of the lab requisition.whoop-pp-cli partner get-service-request-by-id - Retrieves a service request by its unique identifier. The requesting partner must be an owner of the service request.whoop-pp-cli partner request-token - Exchanges partner client credentials for an access token.whoop-pp-cli partner update-service-request-status - Updates the business status of a service request task. The requesting partner must be an owner of the service request.whoop-pp-cli partner upload-diagnostic-report-results - Creates a diagnostic report with results for a service request. The requesting partner must be an owner of the service request.
recovery
Manage recovery
whoop-pp-cli recovery get-collection - Get all recoveries for a user, paginated. Results are sorted by start time of the related sleep in descending order.
user
Endpoints for retrieving user profile and measurement data.
whoop-pp-cli user get-body-measurement - Retrieves the body measurements (height, weight, max heart rate) for the authenticated user.whoop-pp-cli user get-profile-basic - Retrieves the basic profile information (name, email) for the authenticated user.whoop-pp-cli user revoke-oauth-access - Revoke the access token granted by the user. If the associated OAuth client is configured to receive webhooks, it will no longer receive them for this user.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
whoop-pp-cli activity-mapping mock-value
# JSON for scripting and agents
whoop-pp-cli activity-mapping mock-value --json
# Filter to specific fields
whoop-pp-cli activity-mapping mock-value --json --select id,name,status
# Dry run — show the request without sending
whoop-pp-cli activity-mapping mock-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
whoop-pp-cli activity-mapping mock-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
whoop-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/whoop-pp-cli/config.toml
Environment variables:
| Name | Kind | Required | Description |
|---|
WHOOP_OAUTH | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
whoop-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $WHOOP_OAUTH
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
Generated by CLI Printing Press