Withings CLI

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:

• withings-sync — Python (670 stars)
• python_withings_api — Python (110 stars)
• withings-mcp — TypeScript (26 stars)
• aiowithings — Python (7 stars)
• withings-go — Go (6 stars)

Generated by CLI Printing Press