Garmin CLI (gc)

A fully non-interactive CLI to read health data from Garmin Connect.

Installation

brew install voydz/tap/garmin-cli

Or install from source with uv:

git clone https://github.com/voydz/garmin-cli.git
cd garmin-cli
uv sync
uv run gc --help

Authentication

# Login with email and password
gc login --email you@example.com --password yourpass

# Login with MFA code
gc login --email you@example.com --password yourpass --mfa 123456

# Login waiting for MFA prompt on stdin
gc login --email you@example.com --password yourpass --wait-mfa

# Credentials can also be set via environment variables
export GARMIN_EMAIL="you@example.com"
export GARMIN_PASSWORD="yourpass"
gc login

# Check login status
gc status
gc status --profile

# Logout
gc logout

Tokens are stored in ~/.config/garmin-cli/tokens/ by default. Override with --tokenstore PATH or the GARMINTOKENS environment variable.

Usage

Most commands accept a date shortcut as their first argument:

Shortcut	Meaning
today	Today's date
yesterday	Yesterday's date
week	Last 7 days
month	Last 30 days
YYYY-MM-DD	Specific date

Global Options

All data commands support:

• --format json or --format table (default: table)
• --output FILE to write output to a file
• --tokenstore PATH to use a custom token directory

Daily Health

gc health today
gc health yesterday --format json
gc steps week
gc steps --weekly --weeks 8
gc steps --start 2025-01-01 --end 2025-01-31
gc floors today
gc intensity today
gc intensity --weekly
gc events yesterday

Heart Rate

gc heart --date today
gc heart resting --date yesterday

Sleep

gc sleep today

Stress & Body Battery

gc stress --date today
gc stress --weekly --weeks 4
gc stress all-day yesterday

gc battery today
gc battery --start 2025-01-01 --end 2025-01-07
gc battery --events today

Vitals

gc respiration today
gc spo2 today
gc blood-pressure today
gc blood-pressure --end 2025-01-31
gc lifestyle today

Activities

gc activities                              # List recent activities
gc activities --limit 50 --type running
gc activities --start 2025-01-01 --end 2025-01-31
gc activities --date today
gc activities last
gc activities get 12345678
gc activities count
gc activities details 12345678
gc activities splits 12345678
gc activities typed-splits 12345678
gc activities split-summaries 12345678
gc activities weather 12345678
gc activities hr-zones 12345678
gc activities power-zones 12345678
gc activities exercise-sets 12345678
gc activities types
gc activities gear 12345678
gc activities progress --start 2025-01-01 --end 2025-12-31 --metric distance

# Download and upload
gc activities download 12345678 --format fit -o myrun.zip
gc activities download 12345678 --format gpx
gc activities upload myactivity.fit

Body & Weight

gc body --date today
gc body --end 2025-01-31
gc body weighins today
gc body weighins --start 2025-01-01 --end 2025-01-31

Advanced Metrics

gc metrics                    # Latest metrics summary
gc metrics --date today
gc metrics vo2max today
gc metrics hrv today
gc metrics training-readiness today
gc metrics morning-readiness today
gc metrics training-status today
gc metrics fitness-age today
gc metrics race-predictions
gc metrics race-predictions --start 2025-01-01 --end 2025-06-01 --type monthly
gc metrics endurance-score today
gc metrics endurance-score --end 2025-01-31
gc metrics hill-score today
gc metrics lactate-threshold
gc metrics lactate-threshold --no-latest --start 2025-01-01 --end 2025-06-01
gc metrics cycling-ftp

Hydration

gc hydration today

Devices

gc devices
gc devices last-used
gc devices primary
gc devices settings DEVICE_ID
gc devices alarms
gc devices solar DEVICE_ID today

Goals, Badges & Challenges

gc records
gc goals
gc goals --status past --limit 50
gc badges earned
gc badges available
gc badges in-progress
gc challenges adhoc
gc challenges badge
gc challenges available
gc challenges non-completed
gc challenges virtual

Gear

gc gear --user-profile USER_PROFILE_NUMBER
gc gear defaults USER_PROFILE_NUMBER
gc gear stats GEAR_UUID
gc gear activities GEAR_UUID --limit 50

Workouts & Training Plans

gc workouts
gc workouts get WORKOUT_ID
gc workouts download WORKOUT_ID -o workout.fit
gc workouts scheduled WORKOUT_ID
gc workouts create --file workout.json
gc workouts update WORKOUT_ID --file workout.json
gc workouts delete WORKOUT_ID

gc training-plans
gc training-plans get PLAN_ID
gc training-plans adaptive PLAN_ID

Workout creation notes:

• Prefer --file with a Garmin-shaped payload.
• Get a valid payload shape from Garmin, then edit it:
  • gc workouts get WORKOUT_ID --format json > workout.json
  • Update fields you want to change (e.g., workoutName, sportType, workoutSegments).
• To discover sport type ids/keys, use:
  • gc activities types --format json
• If you use flags instead of --file, --steps can be either:
  • A JSON array of Garmin workoutSteps objects, or
  • A shorthand array with type, duration (seconds), and optional target (e.g. hr_zone:2).
• Power targets in shorthand can be defined as watts:
  • power:200 (exact target)
  • power:200-220 (target range)
• --sport-id is optional when --sport is provided; the CLI resolves the id from activity types. Workout update notes:
• gc workouts update with --steps fetches the existing workout payload, replaces the first segment's steps, and preserves other fields.
• Workouts with multiple segments must be updated via --file.

Menstrual Cycle

gc menstrual --date today
gc menstrual calendar --start 2025-01-01 --end 2025-03-01
gc menstrual pregnancy

Building from Source

Build a standalone macOS ARM64 binary:

make package

The binary will be at dist/gc.

License

MIT