gccli: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Read AGENTS.md before you verify or merge a PR, and before you change command output.

Project Overview

gccli is a Go CLI (gccli) for interacting with the Garmin Connect API. It covers authentication, activities, workouts, health data, body composition, devices, gear, goals, badges, challenges, profile, hydration, training, and wellness data. Module: github.com/bpauli/gccli.

Build & Quality Commands

make build              # Build binary to ./bin/gccli
make run -- <args>      # Build and run with arguments
make fmt                # Format code (goimports + gofumpt)
make lint               # Run golangci-lint
make test               # Unit tests with race detector
make test-e2e           # E2E tests (requires .env with GARMIN_EMAIL/GARMIN_PASSWORD)
make ci                 # Full CI gate: fmt-check + lint + test
make tools              # Install dev tools to .tools/

Run a single test:

go test -run TestFuncName ./internal/pkg/...

Run E2E tests selectively:

go test -tags=e2e -run TestName -v -count=1 ./internal/e2e/...

All three checks (make fmt, make lint, make test) must pass before committing.

Architecture

Layered structure: cmd/gccli/main.go → internal/cmd/ (CLI commands) → internal/garminapi/ (API client) → internal/garminauth/ (authentication).

Key packages

• internal/cmd/ — Kong-based CLI commands. Each command is a struct with Run(g *Globals) error. Globals holds context, UI, and account info. resolveClient() loads tokens from the OS keyring and creates an API client.
• internal/garminapi/ - HTTP client for Garmin Connect. Returns json.RawMessage from API calls (no Go structs for every endpoint). All API client requests and the exercise catalog fetch go through RetryTransport (429 retried for every method within Retry-After, 5xx retried only for GET and HEAD with backoff, because writes may already be saved) over a stall watch per attempt (stallTransport: a request fails with StallError when no data moves for 60 s; a transfer that keeps moving has no time limit) over a clone of http.DefaultTransport. Auto-refreshes OAuth2 tokens on 401.
• internal/garminauth/ — Garmin SSO authentication. Supports browser-based SSO (local callback server) and headless email/password login with MFA. OAuth1 → OAuth2 exchange flow.
• internal/secrets/ — OS keyring storage (macOS Keychain, Linux Secret Service, file fallback). Tokens keyed by gccli:token:{email}.
• internal/config/ — Config file paths and env var overrides.
• internal/outfmt/ — Output formatting (JSON/Table/Plain). Mode passed via context.
• internal/ui/ - Terminal UI (colors, prompts) via termenv. Passed to commands in Globals.UI.
• internal/errfmt/ — Maps typed errors to user-friendly messages.
• internal/fit/ — FIT file binary encoding for weight data uploads.
• internal/testutil/ - Test helpers. TempConfigDir points the config directory at a temp directory.
• internal/e2e/ — End-to-end tests (build tag e2e) against real Garmin Connect API.