Description

Garmin Connect CLI for activities, health, body composition, workouts, devices, gear, goals, and more.

README (SKILL.md)

gccli

Name: Garmin Connect CLI
Author: bpauli

Use gccli for Garmin Connect health, fitness, and activity data. Requires Garmin SSO authentication.

Setup (once)

gccli auth login [email protected] (opens browser for Garmin SSO)
Headless: gccli auth login [email protected] --headless (with --mfa-code \x3Ccode> for MFA)
Set default account: export [email protected]
Verify: gccli auth status

Output

Default: human-friendly tables. Use --json / -j for JSON, --plain for TSV.
Data goes to stdout, messages/errors to stderr.
Always use --json when parsing output programmatically.

Date shortcuts

today, yesterday, 3d (N days ago), YYYY-MM-DD (specific date).
Use --start/--end flags for date ranges.

Common commands

Auth status: gccli auth status
Auth token (for scripting): gccli auth token
Export credentials: gccli auth export (pipe to file or copy to another machine)
Import credentials: gccli auth import \x3Ctoken> (from auth export output)
Remove credentials: gccli auth remove
List activities: gccli activities list --limit 20
List activities by type: gccli activities list --type running
Activity count: gccli activities count
Search activities: gccli activities search --start-date 2024-01-01 --end-date 2024-12-31
Activity summary: gccli activity summary \x3Cid>
Activity details: gccli activity details \x3Cid>
Activity splits: gccli activity splits \x3Cid>
Activity weather: gccli activity weather \x3Cid>
Activity HR zones: gccli activity hr-zones \x3Cid>
Activity power zones: gccli activity power-zones \x3Cid>
Activity exercise sets (show): gccli activity exercise-sets \x3Cid>
Set exercise sets: gccli activity exercise-sets set \x3Cid> -e "CATEGORY/NAME:reps@weightkg[:dSECS][:rSECS]" [-e ...]
Activity gear: gccli activity gear \x3Cid>
Download activity (FIT): gccli activity download \x3Cid> --format fit
Download activity (GPX): gccli activity download \x3Cid> --format gpx --output track.gpx
Upload activity: gccli activity upload ./activity.fit
Create manual activity: gccli activity create --name "Morning Run" --type running --date 2024-06-15T07:30:00 --duration 1800 --distance 5000
Rename activity: gccli activity rename \x3Cid> "New Name"
Retype activity: gccli activity retype \x3Cid> running
Delete activity: gccli activity delete \x3Cid> --force
Activity types: gccli activities types
Health summary: gccli health summary [date]
Steps chart: gccli health steps [date]
Daily steps range: gccli health steps daily --start 2024-01-01 --end 2024-01-31
Weekly steps: gccli health steps weekly --weeks 4
Heart rate: gccli health hr [date]
Resting HR: gccli health rhr [date]
Floors climbed: gccli health floors [date]
Sleep: gccli health sleep [date]
Respiration: gccli health respiration [date]
SpO2: gccli health spo2 [date]
HRV: gccli health hrv [date]
Stress: gccli health stress [date]
Weekly stress: gccli health stress weekly --weeks 4
Body battery: gccli health body-battery [date]
Body battery range: gccli health body-battery range --start 2024-01-01 --end 2024-01-07
Training readiness: gccli health training-readiness [date]
Training status: gccli health training-status [date]
Fitness age: gccli health fitness-age [date]
VO2max / max metrics: gccli health max-metrics [date]
Lactate threshold: gccli health lactate-threshold
Cycling FTP: gccli health cycling-ftp
Race predictions: gccli health race-predictions [date]
Race predictions range: gccli health race-predictions range --start 2024-01-01 --end 2024-06-30
Endurance score: gccli health endurance-score [date]
Hill score: gccli health hill-score [date]
Intensity minutes: gccli health intensity-minutes [date]
Weekly intensity minutes: gccli health intensity-minutes weekly --start 2024-01-01 --end 2024-01-31
Wellness events: gccli health events [date]
Body composition: gccli body composition [date]
Body composition range: gccli body composition --start 2024-01-01 --end 2024-01-31
Weigh-ins: gccli body weigh-ins --start 2024-01-01 --end 2024-01-31
Add weight: gccli body add-weight 75.5 --unit kg
Add composition: gccli body add-composition 75.5 --body-fat 15.2 --muscle-mass 35.0
Blood pressure: gccli body blood-pressure --start 2024-01-01 --end 2024-01-31
Add blood pressure: gccli body add-blood-pressure --systolic 120 --diastolic 80 --pulse 65
List workouts: gccli workouts list --limit 20
Workout detail: gccli workouts detail \x3Cid>
Download workout (FIT): gccli workouts download \x3Cid> --output workout.fit
Upload workout (JSON): gccli workouts upload ./workout.json
Schedule workout: gccli workouts schedule add \x3Cid> 2024-06-20
List scheduled workouts: gccli workouts schedule list 2024-06-20
List scheduled workouts in range: gccli workouts schedule list --start 2024-06-01 --end 2024-06-30
Remove scheduled workout: gccli workouts schedule remove \x3Cschedule-id> (use --force to skip confirmation)
Delete workout: gccli workouts delete \x3Cid>
Create running workout with pace: gccli workouts create "Easy Run" --type run --step "warmup:5m" --step "run:20m@pace:5:00-5:30" --step "cooldown:5m"
Create workout with HR targets: gccli workouts create "HR Run" --type run --step "warmup:10m" --step "run:20m@hr:140-160" --step "cooldown:10m"
Create cycling workout with power: gccli workouts create "FTP Intervals" --type bike --step "warmup:10m" --step "run:5m@power:250-280" --step "recovery:3m" --step "run:5m@power:250-280" --step "cooldown:10m"
List courses: gccli courses list
Favorite courses: gccli courses favorites
Course detail: gccli courses detail \x3Cid>
Import course from GPX (default: cycling, private): gccli courses import route.gpx
Import course with name: gccli courses import route.gpx --name "Sunday Ride"
Import course with type: gccli courses import route.gpx --type gravel_cycling
Import public course: gccli courses import route.gpx --privacy 1
Send course to device: gccli courses send \x3Ccourse-id> \x3Cdevice-id>
Delete course: gccli courses delete \x3Cid> (use -f to skip confirmation)
List devices: gccli devices list
Device settings: gccli devices settings \x3Cdevice-id>
Primary device: gccli devices primary
Last used device: gccli devices last-used
Device alarms: gccli devices alarms
Solar data: gccli devices solar \x3Cdevice-id> --start 2024-06-01 --end 2024-06-30
List gear: gccli gear list
Gear stats: gccli gear stats \x3Cuuid>
Gear activities: gccli gear activities \x3Cuuid> --limit 20
Gear defaults: gccli gear defaults
Link gear: gccli gear link \x3Cuuid> \x3Cactivity-id>
Unlink gear: gccli gear unlink \x3Cuuid> \x3Cactivity-id>
Goals: gccli goals list --status active
Earned badges: gccli badges earned
Available badges: gccli badges available
In-progress badges: gccli badges in-progress
Challenges: gccli challenges list
Badge challenges: gccli challenges badge
Personal records: gccli records
Profile: gccli profile
Profile settings: gccli profile settings
Hydration: gccli hydration [date]
Log water: gccli hydration add 500
Nutrition food log: gccli nutrition [date]
Nutrition meals: gccli nutrition meals [date]
Nutrition settings: gccli nutrition settings [date]
Training plans: gccli training plans --locale en
Training plan detail: gccli training plan \x3Cid>
Menstrual cycle: gccli wellness menstrual-cycle --start-date 2024-01-01 --end-date 2024-03-31
Pregnancy summary: gccli wellness pregnancy-summary
List events: gccli events list
List events from date: gccli events list --start 2024-06-01 --limit 50
Add event: gccli events add --name "Berlin Marathon" --date 2026-09-27 --type running --race --location "Berlin, Germany" --distance 42.195km --time 09:15 --timezone Europe/Berlin
Add event with goal and training priority: gccli events add --name "Spring 10K" --date 2026-05-10 --type running --race --distance 10km --goal 40m --training
Delete event: gccli events delete \x3Cid> (use -f to skip confirmation)
Reload data: gccli reload [date]
List exercise categories: gccli exercises list
List exercises in category: gccli exercises list -c BENCH_PRESS
List exercises (JSON): gccli exercises list --json

Strength training workflow (LLM-assisted exercise matching)

When a user wants to log a strength training activity with exercises described in free text (e.g. "Bench Press 3x12@20kg, Lat Pulldowns 3x12@41kg"), follow this workflow:

Fetch the Garmin exercise catalog: gccli exercises list --json
Map each user-described exercise to the best matching Garmin CATEGORY/EXERCISE_NAME pair. The catalog uses SCREAMING_SNAKE_CASE (e.g. BENCH_PRESS/BARBELL_BENCH_PRESS, PULL_UP/WIDE_GRIP_LAT_PULLDOWN, LATERAL_RAISE/DUMBBELL_LATERAL_RAISE, LUNGE/DUMBBELL_LUNGE, CALF_RAISE/STANDING_BARBELL_CALF_RAISE). Use your best judgement to find the closest match.
Show the user the proposed mapping and ask for confirmation before proceeding.
Create the activity: gccli activity create --name "Upper Body" --type strength_training --duration 34m --date 2024-06-15T19:01:00
Extract the activity ID from the output (JSON: activityId field, table: "Created activity \x3Cid>").
Add exercise sets: gccli activity exercise-sets set \x3Cid> -e "CATEGORY/NAME:reps@weightkg[:dSECS][:rSECS]" [-e ...]

Exercise set format: CATEGORY/NAME:reps@weightkg[:dSECS][:rSECS]

CATEGORY: exercise category (e.g. BENCH_PRESS, PULL_UP, LATERAL_RAISE, LUNGE, CALF_RAISE)
NAME: specific exercise name within category (e.g. BARBELL_BENCH_PRESS, WIDE_GRIP_LAT_PULLDOWN)
reps: number of repetitions
weightkg: weight in kg (e.g. 20 for 20kg, 41.5 for 41.5kg, 0 for bodyweight)
:dSECS: optional set duration in seconds (e.g. :d30 for 30s)
:rSECS: optional rest duration in seconds after this set (e.g. :r60 for 60s)

Each -e flag is one set. For 3 sets of 12 reps, use three -e flags with the same exercise.

Example full workflow:

gccli activity create --name "Upper Body" --type strength_training --duration 34m --date 2026-03-13T19:01:00 --json
# Extract activityId from JSON response
gccli activity exercise-sets set \x3Cid> \
  -e "PULL_UP/WIDE_GRIP_LAT_PULLDOWN:12@41:d30:r60" \
  -e "PULL_UP/WIDE_GRIP_LAT_PULLDOWN:12@41:d30:r60" \
  -e "PULL_UP/WIDE_GRIP_LAT_PULLDOWN:12@41:d30:r90" \
  -e "LATERAL_RAISE/DUMBBELL_LATERAL_RAISE:12@8:d25:r60" \
  -e "LATERAL_RAISE/DUMBBELL_LATERAL_RAISE:12@8:d25:r60" \
  -e "LATERAL_RAISE/DUMBBELL_LATERAL_RAISE:12@8:d25:r90" \
  -e "BENCH_PRESS/BARBELL_BENCH_PRESS:12@20:d30:r60" \
  -e "BENCH_PRESS/BARBELL_BENCH_PRESS:8@20:d35:r60" \
  -e "BENCH_PRESS/BARBELL_BENCH_PRESS:5@20:d40"

Notes

Set [email protected] to avoid repeating --account.
For scripting, use --json for JSON output or --plain for TSV.
Dates support today, yesterday, 3d, or YYYY-MM-DD.
Tokens are stored securely in the OS keyring (macOS Keychain, Linux Secret Service, file fallback).
Tokens auto-refresh on 401; automatic retry on 429/5xx with exponential backoff.
For Garmin China accounts: export GCCLI_DOMAIN=garmin.cn.
Confirm before deleting activities/workouts (or use --force).
Download formats: FIT (default), GPX, TCX, KML, CSV.
Workout step format: type:duration[@target:low-high] — types: warmup, run, recovery, cooldown; targets: pace (min:sec), hr (bpm), power (watts), cadence.

Usage Guidance

This skill appears to be a straightforward wrapper for the open-source gccli tool, but take these practical precautions before installing: (1) Inspect the Homebrew formula and the upstream GitHub repo (https://github.com/bpauli/gccli) to confirm the source and review code or release artifacts; (2) prefer installing from an official release or building from source if you need higher assurance; (3) be careful with auth export/import — treat exported tokens like passwords, avoid storing them in world-readable files or sending them to other machines without secure channels; (4) enable MFA on your Garmin account and avoid using headless auth on untrusted hosts; (5) note OS restriction (darwin/linux) and only install the gccli binary if you trust the third-party tap; (6) if you need stronger assurance, run the tool in an isolated environment (container or dedicated machine) and verify network activity if concerned. If you want, I can fetch and summarise the Homebrew formula or the repo's README to help you assess trustworthiness.

Capability Analysis

Type: OpenClaw Skill Name: garmin-connect-cli Version: 1.8.0 The skill bundle provides documentation and instructions for `gccli`, a legitimate open-source command-line interface for Garmin Connect (github.com/bpauli/gccli). It covers authentication, health data retrieval, and activity management. While the tool includes high-risk capabilities such as exporting authentication tokens (`gccli auth export`), these are documented as standard features for credential management. The instructions for the AI agent are clearly aligned with the tool's stated purpose, and no evidence of malicious intent, data exfiltration to unauthorized endpoints, or prompt injection was found.

Capability Assessment

✓ Purpose & Capability

Name/description match the required binary and commands. Requiring the gccli binary and providing Homebrew/source install options is appropriate for a CLI-focused skill that interfaces with Garmin Connect.

ℹ Instruction Scope

SKILL.md instructs the agent to run gccli commands (auth, list, download, upload, etc.), which is expected. It also documents auth export/import and use of auth tokens; these are legitimate for portability but increase the risk of credential exposure if users pipe tokens to insecure locations. The instructions do not ask the agent to read unrelated system files or external endpoints beyond Garmin.

ℹ Install Mechanism

Install uses a Homebrew formula (bpauli/tap/gccli). Homebrew is a standard mechanism, but this is a third-party tap (not the official core). That is reasonable for an open-source tool but warrants reviewing the formula/source before installing.

✓ Credentials

The skill declares no required environment variables or credentials. The documented use of Garmin SSO and local auth tokens is proportional to the tool's purpose. Users should be cautious when exporting/importing tokens or setting GCCLI_ACCOUNT in shared environments.

✓ Persistence & Privilege

The skill does not request always:true or system-wide configuration changes. It relies on a user-installed binary and runs only when invoked; autonomous invocation is allowed but typical for skills and not combined with other concerning privileges.

Version History

v1.8.0

- Added `gccli activities types` command to list available activity types. - No other user-facing changes detected in this update.

v1.7.1

No significant changes detected in this release. - No file changes found between versions 1.7.1 and the previous release. - Documentation and available commands remain the same.

v1.5.0

- Clarified the syntax for adding exercise sets to activities; now documents support for detailed set definitions with optional duration and rest parameters. - No other changes to features or documentation.

v1.4.0

- Added credential export and import commands: `gccli auth export` and `gccli auth import <token>` for easier account migration. - Enhanced workout scheduling: list scheduled workouts in a date range with `gccli workouts schedule list --start <date> --end <date>`. - Improved exercise sets commands: show or set exercise sets with `gccli activity exercise-sets <id>` and `gccli activity exercise-sets set <id>`. - Minor documentation improvements and command clarifications in CLI usage examples.

v1.3.0

Version 1.3.0 - Added event management commands, including listing, adding, and filtering events via `gccli events ...`. - Example commands for adding events with name, date, type, race flag, location, distance, time, and timezone. - Enhanced documentation with new example usage for event features. - No changes to installation or setup procedures.

v1.1.0

Version 1.1.0 - Added course import commands, allowing importing of courses from GPX files, with options to set name, type, and privacy. - Added `courses delete` command to remove courses. - Updated documentation to include new course-related commands and options.

v1.0.1

- Updated internal metadata structure for improved consistency and compatibility. - Adjusted Homebrew installation metadata for clarity. - No functionality changes or new commands in this release.

v1.0.0

## [1.0.0] - 2026-03-02 ### Added - **`courses` command group** — New commands for managing Garmin Connect courses: - `courses list` — List all user courses with table/JSON/plain output - `courses favorites` — List favorite courses - `courses detail <id>` — View full course detail (JSON) - `courses send <course-id> <device-id>` — Send a course to a device via the device message API - **Courses API methods** — `GetCourses`, `GetCourse`, `GetCourseFavorites`, `SendCourseToDevice` in the API client - **E2E tests for courses** — End-to-end tests against the real Garmin Connect API ### Changed - Updated Go module dependencies (`golang.org/x/net`) - Updated CI dependencies (`actions/checkout` 4→6, `actions/setup-go` 5→6, `goreleaser/goreleaser-action` 6→7)

v0.3.0

Version 0.3.0 Fixed - Garmin Connect API compatibility — Adapted to endpoint and payload changes in the Garmin Connect API

v0.2.0

Version 0.1.1 - Added subcommands for managing workout schedules: `schedule add`, `schedule list`, and `schedule remove`. - Updated example commands to reflect new workout scheduling options. - No code changes; documentation improvements only.

v0.1.0

Initial release of garmin-connect-cli (gccli), a comprehensive CLI tool for Garmin Connect data. - Supports authentication with Garmin SSO, including MFA and headless modes. - Allows access to activities, health metrics, body composition, workouts, devices, gear, goals, badges, challenges, and more. - Provides flexible output formats: human-friendly tables, JSON, and TSV. - Includes extensive date filtering and shortcut options. - Features robust scripting support, token storage, and automatic token refresh.

Metadata

Slug garmin-connect-cli

Version 1.8.0

License MIT-0

All-time Installs 5

Active Installs 5

Total Versions 11

Frequently Asked Questions

What is Garmin Connect CLI?

Garmin Connect CLI for activities, health, body composition, workouts, devices, gear, goals, and more. It is an AI Agent Skill for Claude Code / OpenClaw, with 1246 downloads so far.

How do I install Garmin Connect CLI?

Run "/install garmin-connect-cli" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Garmin Connect CLI free?

Yes, Garmin Connect CLI is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does Garmin Connect CLI support?

Garmin Connect CLI is cross-platform and runs anywhere OpenClaw / Claude Code is available (darwin, linux).

Who created Garmin Connect CLI?

It is built and maintained by Burkhard Pauli (@bpauli); the current version is v1.8.0.

More Skills

Garmin Connect CLI