garmin-py 2.7.0

CLI tool for extracting health and activity data from Garmin Connect

garmin-cli

A command-line tool for extracting health, activity, workout, and performance data from Garmin Connect. Designed for both human use (table output) and LLM agent consumption (JSON output).

Installation

From PyPI (the distribution is garmin-py; the installed command is garmin-cli):

pip install garmin-py

Or from a local checkout:

pip install .

Verify the installation:

garmin-cli --version

Authentication

garmin-cli authenticates via the maintained python-garminconnect backend. The primary session-home surface is now GARMIN_HOME / --garmin-home; GARTH_HOME / --garth-home remains as a deprecated compatibility alias.

Interactive login (recommended)

garmin-cli login
# Email: [e-mail]
# Password: (hidden)
# Login successful. Token store saved at: ~/.garminconnect/garmin_tokens.json

Use --email / --password to skip the prompts (useful for scripting):

garmin-cli login --email [e-mail] --password yourpassword

Check login status at any time:

garmin-cli login status
# Logged in. Token store at: ~/.garminconnect/garmin_tokens.json

garmin-cli --json login status
# {"ok": true, "command": "login status", "count": 1, "data": [{"authenticated": true, "garmin_home": "..."}]}

Environment variables (alternative)

export GARMIN_EMAIL="[e-mail]"
export GARMIN_PASSWORD="yourpassword"
garmin-cli health sleep --days 1

Variable	Default	Description
GARMIN_EMAIL	—	Account email for credential-based login
GARMIN_PASSWORD	—	Account password for credential-based login
GARMIN_CLI_HTTP_TIMEOUT	30	HTTP request timeout in seconds (float); invalid or non-positive values fall back to 30
GARMIN_CLI_RETRY_DELAYS	2,4,8	Comma-separated retry delay sequence in seconds (e.g. 1,2,4); invalid values fall back to 2,4,8
GARMIN_CLI_AUTH_PROBE_TTL	600	Seconds to cache a successful auth probe in the MCP server (float); 0 disables caching and probes on every call
GARMIN_CLI_DAILY_CALL_DELAY	0.5	Delay in seconds (float) between request submissions for endpoints that fan out one request per day (e.g. daily-summary); invalid or negative values fall back to 0.5
GARMIN_CLI_FETCH_CONCURRENCY	4	Worker cap for concurrent fan-out fetches (per-day ranges, report snapshot sections, multisport children); invalid or non-positive values fall back to 4

Custom session directory

garmin-cli --garmin-home /path/to/session login
garmin-cli --garmin-home /path/to/session health sleep --days 1

The default session directory is ~/.garminconnect. It is created with 0o700 permissions. Symlinks are rejected. Do not share this directory.

New sessions are stored as garmin_tokens.json inside GARMIN_HOME. If you still have an existing ~/.garth/garmin_tokens.json, the CLI will copy it into the new default home on first use. GARTH_HOME / --garth-home still work as deprecated aliases when you need to keep an older path explicitly.

Output Formats

All commands default to table output. Use --json or --format csv to change:

garmin-cli health sleep --days 7              # table (default)
garmin-cli --json health sleep --days 7       # JSON envelope
garmin-cli --format csv health sleep --days 7 # CSV

JSON envelope structure:

{
  "ok": true,
  "command": "health sleep",
  "date_range": {"from": "2026-03-05", "to": "2026-03-11"},
  "count": 7,
  "data": [
    {"date": "2026-03-05", "bedtime": "2026-03-04T23:10:00", "wake_time": "2026-03-05T06:25:00", "duration_hours": 7.2, "score": 78, ...}
  ]
}

Error envelope:

{
  "ok": false,
  "command": "health sleep",
  "error": "Rate limited by Garmin. Try again later.",
  "error_code": "RATE_LIMITED"
}

Exit code is always 0 on success, 1 on error.

Commands

Health

garmin-cli health sleep            [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health hrv              [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health weight           [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health body-battery     [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health stress           [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health spo2             [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health resting-hr       [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health readiness        [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health status           [--date DATE]
garmin-cli health steps            [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health daily-summary    [--date DATE | --from DATE --to DATE | --days N]
garmin-cli health intensity-minutes [--date DATE | --from DATE --to DATE | --days N]

health daily-summary makes one API call per day — large date ranges may be slow.

health status returns Garmin's full training-load picture for the day: training status, acute/chronic load, acute:chronic workload ratio (ACWR), the chronic-load "tunnel", monthly load-focus buckets with their targets, and load-balance status.

Activities

garmin-cli activity list             [--limit N] [--type TYPE] [--search TEXT] [--date DATE | --from DATE --to DATE | --days N]
garmin-cli activity get              ACTIVITY_ID [--detail] [--laps]  # --detail/-d shows sport-aware metrics; --laps appends lap data
garmin-cli activity laps             ACTIVITY_ID  # per-lap rows (run/bike: HR, power, cadence, start_time_gmt/local) or per-pool-length rows (lap_swimming)
garmin-cli activity zones            ACTIVITY_ID  # HR time-in-zone breakdown
garmin-cli activity weather          ACTIVITY_ID  # temperature, apparent temp, dew point, humidity, wind, condition
garmin-cli activity metrics-describe ACTIVITY_ID  # metric descriptors: key, unit, metricsIndex
garmin-cli activity detail-metrics   ACTIVITY_ID [--metric KEY]...  # raw per-sample time series (one row per sample)
garmin-cli activity download         ACTIVITY_ID [--fmt original|tcx|gpx|kml|csv] [--output PATH] [--force]
garmin-cli activity upload           FILE         # .fit / .gpx / .tcx
garmin-cli activity delete           ACTIVITY_ID [--confirm]
garmin-cli activity rename           ACTIVITY_ID NEW_NAME
garmin-cli activity set-type         ACTIVITY_ID TYPE_KEY  # e.g. running, cycling

--limit defaults to 20, max 100. --type filters by activity type key (e.g., running, cycling).

activity detail-metrics returns the raw recorded sample stream (~2000 rows for a typical activity; columns are the watch's metric keys such as directTimestamp, directHeartRate, directPower). Use repeatable --metric flags to select columns — activity metrics-describe lists what a given activity recorded. This is the data for intra-activity analyses such as first-half vs second-half aerobic decoupling.

activity download writes the activity file to disk (it never prints binary to stdout). --fmt defaults to original (the FIT file inside a ZIP archive); the default output name is activity_<id><ext> in the current directory, and an existing file is not overwritten unless --force is given. activity delete prompts for confirmation unless --confirm is passed. activity set-type accepts any typeKey from Garmin's live sport-type table (an unknown key is rejected before any write).

Detailed sport-specific metrics

activity get --detail projects metrics scoped by the activity's sport:

Sport	Detail-mode metrics (in addition to base summary, HR, calories, elevation, speed, elapsed time)
Cycling	avg/max/normalized power, cadence (rpm), TSS, intensity factor, training effect, vO2max, recovery time
Running	cadence (spm), ground contact time, vertical oscillation/ratio, stride length, training effect, vO2max, recovery time
Lap swimming	SWOLF, total strokes, average stroke rate, distance per stroke, training effect
Open water swimming	universal extras + training effect (no per-length stroke metrics)

Every sport also carries the universal training-response fields: training_effect_label (Garmin's primary-benefit label such as TEMPO), training_load (per-activity EPOC-based load), and workout_id (the structured workout the activity executed, linking plan to execution). training_load also appears in activity list rows.

duration_min is moving time; elapsed_time_min is total wall-clock time, so elapsed - moving is the time stopped.

JSON and CSV output use a stable union schema — every key is present (with null for sport-inapplicable metrics) so downstream parsers see a stable shape. Table output is sport-aware: only sport-applicable columns appear, keeping tables dense.

When --detail is set, JSON also carries an unavailable array describing which registry-known metrics are not produced for this activity. Each entry has field, reason (not_applicable_to_sport or absent_in_response), and leg_index (set on multisport child contributions). Table output prints a single counts-only footnote; CSV output stays a flat tabular format and does not carry the manifest.

# Cycling detail
garmin-cli activity get 12345678 --detail

# Running detail with HR zones
garmin-cli activity get 12345678 --detail
garmin-cli activity zones 12345678

# Pool-swim per-length rows (auto-routes to typed_splits)
garmin-cli activity laps 12345678

# Cycling detail + lap power suite in one envelope
garmin-cli --json activity get 12345678 --detail --laps

Workouts

# Read
garmin-cli workout list     [--limit N]
garmin-cli workout get      WORKOUT_ID
garmin-cli workout calendar [--from DATE --to DATE | --days N | --ahead N]

# Write
garmin-cli workout create   FILE                   # JSON or YAML file
garmin-cli workout create   --stdin                # read JSON from stdin
garmin-cli workout update   WORKOUT_ID FILE        # partial update (only fields provided change)
garmin-cli workout delete   WORKOUT_ID [--confirm] # --confirm skips interactive prompt
garmin-cli workout schedule WORKOUT_ID DATE        # DATE = YYYY-MM-DD
garmin-cli workout unschedule SCHEDULE_ID [--confirm] # removes a calendar entry; SCHEDULE_ID is the workoutScheduleId returned by schedule

--ahead N shows the next N days of planned workouts (future-facing). --days N shows past N days.

YAML input is supported out of the box. See SKILL.md for the full workout JSON schema reference and step/target types.

Performance

garmin-cli performance thresholds
garmin-cli performance zones
garmin-cli performance vo2max
garmin-cli performance race-predictions
garmin-cli performance endurance-score [--date DATE | --from DATE --to DATE | --days N]
garmin-cli performance hill-score      [--date DATE | --from DATE --to DATE | --days N]
garmin-cli performance personal-records

performance endurance-score and performance hill-score make one API call per day — large date ranges may be slow.

performance personal-records returns all-time PRs (fastest 1 km through marathon, longest run/ride, biggest climb, best 20-min power, step records) with a human-readable label; typeIds Garmin has not documented publicly carry label: null with the raw value.

Devices

garmin-cli device list  # registered devices: device_id, display_name, device_type, last_sync_time

Normalized JSON Schemas

Recent fixes normalized several JSON payloads for agent-safe output:

• performance vo2max returns date, vo2max, sport
• performance zones returns sport, lt_hr_bpm, lt_pace
• workout calendar includes id
• workout get includes steps and steps_summary
• health hrv reads lastNightAvg and still falls back to legacy lastNight

Date Range Options

Option	Meaning	Example
--date DATE	Single day	--date 2026-03-11
--days N	Past N days (inclusive)	--days 7
--from DATE --to DATE	Explicit range (both inclusive)	--from 2026-03-01 --to 2026-03-11
--ahead N	Next N days (calendar only)	--ahead 7

Maximum range: 90 days. Conflicting options (e.g., --date with --days) produce a clear error.

Examples

# Last week of sleep data
garmin-cli health sleep --days 7

# HRV for a specific date range
garmin-cli health hrv --from 2026-03-01 --to 2026-03-10

# List recent running activities as CSV
garmin-cli --format csv activity list --limit 10 --type running

# Activities from a specific date range
garmin-cli activity list --from 2026-03-01 --to 2026-03-31

# Activities from the past 7 days
garmin-cli activity list --days 7

# Upcoming planned workouts
garmin-cli workout calendar --ahead 7

# Create a workout from a JSON file
garmin-cli --json workout create my_workout.json

# Create and schedule a workout via stdin
echo '{"name":"Easy Run","sport":"running","steps":[{"type":"interval","duration":{"type":"time","value":1800},"target":{"type":"heart.rate.zone","zone":2}}]}' \
  | garmin-cli --json workout create --stdin

# Schedule an existing workout
garmin-cli --json workout schedule 12345678901 2026-04-01

# All performance thresholds
garmin-cli performance thresholds

# Agent use: JSON output for scripting
garmin-cli --json health hrv --date 2026-03-11
garmin-cli --json activity list --limit 5

Error Codes

Code	Meaning
AUTH_MISSING	No credentials found (no session and no env vars)
AUTH_FAILED	Credentials rejected by Garmin
NOT_FOUND	API endpoint unavailable (404)
RATE_LIMITED	429 after 3 retries
SERVER_ERROR	5xx after 3 retries
NETWORK_ERROR	Connection or timeout failure
INVALID_INPUT	Bad arguments or conflicting options
INTERNAL_ERROR	Unexpected error

MCP Server (Optional)

Expose garmin-cli as an MCP tool server for local or remote MCP clients. Includes read tools for health, activities, workouts, performance, and devices, plus write tools for workouts (workout_create, workout_schedule, workout_update, workout_delete, workout_unschedule, with dry-run preview on create and update) and activities (activity_download, activity_upload, activity_delete, activity_rename, activity_set_type). The report_snapshot tool assembles a full morning/evening/weekly report in a single call, fanning out the underlying reads server-side — designed for recurring agent-driven daily summaries. See SKILL.md for its section composition.

Installation

The package is published on PyPI as garmin-py (the CLI command remains garmin-cli). The recommended install method is uv tool install, which places the binary in ~/.local/bin — a stable, venv-independent location that desktop applications can access without macOS sandbox issues:

uv tool install "garmin-py[mcp]"

Or from a source checkout:

uv tool install --editable "/path/to/garmin-py[mcp]"

To uninstall:

uv tool uninstall garmin-py

Avoid pointing MCP clients at a binary inside a project virtualenv (e.g. .venv/bin/garmin-cli). On macOS, desktop applications run in a sandbox and cannot read pyvenv.cfg inside directories they have not been granted access to, which causes a fatal Python startup error:

PermissionError: [Errno 1] Operation not permitted: '/path/to/.venv/pyvenv.cfg'

The uv tool install approach avoids this entirely. Alternatively, grant Claude Desktop Full Disk Access in System Settings → Privacy & Security → Full Disk Access.

Claude Desktop

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "garmin": {
      "command": "/Users/YOU/.local/bin/garmin-cli",
      "args": ["mcp-server"]
    }
  }
}

With a custom session directory:

{
  "mcpServers": {
    "garmin": {
      "command": "/Users/YOU/.local/bin/garmin-cli",
      "args": ["--garmin-home", "/path/to/.garminconnect", "mcp-server"]
    }
  }
}

Claude Code

claude mcp add --transport stdio garmin -- garmin-cli mcp-server

ChatGPT (via MCP bridge)

ChatGPT does not natively support MCP. To connect, run the server with an HTTP transport and use an MCP-to-OpenAI bridge such as mcp-openai-bridge or a similar proxy:

# Start the MCP server with streamable HTTP
garmin-cli mcp-server --transport streamable-http --host 127.0.0.1 --port 8000

Then point the bridge at http://127.0.0.1:8000/mcp and configure it as a ChatGPT plugin or custom GPT action. Refer to the bridge project's documentation for setup details.

HTTP Transports

SSE and streamable HTTP use the MCP SDK's built-in HTTP server. --host defaults to 127.0.0.1 (loopback only).

Streamable HTTP (recommended for remote clients):

garmin-cli mcp-server --transport streamable-http --port 8000

SSE (for clients that require it):

garmin-cli mcp-server --transport sse --port 8000

Optional HTTP flags: --sse-path, --message-path (SSE only), --streamable-http-path, --stateless-http, --json-response (streamable-http only).

Bearer-token gate on non-loopback binds

Binding to any non-loopback address (--host 0.0.0.0 or an external interface) requires a bearer token. The server refuses to start otherwise.

export GARMIN_MCP_BEARER_TOKEN="<a-long-random-token>"
garmin-cli mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

When the token is set and the bind is non-loopback, the MCP SDK gates every tool call (read and write) through Authorization: Bearer <token> at the transport layer. Loopback binds (127.0.0.1, ::1, localhost) and the stdio transport are not gated -- they are trusted to the same degree as the shell user running the process.

TLS is expected to be terminated by a reverse proxy in front of the server; the built-in HTTP listener is plain HTTP.

For remote clients, prefer a dedicated session directory with --garmin-home rather than exporting credentials into another process.

See SKILL.md for the full tool list and parameter reference.

Development

pip install -e ".[dev]"
pytest tests/            # unit tests (1100+ tests)
pytest tests/ --e2e      # unit + e2e tests (requires GARMIN_HOME/garmin_tokens.json)

To run MCP server tests, also install the mcp extra:

pip install -e ".[dev,mcp]"

E2E tests make real Garmin Connect API calls. They require a valid garmin_tokens.json session in ~/.garminconnect (or GARMIN_HOME; GARTH_HOME still works as an alias). Set E2E_RATE_LIMIT_SECONDS (default: 5) to adjust the inter-request delay.