Garmin Connect CLI

Garmin Connect from your terminal. Pipe it, script it, automate it.

Exploring CLI tools as skills for AI agents. Background below.

Features

• All your Garmin data — activities, stats, sleep, heart rate, stress, body battery
• Script and automate — composable with jq, pipes, xargs, and standard Unix tools
• AI agent ready — install the skill for Claude, Cursor, and other assistants
• Flexible output — JSON for scripts, CSV for spreadsheets, tables for humans

Installation

Quick Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/eddmann/garmin-connect-cli/main/install.sh | sh

Downloads the pre-built binary for your platform (macOS/Linux) to ~/.local/bin.

Homebrew

brew install eddmann/tap/garmin-connect-cli

Using uv

Requires Python 3.12+ and uv.

uvx garmin-connect-cli --help
uv tool install garmin-connect-cli

The PyPI package is garmin-connect-cli; the CLI command remains garmin-connect.

From Source

git clone https://github.com/eddmann/garmin-connect-cli
cd garmin-connect-cli
make deps
uv run garmin-connect --help

Quick Start

# Authenticate with Garmin Connect
garmin-connect auth login

# List recent activities
garmin-connect activities list --limit 10

# Get today's stats
garmin-connect athlete stats

# Get sleep data
garmin-connect health sleep

# Get aggregated context for LLMs
garmin-connect context

Command Reference

Global Options

Authentication

Tokens are stored in ~/.config/garmin-connect-cli/tokens/ and remain valid for approximately one year. MFA is supported.

garmin-connect auth login                    # Interactive login
garmin-connect auth login --email EMAIL      # With credentials
garmin-connect auth status                   # Check status
garmin-connect auth logout                   # Clear tokens
garmin-connect auth login --profile work     # Named profile

Commands

Use garmin-connect <command> --help for full details.

Configuration

CLI preferences are stored in ~/.config/garmin-connect-cli/config.toml:

[defaults]
format = "json"
limit = 30

[profiles.work]
email = "work@example.com"

Authentication tokens are managed by python-garminconnect and stored in ~/.config/garmin-connect-cli/tokens/.

Environment Variables

Composability

# Filter runs over 10km (distance in meters)
garmin-connect activities list --type running | jq '.[] | select(.distance > 10000)'

# Total running distance in km
garmin-connect activities list --type running | jq '[.[].distance] | add / 1000'

# Get recent activities with key metrics
garmin-connect activities list --limit 5 | jq '.[] | {name: .activityName, km: (.distance/1000), mins: (.duration/60)}'

AI Agent Integration

This CLI is available as an Agent Skill — it works with Claude Code, Cursor, and other compatible AI agents. See SKILL.md for the skill definition.

Install Agent Skill

curl -fsSL https://raw.githubusercontent.com/eddmann/garmin-connect-cli/main/install-skill.sh | sh

Installs the skill to ~/.claude/skills/garmin-connect/ and ~/.cursor/skills/garmin-connect/. Agents will auto-detect when you ask about Garmin/fitness data.

Development

git clone https://github.com/eddmann/garmin-connect-cli
cd garmin-connect-cli
make deps                             # Install dependencies
make test                             # Run tests
make run CMD="activities list --limit 5"  # Run command

Background

I recently built garmin-connect-mcp, an MCP server for Garmin Connect. This got me thinking about alternative approaches to giving AI agents capabilities.

There's been a lot of discussion around the heavyweight nature of MCP. An alternative approach is to give agents discoverable skills via well-documented CLI tooling. Give an LLM a terminal and let it use composable CLI tools to build up functionality and solve problems — the Unix philosophy applied to AI agents.

This project is an exploration of Claude Code Skills and the emerging Agent Skills standard for AI-tool interoperability. The goal was to build a CLI that works seamlessly as both:

1. A traditional Unix tool — composable, pipe-friendly, machine-readable
2. An AI agent skill — structured output, comprehensive documentation, predictable behavior

Going forward, another approach worth exploring is going one step further than CLI and providing a code library that agents can import and use directly.

License

MIT

Credits

Built on top of python-garminconnect by cyberjunky.