withings-export-cli

Export health data from Withings scales, watches, and trackers. A command-line tool to back up measurements, sleep summaries, activity, and workouts — all from your terminal, with fitdown-style markdown by default and JSON or CSV on demand.

Features

• Measurements — weight, body fat %, muscle mass, hydration, bone mass, blood pressure, heart rate, SpO₂, temperature, VO₂ max, ECG intervals
• Sleep summaries — per-night sleep stages, sleep score, HR, RR, snoring, apnea-hypopnea index
• Activity — daily steps, distance, elevation, calories, HR zones
• Workouts — runs, walks, bikes, swims, etc. with duration, HR, distance, and more
• Date filtering — relative (30d, 4w, 6m, 1y) or absolute (2026-01-01)
• Fitdown-style markdown by default, plus --format json and --format csv — pipe into your tool of choice
• Multi-platform — pre-built binaries for macOS (Intel + Apple Silicon), Linux, and Windows

Quick Start

# Install with Homebrew
brew tap quantcli/tap
brew install withings-export

# Create a Withings developer app at https://developer.withings.com/,
# set the callback URL to http://127.0.0.1, then:
export WITHINGS_CLIENT_ID=...
export WITHINGS_CLIENT_SECRET=...
export WITHINGS_CALLBACK_URL='https://redirectmeto.com/http://localhost:8128/oauth/authorize'

# Log in (opens your browser) and pull recent data
withings-export auth login
withings-export measurements --since 30d
withings-export sleep --since 7d

Install

Homebrew (macOS / Linux):

brew tap quantcli/tap
brew install withings-export

Or download a pre-built binary from the releases page:

macOS (Apple Silicon):

curl -Lo /tmp/withings-export.zip https://github.com/quantcli/withings-export-cli/releases/latest/download/withings-export_darwin_arm64.zip
unzip -jo /tmp/withings-export.zip -d ~/bin && rm /tmp/withings-export.zip
chmod +x ~/bin/withings-export

macOS (Intel):

curl -Lo /tmp/withings-export.zip https://github.com/quantcli/withings-export-cli/releases/latest/download/withings-export_darwin_amd64.zip
unzip -jo /tmp/withings-export.zip -d ~/bin && rm /tmp/withings-export.zip
chmod +x ~/bin/withings-export

Linux (amd64):

curl -Lo /tmp/withings-export.zip https://github.com/quantcli/withings-export-cli/releases/latest/download/withings-export_linux_amd64.zip
unzip -jo /tmp/withings-export.zip -d ~/bin && rm /tmp/withings-export.zip
chmod +x ~/bin/withings-export

Windows (amd64):

Download withings-export_windows_amd64.zip from the releases page, extract, and add the directory to your PATH.

Authentication

Withings uses OAuth2 — you need your own developer app.

1. Go to https://developer.withings.com/, sign in, and create a new public API app.

2. Withings requires an HTTPS callback URL, so use the redirectmeto.com bounce trick. Register this as your callback:

   https://redirectmeto.com/http://localhost:8128/oauth/authorize
   

   (redirectmeto.com takes any URL after its host and 302-redirects your browser there, so Withings' HTTPS requirement is satisfied while the auth code ends up on your local server.)

3. Copy the Client ID and Consumer Secret into env vars (or you'll be prompted):

export WITHINGS_CLIENT_ID=...
export WITHINGS_CLIENT_SECRET=...
export WITHINGS_CALLBACK_URL='https://redirectmeto.com/http://localhost:8128/oauth/authorize'
withings-export auth login

If WITHINGS_CALLBACK_URL is unset the CLI falls back to binding a random port on 127.0.0.1 — only works if your Withings app allows a plain http:// callback.

Tokens are stored at ~/.config/withings-export/auth.json (mode 0600). Access tokens are refreshed automatically when they expire.

withings-export auth login      # OAuth2 in your browser
withings-export auth status     # One-line readiness check, no network call
withings-export auth logout     # Remove stored tokens

Headless / CI

Where there's no browser to run auth login, supply the refresh token via the environment instead of the token file (quantcli contract §5):

export WITHINGS_CLIENT_ID=...
export WITHINGS_CLIENT_SECRET=...
export WITHINGS_REFRESH_TOKEN=...   # from a prior local `auth login` (see auth.json)
withings-export measurements --since 30d

The CLI mints an access token from the refresh token on demand. When WITHINGS_REFRESH_TOKEN is set it takes precedence over a saved auth.json — a container with a stale mounted config and a freshly injected secret uses the secret. auth status reports the env as the source and exits 0 without a network call, so exit 0 there means "a token was supplied", not "the token works".

Withings rotates refresh tokens on each refresh, so a static WITHINGS_REFRESH_TOKEN is single-use — a repeat job must capture the rotated token (written to ~/.config/withings-export/auth.json) and feed it back for the next run. If that file can't be written (read-only rootfs, no HOME) the export still succeeds and prints a warning to stderr, but the rotated token is lost — mount a writable path for it on any job that runs more than once.

Usage

Measurements (scales, BP monitors, ECG)

withings-export measurements                       # last 30 days, markdown
withings-export measurements --since 1y            # last year
withings-export measurements --since 2026-01-01
withings-export measurements --types 1,6,76        # only weight, body fat %, muscle mass
withings-export measurements --format json         # JSON for scripting
withings-export measurements --format csv          # CSV for spreadsheets

Common measure type codes: 1=weight (kg), 6=body fat %, 8=fat mass (kg), 9=diastolic BP, 10=systolic BP, 11=heart pulse, 54=SpO₂ %, 76=muscle mass, 77=hydration, 88=bone mass.

Sleep

withings-export sleep                  # last 30 nights, markdown
withings-export sleep --since 6m       # last 6 months
withings-export sleep --derive         # polyfill nights with no Withings summary
                                       # using intraday HR samples (Apple Watch via HealthKit)
withings-export sleep --format json

Includes total sleep time, stages (light/deep/REM), sleep score, heart rate, respiratory rate, snoring episodes, and apnea-hypopnea index (if supported by your device).

Activity

withings-export activity               # last 30 days, markdown
withings-export activity --since 1y
withings-export activity --format json

Daily steps, distance, elevation, calories, time in HR zones.

Workouts

withings-export workouts               # last 90 days, markdown
withings-export workouts --since 6m
withings-export workouts --format json

Per-workout category (run/walk/bike/etc.), duration, calories, HR, distance, elevation.

Intraday

withings-export intraday               # last 24h, minute-level samples
withings-export intraday --since 7d
withings-export intraday --format csv

Per-minute heart rate, HRV (rmssd, sdnn1), SpO₂, steps, and distance — typically populated by an Apple Watch via the HealthKit bridge or by a native Withings tracker.

Output Formats

Markdown (default): fitdown-style plain-text blocks with a date heading per record. Human-readable and easy to skim:

Workout 2026-04-23

lift_weights
08:58 → 10:12 (73 min)
482 cal
HR avg 76, 50-127

JSON (--format json): pretty-printed JSON array. Good for jq or custom scripts.

CSV (--format csv): header row + one row per data point. Suitable for spreadsheets, Grafana, pandas, etc.

Example — average weight over the last year:

withings-export measurements --since 1y --types 1 --format json \
  | jq '[.[] | .value] | add / length'

About Withings

Withings makes connected health hardware — smart scales (Body+, Body Scan), hybrid watches (ScanWatch), BP monitors, sleep trackers. All data is stored in Health Mate and exposed via the Withings Public API.

This CLI is unofficial and not affiliated with Withings.

License

MIT — see LICENSE.