CLI - Garu

Visão Geral

A CLI da Garu permite criar cobranças, gerenciar clientes e diagnosticar sua integração sem sair do terminal. Ideal para automações, scripts e agentes de IA que preferem trabalhar com comandos.

Pré-requisito: Você precisa de uma chave de API. Veja como obter em Autenticação.

Instalação

npm install -g @garuhq/cli

Verifique a instalação:

garu --version

Autenticação

Existem três formas de autenticar:

Login interativo
Variável de ambiente
Flag inline

export GARU_API_KEY=YOUR_API_KEY

A CLI usa automaticamente a variável GARU_API_KEY se presente.

garu charges list --api-key YOUR_API_KEY

Útil para scripts e CI/CD. A flag tem prioridade sobre as outras formas.

Para encerrar a sessão:

garu logout

Referência de Comandos

Autenticação

Comando	Descrição
`garu login`	Autentica via navegador
`garu logout`	Remove credenciais salvas

Cobranças

Comando	Descrição
`garu charges create`	Cria uma nova cobrança
`garu charges list`	Lista cobranças
`garu charges get <id>`	Consulta detalhes de uma cobrança
`garu charges refund <id>`	Reembolsa uma cobrança

Clientes

Comando	Descrição
`garu customers create`	Cadastra um novo cliente
`garu customers list`	Lista clientes
`garu customers get <id>`	Consulta detalhes de um cliente
`garu customers update <id>`	Atualiza dados de um cliente
`garu customers delete <id>`	Remove um cliente

Produtos

A partir da CLI 0.7.0 você cria e atualiza produtos sem sair do terminal — incluindo o Pix Automático.

Comando	Descrição
`garu products create`	Cria um novo produto
`garu products update <id>`	Atualiza um produto existente

Cobranças Agendadas

Comando	Descrição
`garu scheduled-charges create`	Agenda uma cobrança (avulsa ou recorrente)

Diagnóstico

Comando	Descrição
`garu doctor`	Verifica configuração e conectividade

Flags Globais

Flag	Descrição
`--api-key`	Chave de API inline (prioridade sobre env e login)
`--json`	Saída em JSON (ideal para scripts e agentes de IA)

Modos de Saída

A CLI detecta automaticamente se está rodando em um terminal interativo (TTY) ou em um script:

Interativo (TTY)
JSON (--json)

Saída formatada com cores e tabelas:

garu charges list

┌────────┬──────────────────┬──────────┬─────────┐
│ ID     │ Cliente          │ Valor    │ Status  │
├────────┼──────────────────┼──────────┼─────────┤
│ 12345  │ joao@email.com   │ R$ 49,90 │ paid    │
│ 12346  │ maria@email.com  │ R$ 99,00 │ pending │
└────────┴──────────────────┴──────────┴─────────┘

Saída em JSON para scripts e automações:

garu charges list --json

[
  {
    "id": 12345,
    "customer": "joao@email.com",
    "amount": 4990,
    "status": "paid"
  }
]

Use --json quando estiver integrando a CLI com outros scripts ou quando um agente de IA estiver usando a CLI.

Diagnóstico com `garu doctor`

O comando garu doctor verifica se tudo está configurado corretamente:

garu doctor

✔ Versão da CLI: 1.0.0
✔ Node.js: v20.11.0
✔ Credenciais: configuradas
✔ Conectividade: API acessível
✔ Chave de API: válida (sk_test_***abc)

O que ele verifica:

Versão da CLI e do Node.js
Se as credenciais estão configuradas
Se a API está acessível
Se a chave de API é válida

Exemplos de Uso

Criar uma cobrança PIX

garu charges create \
  --amount 4990 \
  --method pix \
  --customer-email joao@email.com

Listar cobranças pagas

garu charges list --status paid

Cadastrar um cliente

garu customers create \
  --name "Maria Silva" \
  --email maria@email.com \
  --document 12345678900

Produtos pela CLI

Com garu products create e garu products update <id> você cria e ajusta produtos direto no terminal — perfeito para versionar seu catálogo em scripts ou deixar um agente de IA cuidar disso.

Flags disponíveis

As mesmas flags valem para create e update:

Flag	Descrição
`--name`	Nome do produto (exibido ao cliente)
`--value`	Preço em centavos (ex: `4990` = R$ 49,90)
`--description`	Descrição do produto
`--image`	URL da imagem do produto
`--tags`	Tags para categorização (separadas por vírgula)
`--pix`	Habilita pagamento via PIX
`--boleto`	Habilita boleto bancário
`--credit-card`	Habilita cartão de crédito
`--pix-automatic`	Liga o Pix Automático (débito recorrente)
`--no-pix-automatic`	Desliga o Pix Automático (padrão)
`--installments`	Parcelas máximas no cartão (1–12)
`--subscription`	Marca o produto como assinatura
`--subscription-type`	Tipo da assinatura (`monthly`, `yearly`, etc.)
`--unit-label`	Rótulo da unidade (ex: “licença”, “assento”)
`--return-url`	URL de redirecionamento após o pagamento
`--return-url-button-text`	Texto do botão exibido na tela de sucesso

Na CLI, --value é informado em centavos (igual a garu charges create --amount). No dashboard e na API REST o preço é em Reais — não misture as unidades.

Criar um produto simples

garu products create \
  --name "E-book de Marketing" \
  --value 4700 \
  --pix --credit-card --boleto \
  --installments 3

Ligar e desligar o Pix Automático

O par --pix-automatic / --no-pix-automatic controla o débito recorrente do Pix. Ele vem desligado por padrão e só faz sentido em produtos de assinatura.

garu products create \
  --name "Plano Mensal" \
  --value 4990 \
  --pix --credit-card --pix-automatic \
  --subscription --subscription-type monthly

O que é o Pix Automático

Entenda como o cliente autoriza uma vez no banco e os próximos ciclos caem sozinhos.

Cobranças agendadas com Pix Automático

garu scheduled-charges create agenda uma cobrança para um cliente já cadastrado. A partir da CLI 0.7.0, o --methods aceita o valor pix_automatic para débito recorrente.

--methods pix_automatic exige --type recurring e um --product-id, e o produto precisa ter sido criado com --pix-automatic. Sem isso, a cobrança volta 400.

Receita completa: produto + cobrança recorrente

Crie o produto com Pix Automático ligado e depois agende a série recorrente apontando para ele:

Crie o produto com --pix-automatic

garu products create \
  --name "Plano Mensal" \
  --value 4990 \
  --pix --credit-card --pix-automatic \
  --subscription --subscription-type monthly

Guarde o id retornado — você vai usá-lo no --product-id do próximo passo.

Agende a cobrança recorrente com --methods pix_automatic

garu scheduled-charges create --customer-id 42 --product-id 456 \
  --amount 49.90 --type recurring --due-date 2026-06-15 \
  --methods pix_automatic --recurrence-interval monthly

O cliente autoriza a recorrência uma vez no app do banco e os ciclos seguintes são debitados sozinhos.

Aqui --amount (em scheduled-charges) é informado em Reais (49.90), enquanto --value (em products) é em centavos (4990). São o mesmo preço, em unidades diferentes.

Pix Automático (visão geral)

Como o cliente autoriza, os próximos ciclos e o modelo de falha.

Como integrar Pix Automático

Receita de ponta a ponta via API, SDK e MCP.

Recursos

Repositório GitHub

Código-fonte e documentação técnica

Pacote npm

@garuhq/cli no npm

Próximos Passos

MCP Server

Conecte agentes de IA à API Garu

Node SDK

Use a SDK para integrar no seu código

​Visão Geral

​Instalação

​Autenticação

​Referência de Comandos

​Autenticação

​Cobranças

​Clientes

​Produtos

​Cobranças Agendadas

​Diagnóstico

​Flags Globais

​Modos de Saída

​Diagnóstico com garu doctor

​Exemplos de Uso

​Criar uma cobrança PIX

​Listar cobranças pagas

​Cadastrar um cliente

​Produtos pela CLI

​Flags disponíveis

​Criar um produto simples

​Ligar e desligar o Pix Automático

O que é o Pix Automático

​Cobranças agendadas com Pix Automático

​Receita completa: produto + cobrança recorrente

Pix Automático (visão geral)

Como integrar Pix Automático

​Recursos

Repositório GitHub

Pacote npm

​Próximos Passos

MCP Server

Node SDK

Visão Geral

Instalação

Autenticação

Referência de Comandos

Autenticação

Cobranças

Clientes

Produtos

Cobranças Agendadas

Diagnóstico

Flags Globais

Modos de Saída

Diagnóstico com `garu doctor`

Exemplos de Uso

Criar uma cobrança PIX

Listar cobranças pagas

Cadastrar um cliente

Produtos pela CLI

Flags disponíveis

Criar um produto simples

Ligar e desligar o Pix Automático

Cobranças agendadas com Pix Automático

Receita completa: produto + cobrança recorrente

Recursos

Próximos Passos