AbacatePay CLI · open source

A AbacatePay no seu terminal

Login pelo navegador, os webhooks do modo de teste chegando no seu localhost com a assinatura da produção e o Pix pago com um comando. Um binário em Go, sem dependências.

  • Webhooks de teste no localhost
  • Assinatura igual à da produção
  • Pix simulado sem abrir o banco
  • macOS, Linux e Windows
Instalar a CLIVer os comandos ↓

Roda no seu sistema, no seu terminal e no seu CI.

  • macOS
  • Linux
  • Ubuntu
  • Debian
  • Go
  • curl
  • Bash
  • Zsh
  • fish
  • tmux
  • iTerm2
  • Warp
  • Ghostty
  • Docker
  • GitHub Actions

Do login ao webhook 200 em três comandos

O ciclo inteiro de um pagamento de teste, na sua máquina: sem deploy, sem túnel e sem abrir o app do banco.

  1. 1

    Entre pelo navegador

    A CLI abre a tela de aprovação na sua conta e espera você aprovar. A sessão vai pro keyring do sistema, nunca pra um arquivo de texto.

  2. 2

    Ligue o listen

    Os webhooks do modo de teste chegam por uma conexão de saída e vão pro seu servidor como POST, assinados como na produção. Sem túnel e sem porta aberta.

  3. 3

    Pague o Pix de teste

    Crie o Pix com a chave de teste, pela API ou pelo SDK, e simule o pagamento. O transparent.completed chega no listen e no seu endpoint.

No terminal do listen, o evento aparece com o status que o seu app devolveu:--> transparent.completed e logo depois<-- [200].

Instalação

Um binário, um comando

A CLI é escrita em Go e compilada sem dependências: não precisa de Node, Python nem Docker na máquina.

  • O script baixa o último release e confere o SHA-256 no checksums.txt antes de instalar.
  • Vai pra /usr/local/bin, ou pra pasta que você passar em ABACATEPAY_INSTALL_DIR.
  • abacatepay upgrade troca o binário pela versão nova, sem reinstalar.

Em cada release do GitHub

  • macOSdarwin_arm64darwin_amd64Apple Silicon e Intel
  • Linuxlinux_amd64linux_arm64x86_64 e ARM64
  • Windowswindows_amd64windows_arm64.zip, x64 e ARM64
Como instalar a CLI
terminal
curl -fsSL https://abacatepay.com/install.sh | sh

# Sem sudo, numa pasta sua
curl -fsSL https://abacatepay.com/install.sh | ABACATEPAY_INSTALL_DIR="$HOME/.local/bin" sh

abacatepay --version
terminal
go install github.com/AbacatePay/abacatepay-cli/cmd/abacatepay@latest

# O binário vai pro GOBIN (por padrão, ~/go/bin), que precisa estar no PATH
abacatepay --version
PowerShell
# x64; no ARM, troque por abacatepay_windows_arm64.zip
Invoke-WebRequest https://github.com/AbacatePay/abacatepay-cli/releases/latest/download/abacatepay_windows_amd64.zip -OutFile abacatepay.zip
Expand-Archive abacatepay.zip -DestinationPath "$HOME\abacatepay"

& "$HOME\abacatepay\abacatepay.exe" --version
terminal
# Linux ARM64, por exemplo: troque pelo seu sistema e arquitetura
curl -fsSLO https://github.com/AbacatePay/abacatepay-cli/releases/latest/download/abacatepay_linux_arm64.tar.gz
tar -xzf abacatepay_linux_arm64.tar.gz abacatepay
sudo mv abacatepay /usr/local/bin/

Sem Homebrew por enquanto: o script já pega o último release direto do GitHub. No Windows, ponha a pasta no PATH pra chamar só abacatepay.

Por dentro do listen

Do pagamento de teste ao seu endpoint

A CLI abre uma conexão de saída com a AbacatePay e repassa cada evento pro endereço do--forward-to, do jeito que a produção entrega. Nada da sua máquina fica exposto na internet.

  1. Pagamento de testepayments simulate, o seu app ou o painel
  2. AbacatePaydispara o webhook do modo de teste
  3. abacatepay listenna sua máquina, numa conexão de saída
  4. Seu servidorrecebe o POST no endpoint de sempre

O que chega no seu servidor

POST /webhooks/abacatepay HTTP/1.1
Host: localhost:3000
Content-Type: application/json
X-Webhook-Signature: <HMAC-SHA256 do corpo, em base64>

{
  "id": "log_Qw8eR2tY4uI6oP1aS3dF5gH7",
  "event": "transparent.completed",
  "apiVersion": 2,
  "devMode": true,
  "data": {
    "transparent": { "id": "pix_char_mXq2Lk7vB9nR4sT8", "status": "PAID", … },
    "customer": { … },
    "payerInformation": { … }
  }
}

Destino: http://localhost:3000/webhooks/abacatepay, ou o que você passar no --forward-to.

  • Só o modo de testeEventos de produção nunca chegam na CLI, mesmo logada na mesma conta.
  • A assinatura da produçãoHMAC-SHA256 do corpo cru, em base64, com a chave pública da documentação. A verificação que você já escreveu passa igual.
  • Sem o secret da URLA CLI não põe o ?webhookSecret=. Se a sua rota exige, inclua no próprio --forward-to.
  • Uma entrega por eventoNa CLI não há retentativa: o status volta pro painel e o corpo da resposta vai pro log. Em produção, são até 7 tentativas.
  • Até 10 em paraleloOs encaminhamentos rodam ao mesmo tempo, até 10 por vez, sem um evento lento segurar os outros.
  • Reconecta sozinhaSe a conexão cair, a CLI tenta de novo com espera de 1 s a 15 s, por até 5 tentativas seguidas.

Os comandos, com as flags e a saída

A CLI é pequena de propósito: login, webhooks, simulação e atualização, alinhados com a API v2. Useabacatepay <comando> -h pra ver a ajuda no terminal.

Comando

abacatepay login

alias: signin
abacatepay login [--name <perfil>] [--key <chave>]

Sem flags, abre o navegador na tela de aprovação da sua conta e espera você aprovar, por até 10 minutos. Com --key, valida a chave de API direto, sem navegador. A credencial vai pro keyring do sistema e o perfil vira o ativo.

FlagO que fazPadrão
--nameNome do perfil onde a credencial fica salvadefault
--keyChave de API da AbacatePay; pula o navegador (CI, servidor sem tela)—
exemplo

$ abacatepay login

Opening browser: https://app.abacatepay.com/oauth/cli?id=cli_8Gk2Xq7vRm4Tz9Lp

🥑 Authenticated

Profile: default

User: Torra

Se o navegador não abrir, a CLI imprime o link: abra em qualquer navegador logado na conta.

abacatepay listen

abacatepay listen [--forward-to <url>]

Recebe os webhooks do modo de teste por uma conexão WebSocket e repassa cada um como POST pra sua URL, com Content-Type: application/json e o X-Webhook-Signature da produção. No terminal, abre um painel com a conexão e os eventos; fora dele, imprime uma linha por evento.

FlagO que fazPadrão
--forward-toURL que recebe os eventos (http:// ou https://)pergunta no terminal, sugerindo http://localhost:3000/webhooks/abacatepay
exemplo

$ abacatepay listen --forward-to http://localhost:3000/webhooks/abacatepay

🥑 abacatepay listen

● connected forwarding to http://localhost:3000/webhooks/abacatepay

14:32:07 --> transparent.completed [pix_char_mXq2Lk7vB9nR4sT8]

14:32:07 <-- [200] transparent.completed

↑/k up • ↓/j down • G latest • q quit

Status fora de 2xx sai em vermelho. Com -v, o painel mostra o JSON de cada evento.

abacatepay payments simulate

alias: payments simulate-payment
abacatepay payments simulate <charge-id>

Paga uma cobrança transparente criada com a chave de teste. Por baixo, chama POST /v2/transparents/simulate-payment?id=<charge-id>, e os webhooks da conta disparam como num pagamento de verdade, inclusive pro listen.

exemplo

$ abacatepay payments simulate pix_char_mXq2Lk7vB9nR4sT8

🥑 Payment Simulated

ID: pix_char_mXq2Lk7vB9nR4sT8

Status: PAID

DevMode: true

A CLI não cria cobrança: crie o Pix pela API ou pelo SDK, com a mesma chave de teste, e passe o id.

abacatepay logout

alias: signout
abacatepay logout

Apaga a credencial do perfil ativo do keyring. Se houver outro perfil salvo, ele passa a ser o ativo; se não, os outros comandos pedem um login novo.

exemplo

$ abacatepay logout

🥑 Signed out successfully

Profile: default

abacatepay upgrade

abacatepay upgrade

Confere o último release no GitHub e, se houver versão nova, troca o binário atual por ela. Instalada numa pasta do sistema, como /usr/local/bin, pode pedir sudo.

exemplo

$ abacatepay upgrade

🥑 Already up to date

Version: 0.2.1

Instalou com go install? Rodar o mesmo go install de novo também atualiza.

Flags globais

abacatepay [comando] [-v] [-h] [--version]

O ambiente (teste ou produção) vem da chave, não de uma flag: a antiga --local (-l) não faz mais nada. A ajuda de qualquer comando sai com -h.

FlagO que fazPadrão
--verbose, -vLog detalhado; no simulate, mostra a requisição e a resposta da API; no listen, o JSON de cada eventofalse
--versionMostra a versão instalada—
--help, -hAjuda do comando—
exemplo

$ abacatepay --version

abacatepay version 0.2.1

CI e scripts

No pipeline, sem ninguém pra clicar

A mesma CLI roda no CI: entra com a chave do modo de teste, paga o Pix de teste e para o job se algo falhar. Pra conferir o status da cobrança depois, consulte a API.

  • Login sem navegadorlogin --key valida a chave e salva no perfil. Sem keyring, vai pra um arquivo criptografado.
  • Código de saída0 no sucesso e 1 no erro. O texto é pra gente ler e pode mudar entre versões: não faça parse dele.
  • Sem animação fora do terminalEm pipe ou CI, uma linha por evento. No listen, o status vai pro stderr e os eventos pro stdout.
  • Logs em JSONabacatepay.log e transactions.log em ~/.abacatepay/logs, com rotação: 10 MB, 5 arquivos, 30 dias.
Exemplos de automação com a CLI
teste-de-pagamento.sh
set -e

# Chave do modo de teste guardada nos secrets do CI
abacatepay login --key "$ABACATEPAY_DEV_API_KEY"

# Cria um Pix de teste pela API e guarda o id
CHARGE_ID=$(curl -s https://api.abacatepay.com/v2/transparents/create \
  -H "Authorization: Bearer $ABACATEPAY_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"PIX","data":{"amount":10000}}' | jq -r .data.id)

# Paga. Se falhar, a CLI sai com código 1 e o job para aqui
abacatepay payments simulate "$CHARGE_ID"
terminal
# Encaminhamentos que o seu app recusou, com o corpo da resposta
jq 'select(.msg=="webhook_forward_error") | {event, status_code, response_body}' \
  ~/.abacatepay/logs/transactions.log

# O JSON do último evento recebido
jq -r 'select(.msg=="webhook_received") | .raw_message' \
  ~/.abacatepay/logs/transactions.log | tail -1 | jq

# Tempo médio de encaminhamento, em ms
jq 'select(.msg=="webhook_forwarded") | .duration_ms' \
  ~/.abacatepay/logs/transactions.log | jq -s 'add/length'
terminal
# Uma conta por perfil
abacatepay login --name loja-a --key "$CHAVE_LOJA_A"
abacatepay login --name loja-b --key "$CHAVE_LOJA_B"

# O perfil ativo é o do último login: pra voltar pra loja A
abacatepay login --name loja-a --key "$CHAVE_LOJA_A"
abacatepay listen --forward-to http://localhost:3000/webhooks/abacatepay

Pequena, aberta e feita pro teste

Uma ferramenta que faz poucas coisas e faz direito: o ciclo local de um pagamento, com o mesmo contrato da produção.

Cada evento, com a resposta do seu app

O painel do listen mostra o que chegou e o status que o seu servidor devolveu, em verde ou vermelho.

Código aberto

Apache 2.0 no GitHub. Leia como o listen assina os eventos, abra issue, mande PR.

Só o modo de teste

Eventos de produção nunca chegam na CLI, e o simulate só paga cobrança de teste.

Sessão no keyring

Keychain no macOS, Credential Manager no Windows e Secret Service no Linux.

Histórico local

Cada evento e cada resposta do seu app em JSON, no transactions.log.

1binário, sem dependências
Open source

Go compilado pra macOS, Linux e Windows, em amd64 e arm64. Baixou, rodou.

Mais pra quem constrói

A API, os SDKs, o MCP e o código aberto: o que mais tem pra quem integra a AbacatePay.

Dúvidas sobre a CLI

O que mais perguntam antes de rodar o primeiro abacatepay listen.

O que é a CLI da AbacatePay?

É a ferramenta de linha de comando oficial da AbacatePay, open source (Go, licença Apache 2.0). Ela entra na sua conta pelo navegador, recebe os webhooks do modo de teste e repassa pro seu servidor local, e simula o pagamento de um Pix de teste.

Como instalo a CLI?

No macOS e no Linux: curl -fsSL https://abacatepay.com/install.sh | sh. Com Go: go install github.com/AbacatePay/abacatepay-cli/cmd/abacatepay@latest. No Windows, baixe o .zip nos releases do GitHub. Confira com abacatepay --version e atualize com abacatepay upgrade.

Preciso de um túnel pra testar webhook no localhost?

Não. O abacatepay listen abre uma conexão de saída (WebSocket) com a AbacatePay e repassa cada evento como POST pro endereço do --forward-to. Nada da sua máquina fica exposto na internet.

Os eventos chegam assinados como na produção?

Sim. Cada evento vai com o header X-Webhook-Signature: o HMAC-SHA256 do corpo, em base64, com a mesma chave pública da documentação. O secret da URL (?webhookSecret=) a CLI não adiciona: se a sua rota exige, ponha no --forward-to.

A CLI recebe eventos de produção?

Não. Só eventos do modo de teste chegam no listen, e o payments simulate só paga cobrança criada com a chave de teste. Em produção, o pagamento acontece pelo fluxo real e o webhook vai pro endpoint cadastrado na conta.

E se o meu servidor responder erro?

O painel do listen mostra o status em vermelho e o ~/.abacatepay/logs/transactions.log guarda o corpo da resposta (webhook_forward_error). Na CLI, cada evento é enviado uma vez: corrija e simule outro pagamento. Em produção, a AbacatePay tenta de novo até 7 vezes em cerca de 18 horas.

Dá pra usar em CI?

Dá. Entre com abacatepay login --key e a chave de teste guardada nos secrets, e confie no código de saída (0 ou 1). Fora de um terminal, a CLI imprime linhas simples, sem animação. Ela não tem saída em JSON: pra conferir o status da cobrança, consulte a API.

Onde fica a minha credencial?

No keyring do sistema: Keychain no macOS, Credential Manager no Windows e Secret Service no Linux. Sem keyring (servidor sem interface ou container), num arquivo criptografado em ~/.abacatepay/keyring. O login pelo navegador vale por até 34 horas; depois, rode abacatepay login de novo.

A CLI cria cobranças?

Não. Ela cobre o ciclo local: login, webhooks e simulação. A cobrança de teste você cria pela API ou pelos SDKs, com a chave de teste, e passa o id pro payments simulate. Pra operar a conta pedindo em português, use o MCP.

Quanto custa?

Nada. A CLI e o modo de teste são grátis: você paga só as taxas das vendas de verdade, sem mensalidade.

Ler a documentação da CLI

A CLI e o modo de teste são grátis.

abacatepay login.
E pronto.

Crie a conta, instale a CLI e veja o primeiro webhook de teste chegar no seu localhost ainda hoje.

Criar conta grátis

Sem mensalidade. Aprovação não leva semanas.

Ilustração renascentista com anjos e um abacate numa concha