gccli: guia para consultar dados do Garmin Connect pela linha de comando e com um agente

Para quem é

gccli é uma ferramenta de linha de comando para o Garmin Connect, posicionada oficialmente como uma “CLI rápida e amigável para scripts”, com acesso a atividades, dados de saúde, composição corporal, treinos, percursos, dispositivos, equipamentos, metas e medalhas. Serve para:

• Quem quer consultar os próprios dados do Garmin direto no terminal e levar os resultados para scripts: o projeto oficial oferece dois modos de saída processável, JSON e plain/TSV, pensados explicitamente para scripts e automação.
• Quem trabalha dentro de um cliente agente e quer delegar ao agente a consulta de dados: o gccli traz um agent skill pronto para uso que, segundo a descrição oficial, é voltado a clientes de agentes de IA como Claude Code, Codex, Hermes e OpenClaw.
• Desenvolvedores que precisam integrar treinos e dados de saúde a fluxos automatizados.

Casos em que não serve, ou em que vale confirmar antes:

• Sem conta no Garmin Connect não dá para usar: a autenticação é feita via Garmin SSO; é pré-requisito obrigatório.
• Ambientes onde você não quer Homebrew: o único comando de instalação copiável que a documentação oficial fornece é o do Homebrew; compilar do código fonte exige Go 1.26 ou superior, e os passos completos de compilação não aparecem no repositório oficial.
• A lista de clientes é um exemplo oficial, não exaustiva; não se informa se há compatibilidade fora dela — consulte a documentação do repositório antes de integrar.

Primeira tentativa em 3 minutos

O caminho principal recomendado é um só: instalar com Homebrew, concluir a autenticação via Garmin SSO e pedir ao agente que execute uma consulta.

Pré-requisitos: você já tem conta no Garmin Connect; o Homebrew está instalado na sua máquina; e você sabe que a primeira autenticação grava as credenciais no keyring do sistema (efeitos colaterais em “Limites de uso”).

Passo 1, instalar:

brew install bpauli/tap/gccli

Passo 2, autenticar. A autenticação é feita via Garmin SSO e as credenciais ficam guardadas no keyring do sistema. Um detalhe que você precisa saber antes: a documentação oficial afirma claramente que o gccli criptografa cada arquivo de tokens com uma frase secreta fixa embutida no código fonte; ou seja, o arquivo de tokens de reserva usado quando o keyring não está disponível, e essa frase não é um segredo exclusivamente seu. Decida você, antes da primeira autenticação, se aceita essa forma de armazenamento. A documentação oficial não traz um comando de login específico; depois de instalar, siga a ajuda integrada do gccli.

Passo 3, conectar o agente à skill. O agent skill que acompanha o gccli fica em skills/gccli/SKILL.md e, segundo o projeto oficial, está pronto para uso; os passos para conectá-lo ao seu cliente não constam da documentação oficial — siga a documentação de cada cliente.

Passo 4, disparar uma tarefa de consulta. Diga diretamente ao agente: “Traga minhas últimas atividades de corrida e os dados de composição corporal desta semana”. Esse tipo de tarefa está dentro das capacidades de acesso a dados listadas oficialmente; se o processo de consulta grava arquivos locais não está explicado oficialmente e segue sem confirmação. O único efeito de gravação confirmado é o armazenamento de tokens (ver “Limites de uso”): não presuma que é somente leitura.

Passo 5, conferir o sinal de sucesso: a resposta deve ser uma saída processável em modo JSON ou plain/TSV, pronta para colar ou entregar a um script; ao ver saída estruturada, o caminho está funcionando.

Casos de uso

Caso 1: consolidar treinos e dados corporais.

• Cenário: ver de uma vez os últimos treinos e a evolução do peso, sem folhear registro por registro na versão web.
• Disparo: em um cliente agente conectado ao gccli, diga “Liste meus últimos treinos e registros de composição corporal”.
• Fluxo: o agente acessa via gccli atividades e composição corporal, duas categorias de dados confirmadas oficialmente.
• Resultado esperável: uma saída JSON ou plain/TSV processável, para colar em uma planilha ou entregar a um script; a lista de campos por registro não está documentada oficialmente — vale a resposta real.

Caso 2: integrar os dados do Garmin a scripts de automação.

• Cenário: resumir semanalmente dispositivos, equipamentos, metas e medalhas para montar seu próprio arquivo de treinos.
• Disparo: chame o gccli dos seus scripts existentes ou de tarefas de agente agendadas e passe a saída para a etapa seguinte.
• Fluxo: use o posicionamento oficial “amigável para scripts” e os modos de saída JSON e plain/TSV para se conectar aos fluxos atuais.
• Resultado esperável: uma saída legível por máquina que entra com estabilidade na etapa seguinte; a lista exata de subcomandos e parâmetros não é dada literalmente na documentação oficial — consulte a ajuda do gccli e o repositório antes de começar.

Limites de uso

• Rede e conta: os dados vêm da nuvem do Garmin Connect; a autenticação e cada consulta exigem conexão à internet e a sua conta Garmin. Não há menção oficial a capacidade offline, e isso segue sem confirmação.
• Credenciais e efeitos de gravação: a primeira autenticação é via Garmin SSO e grava as credenciais no keyring do sistema; o arquivo de tokens de reserva, usado quando o keyring não está disponível, é criptografado com uma frase secreta fixa embutida no código fonte. Além do armazenamento de tokens, não se explica oficialmente se as consultas gravam outros arquivos, e isso segue sem confirmação.
• Ambiente de execução: compilar do código fonte exige Go 1.26 ou superior; o caminho principal recomendado instala via Homebrew, sem compilação local. Os demais requisitos de execução não estão documentados.
• Pré-requisito de cliente: o agent skill embutido é voltado a clientes de agentes de IA como Claude Code, Codex, Hermes e OpenClaw; compatibilidade fora dessa lista e uniformidade dos passos de integração não são detalhadas oficialmente — consulte a documentação de cada cliente antes de integrar.
• Limites explícitos: limites de taxa, tetos de exportação e restrições dos termos de serviço não são mencionados oficialmente; consulte o repositório oficial antes de uso em massa ou de alta frequência.