Garmin Connect. One binary.

Garmin
Connect
in your terminal

gccli is a fast, script-friendly CLI for Garmin Connect — activities, health data, workouts, body composition, devices, gear, goals, badges, and more. JSON output and credential storage in the OS keyring.

Activities Health Workouts Body Devices Gear Goals Badges Courses Events Training Hydration Nutrition Wellness Profile
Install Readme

Tip: gccli auth login saves your email as the default account automatically.

gccli — terminal
$ gccli auth login you@example.com
$ gccli activities list --limit 5
$ gccli health summary today
$ gccli --json body weigh-ins --start 2024-01-01 --end 2024-06-30
$ gccli workouts create "Easy Run" --type run --step "warmup:5m"
Output
tables / --json
Accounts
multi-account
Secrets
OS keyring
Resilience
retry + timeout

Install

Install via Homebrew or build from source.

Homebrew (macOS / Linux)

brew install bpauli/tap/gccli

Build from source

git clone https://github.com/bpauli/gccli.git
cd gccli
make build
./bin/gccli --help

Shell Completions

# Bash (~/.bashrc)
source <(gccli completion bash)

# Zsh (~/.zshrc)
source <(gccli completion zsh)

# Fish (~/.config/fish/config.fish)
gccli completion fish | source

# PowerShell ($PROFILE)
gccli completion powershell | Invoke-Expression

Development

make tools    # Install dev tools
make test     # Unit tests + race
make lint     # golangci-lint
make fmt      # goimports + gofumpt
make ci       # Full CI gate

Quickstart

Authenticate once via browser or headless, then start querying your Garmin data.

1

Log in via browser SSO

Opens your browser for Garmin SSO. Tokens are stored in your system keyring.

gccli auth login you@example.com
2

Or log in headless

For servers or CI. Supports MFA.

gccli auth login you@example.com --headless
gccli auth login you@example.com --headless --mfa-code 123456
3

Start using

Login saves your default account automatically. Check auth status and fetch your recent activities.

gccli auth status
gccli activities list --limit 5
🔑

Keyring backends

Defaults to auto-detect. Force with GCCLI_KEYRING_BACKEND: keychain (macOS), secret-service (Linux D-Bus), or file (fallback). The file backend encrypts tokens with a fixed passphrase that is built into gccli. Anyone who can read the files can decrypt the tokens. Use the keychain or Secret Service when you can.

Features

Comprehensive Garmin Connect coverage with consistent CLI patterns and clean output.

🏃

Activities

List, search, view details, splits, weather, HR/power zones. Download FIT/GPX/TCX/KML/CSV. Upload, create (with date), rename, retype, delete. Set exercise sets for strength training.

❤

Health Data

Steps, heart rate, sleep, stress, HRV, SpO2, respiration, body battery, floors, training readiness, VO2max, fitness age, race predictions.

💪

Workouts

Create with pace/HR/power/cadence targets, schedule to calendar, download as FIT, upload from JSON, update in place without losing the ID or schedule. Running, cycling, strength, and more.

⚖

Body Composition

Weight tracking, body fat, muscle mass, weigh-in history, blood pressure. Add entries and upload via FIT encoding.

🗺

Courses

List courses, view favorites, get full course detail, download as FIT or GPX. Import GPX files as new courses. Send courses directly to your device or delete them.

⌚

Devices

List registered devices, view settings, solar data, alarms. Query primary and last-used device.

👟

Gear

List gear, usage stats, linked activities, defaults per activity type. Link and unlink gear to activities.

🎯

Goals & Badges

Active goals, earned/available/in-progress badges, challenges, and personal records.

📅

Events

List, add, and delete calendar events, such as races and group rides. Set custom goals and training priority.

📅

Training Plans

Browse and view training plans from the Garmin training catalog.

💧

Hydration

View and log daily water intake. Track hydration by date.

🍲

Nutrition

View daily food logs, meal summaries, and nutrition settings by date.

🌿

Wellness

Menstrual cycle tracking, menstrual summaries, and pregnancy summary data.

👤

Profile

View user profile information and account settings.

📏

Your Unit System

Tables show km or miles, pace per km or per mile, and elevation in metres or feet, as set in your Garmin Connect profile. Pin one with --units. JSON is never converted.

🔄

Resilient Networking

Retries 429 up to 3 times within Retry-After, retries 5xx up to 2 times for read requests with exponential backoff, times out after 60 s without response headers, and refreshes OAuth2 tokens on 401.

⌨

Shell Completion

Generated completion scripts for bash, zsh, fish, and PowerShell. Commands, subcommands, flags, and enum values.

🤖

Agent-Ready

Ships a bundled agent skill that plugs into AI assistants like Claude Code, Codex, Hermes, and OpenClaw - drive Garmin Connect in plain language.

Agent & AI Assistant Integration

gccli ships a bundled agent skill that teaches an AI assistant its full command surface. Ask in plain language and let the agent drive the CLI.

agent - chat
you> How did I sleep last week?
you> Download my last three runs as GPX.
you> Log today's session: bench 3x12@20kg,
lat pulldowns 3x12@41kg.
you> Build a tempo run, schedule it Saturday.
agent runs gccli --json…
🤖

Claude Code

Anthropic's terminal-native coding agent. Point it at the bundled skill and drive Garmin Connect conversationally.

⚙

Codex

OpenAI's coding agent. The portable SKILL.md format works out of the box.

🧭

Hermes

Agent runtime with skill support - drop in the gccli skill and go.

🐾

OpenClaw

The skill's frontmatter carries install metadata, so OpenClaw can provision the gccli binary automatically.

📦

Setup

Clone the repo and point your agent at skills/gccli (copy or symlink it into wherever your agent discovers skills). Authenticate once with gccli auth login and set GCCLI_ACCOUNT. The skill instructs the agent to use --json output and to confirm before destructive actions.

Commands

Click a group to expand. Every command supports --json, --plain, and --help. Only some commands print TSV with --plain. Most others print JSON in all modes (see Global Flags below).

Authentication

▶
gccli auth login <email>
Log in via browser SSO
gccli auth login <email> --headless
Log in via email/password
gccli auth login <email> --headless --mfa-code <code>
Log in with MFA
gccli auth status
Show auth state and token expiry (exit 3 if no credentials are stored)
gccli auth token
Print OAuth2 access token
gccli auth export
Export credentials for transfer to another machine
gccli auth import <token>
Import credentials from another machine
gccli auth remove
Remove stored credentials

Activities

▶
gccli activities list --limit 20 --start 0
List recent activities
gccli activities list --type running
Filter by activity type
gccli activities count
Total activity count
gccli activities search --start-date ... --end-date ...
Search by date range
gccli activity summary <id>
Activity summary
gccli activity details <id>
Full activity details
gccli activity splits <id>
Activity split data
gccli activity typed-splits <id>
Typed splits
gccli activity split-summaries <id>
Split summaries
gccli activity weather <id>
Weather during activity
gccli activity hr-zones <id>
Heart rate zone breakdown
gccli activity power-zones <id>
Power time in zones
gccli activity exercise-sets <id>
Exercise sets
gccli activity gear <id>
Linked gear
gccli activity download <id> --format fit
Download as FIT/GPX/TCX/KML/CSV
gccli activity upload ./activity.fit
Upload a FIT file
gccli activity create --name "Run" --type running --duration 30m
Create manual activity entry
gccli activity create --name "Workout" --type strength_training --duration 34m --date 2026-03-13T19:01:00
Create activity with date
gccli activity exercise-sets set <id> -e "BENCH_PRESS/BARBELL:12@20:d30:r60"
Set exercise sets for strength training
gccli exercises list
Browse exercise categories
gccli exercises list -c BENCH_PRESS
List exercises in a category
gccli activity rename <id> "New Name"
Rename an activity
gccli activity retype <id> --type-id 1 --type-key running
Change activity type
gccli activity delete <id> --force
Delete an activity
gccli activities types
List all Garmin activity types

Health Data

▶
gccli health summary [date]
Daily health summary
gccli health steps [date]
Step chart for a day
gccli health steps daily --start ... --end ...
Daily step totals in a range
gccli health steps weekly --weeks 4
Weekly step totals
gccli health hr [date]
Heart rate data
gccli health rhr [date]
Resting heart rate
gccli health sleep [date]
Sleep data
gccli health stress [date]
Stress scores
gccli health stress weekly --weeks 4
Weekly stress data
gccli health hrv [date]
Heart rate variability
gccli health spo2 [date]
Blood oxygen saturation
gccli health body-battery [date]
Body battery levels
gccli health body-battery range --start ... --end ...
Body battery data for a date range
gccli health respiration [date]
Respiration rate
gccli health floors [date]
Floors climbed
gccli health training-readiness [date]
Training readiness score
gccli health training-status [date]
Training status
gccli health fitness-age [date]
Fitness age estimate
gccli health max-metrics [date]
VO2max and performance metrics
gccli health race-predictions
Race time predictions
gccli health race-predictions range --start ... --end ...
Race predictions for a date range
gccli health endurance-score [date]
Endurance score
gccli health hill-score [date]
Hill score
gccli health intensity-minutes [date]
Intensity minutes
gccli health intensity-minutes weekly --start ... --end ...
Weekly intensity minutes for a date range
gccli health lactate-threshold
Lactate threshold
gccli health cycling-ftp
Cycling FTP
gccli health events [date]
Daily wellness events
gccli health lifestyle [date]
Lifestyle logging data

Body Composition

▶
gccli body composition
Today's body composition
gccli body composition --start ... --end ...
Body composition over a date range
gccli body weigh-ins --start ... --end ...
Weigh-in history
gccli body daily-weigh-ins [date]
Weigh-in data for a single day
gccli body add-weight 75.5 --unit kg
Log a weight entry
gccli body add-composition 75.5 --body-fat 15.2 --muscle-mass 35.0
Log full body composition
gccli body blood-pressure --start ... --end ...
Blood pressure history
gccli body add-blood-pressure --systolic 120 --diastolic 80
Log blood pressure
gccli body delete-weight <pk> --date ...
Delete a weight entry
gccli body delete-blood-pressure <version> --date ...
Delete a blood pressure entry

Workouts

▶
gccli workouts list --limit 20
List saved workouts
gccli workouts detail <id>
View workout details
gccli workouts download <id> --output workout.fit
Download workout as FIT
gccli workouts upload ./workout.json
Upload workout from JSON
gccli workouts update <id> ./workout.json
Replace a workout in place, keeping its ID and schedule
gccli workouts create "Name" --type run --step "warmup:5m" ...
Create with pace/HR/power targets
gccli workouts schedule add <id> <YYYY-MM-DD>
Schedule workout on a date
gccli workouts schedule list <YYYY-MM-DD>
List scheduled workouts for a date
gccli workouts schedule list --start 2024-06-01 --end 2024-06-30
List scheduled workouts in a date range
gccli workouts schedule remove <schedule-id> [-f]
Remove a scheduled workout
gccli workouts delete <id>
Delete a workout

Courses

▶
gccli courses list
List your courses
gccli courses favorites
List favorite courses
gccli courses detail <id>
View course details
gccli courses download <id> --format fit
Download course as FIT or GPX
gccli courses import route.gpx
Import GPX as new course (default: cycling, private)
gccli courses import route.gpx --name "Ride"
Import with custom name
gccli courses import route.gpx --type hiking
Override activity type
gccli courses import route.gpx --privacy 1
Import as public course
gccli courses send <course-id> <device-id>
Send course to a device
gccli courses delete <id> [-f]
Delete a course

Devices

▶
gccli devices list
List registered devices
gccli devices settings <device-id>
View device settings
gccli devices primary
Show primary device
gccli devices last-used
Show last-used device
gccli devices alarms
List device alarms
gccli devices solar <device-id> --start ... --end ...
Solar charging data

Gear

▶
gccli gear list
List all gear
gccli gear stats <uuid>
Gear usage statistics
gccli gear activities <uuid> --limit 20
Activities linked to gear
gccli gear defaults
Default gear per activity type
gccli gear link <uuid> <activity-id>
Link gear to activity
gccli gear unlink <uuid> <activity-id>
Unlink gear from activity

Goals, Badges & Challenges

▶
gccli goals list
List active goals
gccli goals list --status past
List goals by status: active, future or past
gccli badges earned
Earned badges
gccli badges available
Available badges
gccli badges in-progress
In-progress badges
gccli challenges list
Active challenges
gccli challenges badge
Badge challenges
gccli records
Personal records

Events

▶
gccli events list
List upcoming calendar events
gccli events list --start 2024-06-01 --limit 50
List events from a date
gccli events add --name "Race" --date 2026-09-27 --type running --race
Add a race event
gccli events add --name "10K" --date 2026-05-10 --type running --distance 10km --goal 40m --training
Add event with goal & training priority
gccli events delete <id>
Delete an event (with confirmation)

Hydration, Nutrition, Profile, Training, Wellness & Utilities

▶
gccli hydration [date]
View hydration data
gccli hydration add 500
Log 500ml of water
gccli nutrition [date]
View daily food log
gccli nutrition meals [date]
View meal summaries
gccli nutrition settings [date]
View nutrition settings
gccli profile
User profile
gccli profile settings
Account settings
gccli training plans --locale en
Browse training plans
gccli training plan <id>
View a training plan
gccli wellness menstrual-cycle --start-date ... --end-date ...
Menstrual cycle data
gccli wellness menstrual-summary --start-date ... --end-date ...
Menstrual cycle summary
gccli wellness pregnancy-summary
Pregnancy summary
gccli reload [date]
Reload data for a date
gccli completion bash
Generate bash completion script
gccli completion zsh
Generate zsh completion script
gccli completion fish
Generate fish completion script
gccli completion powershell
Generate PowerShell completion script

Configuration

Environment variables, config file, and global flags.

Environment Variables

VariableDescription
GCCLI_ACCOUNTDefault account email (overrides config file default)
GCCLI_DOMAINGarmin domain (garmin.com or garmin.cn)
GCCLI_JSONEnable JSON output (1, true, yes)
GCCLI_PLAINEnable plain/TSV output
GCCLI_COLORColor mode: auto, always, never
GCCLI_UNITSUnit system: auto, metric, statute_us, statute_uk
GCCLI_KEYRING_BACKENDKeyring: keychain, secret-service, file

Global Flags

FlagDescription
--account <email>Account to use (overrides GCCLI_ACCOUNT and config default)
--json, -jOutput JSON to stdout. Runtime errors go to stderr as {"error":{"code":"...","status":404,"message":"..."}}
--plainOutput TSV to stdout, with no header row. Only these commands print TSV: activities list, activities search, activities types, activity summary, courses list, courses favorites, courses import, events list, workouts list, workouts schedule list and exercises list (without --category). Most other commands print JSON in all modes.
--color <mode>Color mode: auto, always, never
--units <system>Unit system for table and plain output: auto (default, from the Garmin profile), metric (km, m), statute_us (mi, ft), statute_uk (mi, m). Precedence: flag, GCCLI_UNITS, config "units", Garmin profile, metric. Pin it for scripts that parse --plain.
--versionPrint version information
--helpShow help for any command

Exit Codes

CodeMeaning
0Success
1Other error
2Usage error (unknown command, flag or value); usage text goes to stderr
3Login needed: no account, no stored credentials, or an expired token
4Garmin returned 404 Not Found
5Garmin rate limit (HTTP 429)
📄

Config file

macOS: ~/Library/Application Support/gccli/config.json
Linux: ~/.config/gccli/config.json

{
  "keyring_backend": "file",
  "domain": "garmin.com"
}

Date Formats

FormatExampleDescription
YYYY-MM-DD2024-06-15Explicit date
todayToday's date
yesterdayYesterday's date
Nd3d, 7dN days ago

Examples

Real-world scripts and one-liners you'll use daily.

Export all runs from the last month

Fetch running activities and download each as GPX.

gccli --json activities search \
  --start-date 2024-05-15 --end-date 2024-06-15 \
  --limit 100 | \
  jq -r '.[] | select(.activityType.typeKey == "running") | .activityId' | \
  while read id; do
    gccli activity download "$id" --format gpx --output "run_${id}.gpx"
  done

Daily health dashboard

Pull today's key metrics into a JSON summary.

gccli --json health summary | jq '{
  steps: .totalSteps,
  calories: .totalKilocalories,
  distance_km: (.totalDistanceMeters / 1000),
  active_minutes: .moderateIntensityMinutes + .vigorousIntensityMinutes
}'

Track weight over time

Export weigh-in data as tab-separated values.

gccli --json body weigh-ins \
  --start 2024-01-01 --end 2024-06-30 | \
  jq -r '.dailyWeightSummaries[] | [.summaryDate, .weight.value] | @tsv'

Download the latest activity

One-liner to grab your most recent activity.

latest=$(gccli --json activities list --limit 1 | jq -r '.[0].activityId')
gccli activity download "$latest" --format fit

Create a structured running workout

Warmup, pace intervals, and cooldown.

gccli workouts create "Tempo 30min" --type run \
  --step "warmup:5m@pace:5:30-6:00" \
  --step "run:20m@pace:5:00-5:30" \
  --step "cooldown:5m"

Cycling with power targets

FTP interval workout for the bike.

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"

Architecture

Clean layered design with function-variable DI and context-based injection.

cmd/gccli/main.go → internal/cmd/ → internal/garminapi/ → internal/garminauth/

internal/cmd/

Kong-based CLI commands. Each command is a struct with Run(g *Globals) error.

internal/garminapi/

HTTP client returning json.RawMessage. RetryTransport.

internal/garminauth/

SSO auth: browser + headless login, DI OAuth exchange, MFA.

internal/secrets/

OS keyring abstraction. macOS Keychain, Linux Secret Service, file fallback.

internal/config/

Config file paths and environment variable overrides.

internal/outfmt/

Output formatting: JSON, Table, and Plain/TSV modes via context.

internal/ui/

Terminal UI with colors and prompts via termenv.

internal/fit/

FIT file binary encoding for weight and body composition uploads.

gccli architecture diagram showing the layered design: CLI commands, API client, authentication, secrets, and cross-cutting utilities