Every Withings metric in one offline-first, agent-native CLI — with a local SQLite mirror and recomposition, recovery, sleep-debt and clinician-report analytics no Withings tool has.
Pulls your weight/body-composition, activity, sleep, heart/ECG and workouts from the official Withings API into a local SQLite store you can search, query with SQL, and export as JSON or CSV. On top of that it adds local-join analytics — recomp, recovery, bp-report, sleep debt, digest, correlate — that no single API call can produce.
Authentication
Withings uses OAuth2. Register a free app at the Withings developer portal, run withings-pp-cli auth login once to authorize in your browser, and the CLI stores and auto-rotates your refresh token (Withings refresh tokens are single-use, so the CLI persists each new one for you).
Quick Start
# Check config and reachability before anything else (works without auth).
withings-pp-cli doctor --dry-run
# Mirror the last 90 days into local SQLite.
withings-pp-cli sync --resources measure,activity,sleep --since 90d
# See your real fat-vs-lean recomposition trend.
withings-pp-cli recomp --since 90d
# Structured 'what changed' snapshot for an agent.
withings-pp-cli digest --since 24h --json
Unique Features
These capabilities aren't available in any other tool for this API.
Local-join analytics
-
recomp — See whether you're actually recomposing — fat mass down while lean mass holds — on a de-noised rolling-average weight, not scale-weight whiplash.
Reach for this instead of raw measures when the question is 'is my cut/bulk working', not 'what did I weigh on Tuesday'.
withings-pp-cli recomp --since 90d --agent
-
recovery — Weigh recent workout HR-zone load against your recovery markers (resting HR, HRV, sleep score) to catch overtraining before it catches you.
Use when deciding whether to push or back off; it correlates how hard you trained with how recovered you are.
withings-pp-cli recovery --since 14d --agent
-
sleep debt — Cumulative sleep deficit against your target over a rolling window — the number the per-night summary never adds up for you.
Use for sleep-deficit accounting over time; for one night use 'sleep summary'.
withings-pp-cli sleep debt --window 14d --agent
-
correlate — Pearson + best-lag correlation between any two daily metrics (weight vs sleep score, steps vs resting HR).
The flexible fallback when no curated readout fits the metric pair you care about.
withings-pp-cli correlate weight sleep_score --since 90d --agent
Clinician + agent reports
-
bp-report — A dated blood-pressure + AFib table with your own annotations (medication changes, symptoms) — the clean history to hand a cardiologist.
Use for a doctor-ready BP/AFib history; prefer it over raw 'heart list' when you need the annotated report.
withings-pp-cli bp-report --since 90d --agent
-
digest — One structured 'what changed since across all my metrics' snapshot — built for piping into an agent.
The go-to for LLM health Q&A: one cursor-driven structured pull instead of N endpoint calls.
withings-pp-cli digest --since 24h --agent
Recipes
Mirror everything, then ask offline
withings-pp-cli sync --resources measure,activity,sleep,workouts,heart --since 180d
One incremental sync populates the local store for fast offline analytics.
Agent-native health digest
withings-pp-cli digest --since 24h --agent --select weight,sleep_score,resting_hr,new_afib
Narrowed structured output an agent can consume without parsing the full envelope.
Doctor-ready BP/AFib history
withings-pp-cli bp-report --since 90d --note 2026-06-03=started-amlodipine --csv
A dated BP + AFib table with your medication-change annotation, exported as CSV.
Is my cut working?
withings-pp-cli recomp --since 90d
De-noised weight trend plus fat-down/muscle-held verdict over the window.
Usage
Run withings-pp-cli --help for the full command reference and flag list.
Commands
activity
Daily and intraday activity: steps, distance, calories, heart-rate zones
withings-pp-cli activity get - Daily activity aggregates (getactivity).withings-pp-cli activity intraday - High-resolution intraday activity series (getintradayactivity).
devices
Linked Withings devices
withings-pp-cli devices - List linked devices (getdevice): model, battery, last sync.
goals
User goals: steps, sleep, weight
withings-pp-cli goals - Get user goals (getgoals).
heart
ECG/AFib recordings and blood-pressure readings
withings-pp-cli heart ecg - Get a single raw ECG signal by signalid (get).withings-pp-cli heart list - List heart recordings (list): ECG signalids, AFib classification, BP.
measure
Body measurements: weight, body composition, blood pressure, SpO2, temperature, ECG intervals
withings-pp-cli measure - Get body measurements (getmeas). Filter by type codes and date range.
notify
Webhook subscriptions (Notify)
withings-pp-cli notify get - Get one subscription (get).withings-pp-cli notify list - List webhook subscriptions (list).withings-pp-cli notify revoke - Revoke a webhook subscription (revoke).withings-pp-cli notify subscribe - Subscribe a webhook (subscribe).
sleep
Sleep stage series and per-night summaries
withings-pp-cli sleep series - High-frequency sleep stage series (get).withings-pp-cli sleep summary - Per-night sleep summary (getsummary): durations, HR, RR, snoring, AHI, sleep score.
workouts
Workout sessions with HR zones, distance, calories
withings-pp-cli workouts - List workout sessions (getworkouts).
Output Formats
# Human-readable table (default in terminal, JSON when piped)
withings-pp-cli activity get
# JSON for scripting and agents
withings-pp-cli activity get --json
# Filter to specific fields
withings-pp-cli activity get --json --select id,name,status
# Dry run — show the request without sending
withings-pp-cli activity get --dry-run
# Agent mode — JSON + compact + no prompts in one flag
withings-pp-cli activity get --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 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
withings-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/withings-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
WITHINGS_ACCESS_TOKEN | per_call | Yes | Set to your API credential. |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, withings-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
withings-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $WITHINGS_ACCESS_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- 401 / token expired — Run
withings-pp-cli auth refresh (or auth login to re-authorize); access tokens last 3h and the CLI rotates the single-use refresh token automatically.
- status 601 in responses — Rate limit (120 req/min). Slow down or rely on local sync + offline queries instead of repeated live calls.
- empty results after sync — Confirm the resource was synced:
withings-pp-cli sync --resources measure then withings-pp-cli measure get --limit 5.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press