Garmin Connect

Garmin Connect

Query your Garmin Connect account from the CLI. Zero npm dependencies, single-file Bun script. Auth uses the mobile JSON login API (the flow Garmin actually supports for third-party clients as of March 2026) and caches tokens locally — MFA is re-prompted only when the ~1-year OAuth1 token expires.

When to use

Use this skill whenever the user asks a question that requires data from their Garmin watch/account. Examples:

• "How did I sleep last night?"
• "How many gym sessions this week?"
• "What's my average resting HR this month?"
• "Show me my last run"
• "What's my training readiness today?"
• "Did I hit my step goal yesterday?"

For single metrics, call one subcommand. For analytical questions, pull summary or weekly and reason over the JSON.

Usage pattern

1. First run: user sets env vars and invokes login. If MFA is on, two-phase.
2. Subsequent runs: any subcommand. Tokens auto-refresh.
3. Answer the question: parse the JSON output and respond conversationally.

Always prefer --pretty when piping into your own context — compact JSON is for piping into other tools.

Environment setup (one-time)

export GARMIN_EMAIL="your@email.com"
export GARMIN_PASSWORD="yourpassword"
# Optional: persist in ~/.config/garmin-api/env and source from shell rc.

First login with MFA:

# Phase 1 — triggers the email/app MFA prompt and exits with code 2.
bun run scripts/garmin.ts login
# → "[auth] MFA required (email) — code sent."

# Phase 2 — supply the code (≤10 minutes after phase 1).
GARMIN_MFA=123456 bun run scripts/garmin.ts login
# → "[auth] authenticated as <displayName> — tokens cached."

Without MFA: bun run scripts/garmin.ts login completes in one call.

Subcommands

# Identity
bun run scripts/garmin.ts whoami --pretty

# Single-date queries (default: today)
bun run scripts/garmin.ts daily 2026-04-14 --pretty
bun run scripts/garmin.ts sleep 2026-04-14 --pretty
bun run scripts/garmin.ts hrv 2026-04-14 --pretty
bun run scripts/garmin.ts readiness 2026-04-14 --pretty
bun run scripts/garmin.ts training 2026-04-14 --pretty

# Bundle for one day (daily + sleep + hrv + readiness + training + activities)
bun run scripts/garmin.ts summary 2026-04-14 --pretty

# Activity list (date range, inclusive)
bun run scripts/garmin.ts activities --from 2026-04-08 --to 2026-04-14 --pretty
bun run scripts/garmin.ts activities --from 2026-04-08 --to 2026-04-14 --limit 100

# 7-day window ending on <date> (default today)
bun run scripts/garmin.ts weekly 2026-04-14 --pretty

All commands print JSON to stdout. Errors (including MFA prompts) go to stderr.

Analytical patterns

When the user asks an analytical question, pick the smallest query that contains the answer, then reason over the JSON.

For "this week" / "this month": compute the date range yourself before calling. Garmin's API is always date-explicit.

Activity type keys (partial)

Common activityType.typeKey values to filter on:

• running, treadmill_running, trail_running, track_running, indoor_running
• walking, hiking, casual_walking
• cycling, road_biking, mountain_biking, indoor_cycling, virtual_ride
• strength_training, fitness_equipment, indoor_cardio
• swimming, lap_swimming, open_water_swimming
• yoga, pilates, stretching
• other

Failure modes

Self-repair (for Claude)

This skill is designed to be patched in place when Garmin changes its auth or API surface. The compatibility surface is ~6 GET endpoints + the auth flow, and all of them live in scripts/garmin.ts. When something breaks, follow this escalation:

Step 1 — Check if consumer creds rotated

Symptom: 401 Unauthorized on /oauth-service/oauth/preauthorized with "Invalid signature for signature method HMAC-SHA1".

The script already auto-refreshes from https://thegarth.s3.amazonaws.com/oauth_consumer.json (24h cache, retry-on-401). If that URL itself stops working:

1. Check the garth repo for the current canonical source of the consumer pair. Look at garth/client.py or the sso.py constants.
2. If thegarth.s3.amazonaws.com is dead, find the new host in garth's OAUTH_CONSUMER_URL. Update the OAUTH_CONSUMER_URL constant in scripts/garmin.ts.
3. As a last resort, inspect the current Garmin Connect mobile app traffic (mitmproxy + a rooted Android emulator) and read the pair off the first OAuth1-signed request.

Step 2 — Check if the login endpoint moved

Symptom: 404 Not Found on /sso/mobile/api/login or /sso/mobile/api/mfa/verifyCode.

1. Install the latest garth: uvx --with garth python3 -c "import garth.sso as s, inspect; print(inspect.getsource(s.login))"
2. Compare the URL constants, method, body shape, and clientId / service query params against loginInit() / loginComplete() in scripts/garmin.ts.
3. Port any deltas. Things to watch: SSO_CLIENT_ID, SSO_SERVICE_URL, the JSON body field names (rememberMe, captchaToken, mfaVerificationCode, etc.), and the responseStatus.type values (SUCCESSFUL, MFA_REQUIRED).

Step 3 — Check if the User-Agent fingerprint is being blocked

Symptom: 403 immediately, even from a fresh IP.

1. Garmin cycles accepted mobile UAs. Current values:
   • SSO endpoints expect an iPhone Safari UA (SSO_MOBILE_UA constant).
   • Connectapi endpoints expect GCM-iOS-5.22.1.4 (CONNECTAPI_UA constant).
2. Check garth's http.py for the current USER_AGENT dict. Update the constants in scripts/garmin.ts to match.

Step 4 — Check if an API endpoint path or response shape changed

Symptom: 404 on one of the data endpoints (e.g. /usersummary-service/usersummary/daily/...), or JSON.parse failure.

1. Log into Garmin Connect in a browser, open DevTools → Network tab.
2. Find the equivalent request (the web app also hits connectapi.garmin.com via a CSRF-protected proxy; the path is the part after /gc-api/).
3. Update the path in the corresponding method on the Api object in scripts/garmin.ts.
4. Update references/endpoints.md with the new path.

Step 5 — Verify with a fresh login

After any change:

rm -f ~/.config/garmin-api/tokens.json ~/.config/garmin-api/consumer.json
bun run scripts/garmin.ts login
# Phase 2 if MFA: GARMIN_MFA=xxxxxx bun run scripts/garmin.ts login
bun run scripts/garmin.ts whoami --pretty
bun run scripts/garmin.ts summary $(date +%F) --pretty | head -40

If all three succeed, the skill is healthy again.

What NOT to do

• Don't add new npm dependencies — the whole point is a zero-dep single file.
• Don't try to impersonate the web app's connect-csrf-token session flow — it's more brittle than the mobile SSO flow and couples you to cookies.
• Don't hardcode a user-specific value (displayName, ticket, token). They go in ~/.config/garmin-api/tokens.json.

Files

• scripts/garmin.ts — the CLI (single file, zero deps beyond Bun)
• references/endpoints.md — Garmin endpoints this skill calls
• README.md — human-facing intro and setup

Not in scope

• Writing data back to Garmin (activity uploads, settings, etc.)
• Syncing to external systems — that's a downstream concern
• Non-Garmin data sources (Apple Watch, Whoop, Oura, etc.)