CLI - Garu

Visão Geral

A CLI da Garu permite criar cobranças, vender em carnê (boleto parcelado), gerenciar reembolsos 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

curl -fsSL https://raw.githubusercontent.com/Garu-Pagamentos/garu-cli/main/install.sh | bash

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 <uuid>`	Consulta detalhes de uma cobrança
`garu charges refund <uuid>`	Reembolsa uma cobrança

Clientes

A partir da CLI 0.10.0 você gerencia clientes sem sair do terminal.

Comando	Descrição
`garu customers create`	Cadastra um cliente para o seller atual
`garu customers list`	Lista clientes, com busca e filtro `--status overdue`
`garu customers get <uuid>`	Consulta um cliente
`garu customers update <uuid>`	Atualiza campos do cliente (parcial)
`garu customers set-billing-email <uuid>`	Define o e-mail de cobrança fixo
`garu customers clear-billing-email <uuid>`	Limpa o e-mail de cobrança fixo
`garu customers delete <uuid>`	Desvincula o cliente do seller atual

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

Carnê (Boleto Parcelado)

A partir da CLI 0.9.0, venda em carnê — um produto dividido em 2 a 12 boletos mensais — direto do terminal.

Comando	Descrição
`garu installment-plans create`	Vende um produto em carnê para um cliente
`garu installment-plans list`	Lista carnês, com filtros de status, cliente e produto
`garu installment-plans get <uuid>`	Consulta um carnê e todas as suas parcelas
`garu installment-plans reissue <uuid> <n>`	Emite segunda via de uma parcela vencida
`garu installment-plans postpone <uuid> <n>`	Adia o vencimento de uma parcela
`garu installment-plans mark-paid <uuid> <n>`	Marca uma parcela como paga manualmente
`garu installment-plans cancel <uuid>`	Cancela o carnê e os boletos ainda em aberto
`garu installment-plans request-refund <uuid>`	Solicita o estorno de um carnê

Reembolsos

A CLI não reverte boleto nem Pix automaticamente — esse fluxo é registrar o pedido, você devolver o valor por fora, e depois confirmar. Cartão continua com estorno automático via garu charges refund.

Comando	Descrição
`garu refund-requests list`	Lista pedidos de estorno (carnê e Pix/boleto)
`garu refund-requests get <uuid>`	Consulta um pedido de estorno
`garu refund-requests confirm <uuid>`	Confirma que o valor já foi devolvido (chame depois de devolver)
`garu refund-requests reject <uuid>`	Recusa o pedido — o carnê ou a cobrança seguem intactos

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 \
  --type pix \
  --product-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --customer-name "João Silva" \
  --customer-email joao@email.com \
  --customer-document 12345678900 \
  --customer-phone 11987654321

Listar cobranças pagas

garu charges list --status paid

Cadastrar um cliente

garu customers create \
  --name "Maria Silva" --email maria@exemplo.com.br \
  --document 12345678909 --phone 11987654321 \
  --person-type fisica

Vender um produto em carnê

garu installment-plans create \
  --product-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --customer-id 4821 \
  --installments 12

Confirmar um reembolso após devolver o valor

garu refund-requests confirm a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --note "Pix devolvido em 14/08, e2e E12345678"

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 Reais (ex: `49.90` = 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

--value (produtos) é informado em Reais — o mesmo que o dashboard e a API REST (ex: 49.90 = R

49,90). Não use centavos: `--value 4990` cadastraria um produto de R

4.990,00.

Criar um produto simples

garu products create \
  --name "E-book de Marketing" \
  --value 47.00 \
  --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 49.90 \
  --pix --credit-card --pix-automatic \
  --subscription --subscription-type monthly

garu products update 456 --pix-automatic

garu products update 456 --no-pix-automatic

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 49.90 \
  --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.

Tanto --amount (em scheduled-charges) quanto --value (em products) são informados em Reais (49.90). Mesma unidade nos dois comandos.

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

​Carnê (Boleto Parcelado)

​Reembolsos

​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

​Vender um produto em carnê

​Confirmar um reembolso após devolver o valor

​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

Carnê (Boleto Parcelado)

Reembolsos

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

Vender um produto em carnê

Confirmar um reembolso após devolver o valor

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