gccli: A Command-Line and Agent Query Guide for Garmin Connect Data

Who it's for

gccli is a command-line tool for Garmin Connect, officially positioned as a “fast, script-friendly CLI” with access to activities, health data, body composition, workouts, courses, devices, gear, goals, and badges. It suits people who:

• Want to query their Garmin data directly in the terminal and feed the results into scripts: the official project provides two parseable output modes, JSON and plain/TSV, explicitly aimed at scripting and automation.
• Work inside agent clients and want an agent to fetch data on their behalf: gccli ships a ready-to-use agent skill, which the official description targets at AI agent clients such as Claude Code, Codex, Hermes, and OpenClaw.
• Need to fold workout and health data into automated workflows.

Cases where it does not fit, or where you should confirm first:

• It cannot be used without a Garmin Connect account: authentication goes through Garmin SSO, which is a hard prerequisite.
• Environments where you do not want Homebrew: the only copy-paste install command given by the official documentation is Homebrew; building from source requires Go 1.26 or later, and complete build steps are not provided in the official repository.
• The client list is officially illustrative rather than exhaustive; compatibility beyond that list is not stated, so rely on the repository documentation before integrating.

Your first try in 3 minutes

There is exactly one recommended main path: install with Homebrew, complete Garmin SSO authentication, then have your agent run a query.

Prerequisites: you already have a Garmin Connect account; Homebrew is installed on your machine; and you know that the first authentication writes your credentials to the system keyring (side effects covered under “Boundaries”).

Step 1, install:

brew install bpauli/tap/gccli

Step 2, authenticate. Authentication runs through Garmin SSO, and credentials are saved to the system keyring. One detail you must know beforehand: the official documentation states clearly that gccli encrypts every token file with a fixed passphrase embedded in the source code — that is, the fallback token file used when the keyring is unavailable, and that encryption passphrase is not a secret unique to you. Decide for yourself, before the first authentication, whether you accept this storage method. The official documentation does not give a specific login command; after installing, follow gccli's built-in help to complete the login.

Step 3, connect your agent to the skill. The agent skill bundled with gccli lives at skills/gccli/SKILL.md and is described by the official project as ready to use; the steps for attaching it to your specific client are not given by the official documentation, so follow the documentation of each client.

Step 4, issue a query task. Tell the agent directly: “Pull up my recent running activities and this week's body composition data.” Tasks like this fall within the officially listed data-access capabilities; whether the query process writes local files is not explained by the official documentation and remains unconfirmed. The only confirmed write side effect is token storage (see “Boundaries”) — do not assume it is read-only and never writes.

Step 5, check the success signal: the response should be parseable output in JSON or plain/TSV mode, ready to paste or hand to a script; once you see structured output, the path works.

Use cases

Case 1: Summarizing workout and body data.

• Scenario: you want to see all recent workout records and weight changes at once, without paging through the web client record by record.
• Prompt: in an agent client connected to gccli, say “List my recent workouts and body composition records.”
• Workflow: the agent uses gccli to access activities and body composition, the two officially confirmed data categories.
• Expected result: parseable JSON or plain/TSV output that you can paste into a spreadsheet or hand to a script; the official documentation does not list the fields of a single record, so the actual response is authoritative.

Case 2: Folding Garmin data into automation scripts.

• Scenario: you want a weekly summary of devices, gear, goals, and badges to build your own training archive.
• Prompt: call gccli from your existing scripts or scheduled agent tasks and pass the output to the next stage.
• Workflow: lean on the official “script-friendly” positioning and the JSON and plain/TSV output modes to plug into existing flows.
• Expected result: machine-readable output feeds reliably into the next step; the exact list of subcommands and parameters is not spelled out verbatim by the official documentation, so check gccli's help output and the repository before you start.

Boundaries

• Network and account: data comes from the Garmin Connect cloud; authentication and every query require an internet connection and your Garmin account. Offline capability is not mentioned officially and remains unconfirmed.
• Credentials and write side effects: the first authentication runs through Garmin SSO and writes credentials to the system keyring; the fallback token file used when the keyring is unavailable is encrypted with a fixed passphrase embedded in the source code. Beyond token storage, whether queries write other files is not explained officially and remains unconfirmed.
• Runtime: building from source requires Go 1.26 or later; the recommended main path installs via Homebrew and involves no local build. Other runtime requirements are not documented.
• Client prerequisite: the bundled agent skill targets AI agent clients such as Claude Code, Codex, Hermes, and OpenClaw; compatibility beyond that list, and whether setup steps match across clients, is not individually documented — check each client's documentation before integrating.
• Explicit limits: rate limits, export caps, and terms-of-service constraints are not mentioned officially; consult the official repository before bulk or high-frequency use.