Garmin Connect. One binary.
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 secure credential storage built in.
Tip: gccli auth login saves your email as the default account automatically.
Install via Homebrew or build from source.
brew install bpauli/tap/gccli
git clone https://github.com/bpauli/gccli.git cd gccli make build ./bin/gccli --help
make tools # Install dev tools make test # Unit tests + race make lint # golangci-lint make fmt # goimports + gofumpt make ci # Full CI gate
Authenticate once via browser or headless, then start querying your Garmin data.
Opens your browser for Garmin SSO. Tokens are stored in your system keyring.
gccli auth login you@example.com
For servers or CI. Supports MFA.
gccli auth login you@example.com --headless gccli auth login you@example.com --headless --mfa-code 123456
Login saves your default account automatically. Check auth status and fetch your recent activities.
gccli auth status gccli activities list --limit 5
Defaults to auto-detect. Force with GCCLI_KEYRING_BACKEND: keychain (macOS), secret-service (Linux D-Bus), or file (encrypted fallback).
Comprehensive Garmin Connect coverage with consistent CLI patterns and clean output.
List, search, view details, splits, weather, HR/power zones. Download FIT/GPX/TCX/KML/CSV. Upload, create, rename, retype, delete.
Steps, heart rate, sleep, stress, HRV, SpO2, respiration, body battery, floors, training readiness, VO2max, fitness age, race predictions.
Create with pace/HR/power/cadence targets, schedule to calendar, download as FIT, upload from JSON. Running, cycling, strength, and more.
Weight tracking, body fat, muscle mass, weigh-in history, blood pressure. Add entries and upload via FIT encoding.
List registered devices, view settings, solar data, alarms. Query primary and last-used device.
List gear, usage stats, linked activities, defaults per activity type. Link and unlink gear to activities.
Active goals, earned/available/in-progress badges, challenges, and personal records.
Browse and view training plans from the Garmin training catalog.
View and log daily water intake. Track hydration by date.
Menstrual cycle tracking, menstrual summaries, and pregnancy summary data.
View user profile information and account settings.
Auto-retry on 429/5xx with exponential backoff, circuit breaker, and automatic OAuth2 token refresh on 401.
Click a group to expand. Every command supports --json, --plain, and --help.
Environment variables, config file, and global flags.
| Variable | Description |
|---|---|
| GCCLI_ACCOUNT | Default account email (overrides config file default) |
| GCCLI_DOMAIN | Garmin domain (garmin.com or garmin.cn) |
| GCCLI_JSON | Enable JSON output (1, true, yes) |
| GCCLI_PLAIN | Enable plain/TSV output |
| GCCLI_COLOR | Color mode: auto, always, never |
| GCCLI_KEYRING_BACKEND | Keyring: keychain, secret-service, file |
| Flag | Description |
|---|---|
| --account <email> | Account to use (overrides GCCLI_ACCOUNT and config default) |
| --json, -j | Output JSON to stdout |
| --plain | Output stable TSV to stdout |
| --color <mode> | Color mode: auto, always, never |
| --version | Print version information |
| --help | Show help for any command |
macOS: ~/Library/Application Support/gccli/config.json
Linux: ~/.config/gccli/config.json
{
"keyring_backend": "file",
"domain": "garmin.com"
}
| Format | Example | Description |
|---|---|---|
| YYYY-MM-DD | 2024-06-15 | Explicit date |
| today | Today's date | |
| yesterday | Yesterday's date | |
| Nd | 3d, 7d | N days ago |
Real-world scripts and one-liners you'll use daily.
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
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
}'
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'
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
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"
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"
Clean layered design with function-variable DI and context-based injection.
Kong-based CLI commands. Each command is a struct with Run(g *Globals) error.
HTTP client returning json.RawMessage. RetryTransport + CircuitBreaker.
SSO auth: browser + headless login, OAuth1→OAuth2 exchange, MFA.
OS keyring abstraction. macOS Keychain, Linux Secret Service, file fallback.
Config file paths and environment variable overrides.
Output formatting: JSON, Table, and Plain/TSV modes via context.
Terminal UI with colors and prompts via termenv.
FIT file binary encoding for weight and body composition uploads.