Primeiros passos com a CLI do BananaSplit: automatize o registro e a divisão de gastos com agentes de IA

A maioria dos gastos não precisa de uma decisão. Precisa de alguém para digitar. Um jantar com o time, a fatura mensal da hospedagem, o pedido da Amazon que você dividiu com quem mora com você: você já sabe quem pagou e como dividir. Digitar é que é a parte chata.

A CLI do BananaSplit passa essa parte para o seu agente de IA. Você diz o que aconteceu com as suas palavras e o agente registra no BananaSplit. Vá um passo além e o agente nem precisa que você peça: ele lê os recibos da sua caixa de entrada e adiciona tudo de forma agendada.

Este guia leva você do zero às duas coisas.

1. Instale a CLI do BananaSplit

No macOS ou Linux:

curl -fsSL https://github.com/teotti/banana-cli/releases/latest/download/install.sh | sh

No Windows (PowerShell):

irm https://github.com/teotti/banana-cli/releases/latest/download/install.ps1 | iex

Prefere um gerenciador de pacotes? npm install -g @bananasplitapp/cli ou bun install -g @bananasplitapp/cli também funcionam.

Depois faça login. Isso abre o navegador, e a CLI guarda o login de forma segura no seu computador:

banana login

Confira se está tudo certo:

banana doctor
banana balance

Se o banana balance mostrar o seu saldo, a CLI está pronta.

2. Abra o seu agente

Qualquer agente que consiga rodar comandos no terminal funciona: Claude Code, Codex, Cursor, Gemini CLI, OpenCode. Neste guia usamos o Claude Code.

claude

3. Peça para o seu agente instalar a skill banana

A skill ensina o seu agente como a CLI funciona: quais comandos existem, como as divisões fecham, como chamar grupos e amigos, e quando perguntar antes de mudar alguma coisa. Você não precisa procurar nada disso. É só pedir:

Instale a skill do BananaSplit para o Claude Code com banana skill install --agent claude.

Quando terminar, abra uma nova sessão (saia e rode claude de novo) para o agente carregar a skill.

Prefere fazer você mesmo? Rode isto no terminal:

banana skill install

Sem --agent, ele encontra todos os agentes que você tem instalados e escreve a skill para cada um. Você também pode instalar com npx skills add teotti/banana-cli --skill banana --global.

4. Adicione seu primeiro gasto pedindo

Agora é só dizer o que aconteceu:

Adiciona o jantar de ontem no Wendy's com o Leo, R$ 120

Pronto. O agente registra o gasto, divide e conta o que fez. O Leo já vê no BananaSplit na hora.

Mais coisas para pedir:

• "Quem me deve dinheiro, e quanto?"
• "Mostra os últimos 10 gastos da Viagem para Lisboa."
• "O Leo me pagou R$ 60, registra isso."
• "Adiciona o aluguel, R$ 3.000, todo dia 1 do mês, dividido com o Leo."

O que acontece por trás

O agente procura o Leo nos seus amigos, calcula a divisão e roda um único comando:

banana expenses add --title "Jantar no Wendy's" --amount 120 --currency BRL \
  --date 2026-10-27 --split me=60 --split Leo=60

Para um jantar em grupo, ele usa --group. Com --group e sem divisão, o gasto é dividido igualmente entre todo mundo do grupo:

banana expenses add --title "Jantar do time no Rosetta" --amount 720 --currency BRL \
  --date 2026-10-27 --group "Time"

Você nunca precisa escrever esses comandos, mas pode. São os mesmos comandos que você digitaria, então dá sempre para ler o que o agente fez, ou pular o agente e rodar direto. O banana expenses add --help lista todas as opções.

5. Deixe a sua caixa de entrada alimentar o BananaSplit

Pedir é rápido. Não precisar pedir é mais rápido ainda.

Muitos gastos já chegam por e-mail: pedidos da Amazon, faturas de hospedagem, contas de luz, extratos de pedágio. Dê ao seu agente acesso à sua caixa de entrada e ele transforma esses e-mails em gastos para você.

Nós usamos o HEY, que tem a sua própria CLI, então o agente consegue buscar e-mails e ler recibos pelo terminal. Gmail e Outlook funcionam do mesmo jeito pelos seus servidores MCP ou APIs.

Em uma sessão que tenha as skills do HEY e do BananaSplit, experimente:

Procura e-mails de pedidos da Amazon da última semana e adiciona cada um no BananaSplit como gasto pessoal. Usa --notify-me.

A flag --notify-me é o detalhe importante. Normalmente você não recebe notificação de um gasto que você mesmo adicionou. Com --notify-me, o BananaSplit manda a notificação de "gasto criado" mesmo assim, então cada gasto automático te dá um toque e você pode conferir rapidinho no celular:

banana expenses add --title "Amazon: USB-C hub" --amount 34.99 --currency USD \
  --date 2026-10-24 --split me=34.99 --notify-me

6. Transforme isso em uma tarefa que roda toda semana

Fazer isso na mão uma vez por semana ainda é chato. Então o próximo passo é pedir para o agente escrever um pequeno script e agendar. Algo assim:

Escreve um script que busque no HEY recibos da Amazon e do nosso provedor de hospedagem dos últimos 10 dias e adicione cada um no BananaSplit com --notify-me. Nunca adicione o mesmo recibo duas vezes. Registre em log o que ele faz. Depois agende para rodar toda segunda-feira às 10:00.

Foi assim que o meu próprio importador foi feito. Ele roda toda segunda-feira, e o log fica assim:

2026-10-19 10:00:01 signed in to HEY as [email protected]
2026-10-19 10:00:07 signed in to BananaSplit as Diogo ([email protected])
2026-10-19 10:00:08 [amazon] 1 email(s) in HEY from the last 10 days, 0 new
2026-10-19 10:00:08 [amazon] Your Amazon.com order of "USB-C hub": already handled in an earlier run
2026-10-19 10:00:08 [hosting] no emails in HEY from the last 10 days
2026-10-19 10:00:08 done: 0 added, 1 already in BananaSplit
2026-10-26 10:00:01 signed in to HEY as [email protected]
2026-10-26 10:00:07 signed in to BananaSplit as Diogo ([email protected])
2026-10-26 10:00:07 [amazon] no emails in HEY from the last 10 days
2026-10-26 10:00:08 [hosting] 1 email(s) in HEY from the last 10 days, 1 new
2026-10-26 10:00:12 [hosting] ADDED Hosting 29.00 USD 2026-10-25 [Side project] (receipt #2291-4410)
2026-10-26 10:00:12 done: 1 added, 0 already in BananaSplit

O script

Aqui vai uma versão enxuta para você copiar e adaptar. Ela faz três coisas: busca na caixa de entrada, lê o valor de cada recibo e adiciona no BananaSplit. As duas CLIs devolvem JSON com --json, o que facilita usar em scripts.

#!/usr/bin/env python3
"""Weekly job: receipts in HEY -> expenses in BananaSplit."""
import json, os, re, subprocess
from datetime import datetime

STATE = os.path.expanduser("~/.local/state/receipts-to-banana.json")
FOOTER = "\n\n🤖 automated"  # marks expenses this job created


def cli(*args):
    out = subprocess.run([*args, "--json"], capture_output=True, text=True).stdout
    return json.loads(out)


def log(msg):
    print(f"{datetime.now():%Y-%m-%d %H:%M:%S} {msg}", flush=True)


# One entry per kind of receipt: what to search for and where it goes.
SOURCES = [
    dict(name="amazon", query="Your Amazon.com order",
         amount_re=r"Order Total:\s*\$([\d,]+\.\d{2})", group=None),
    dict(name="hosting", query="Your receipt from",
         amount_re=r"Amount paid\s*\$([\d,]+\.\d{2})", group="Side project"),
]


def main():
    handled = set(json.load(open(STATE))) if os.path.exists(STATE) else set()
    for src in SOURCES:
        emails = cli("hey", "search", src["query"], "--date", "last_7_days").get("data", [])
        log(f"[{src['name']}] {len(emails)} email(s) in HEY")
        for email in emails:
            topic = str(email["topic_id"])
            if topic in handled:
                continue
            thread = cli("hey", "thread", "read", topic).get("data", [])
            body = "\n".join(entry.get("body") or "" for entry in thread)
            match = re.search(src["amount_re"], body)
            if not match:
                log(f"[{src['name']}] could not read an amount from {email['subject']}")
                continue
            amount = match.group(1).replace(",", "")
            args = ["banana", "expenses", "add",
                    "--title", email["subject"][:80],
                    "--amount", amount, "--currency", "USD",
                    "--date", email["updated_at"][:10],
                    "--description", f"From: {email['subject']}{FOOTER}",
                    "--notify-me"]
            args += ["--group", src["group"]] if src["group"] else ["--split", f"me={amount}"]
            cli(*args)
            handled.add(topic)
            log(f"[{src['name']}] ADDED {email['subject']} {amount} USD")
    os.makedirs(os.path.dirname(STATE), exist_ok=True)
    json.dump(sorted(handled), open(STATE, "w"))


if __name__ == "__main__":
    main()

Algumas coisas que vale manter, sejam quais forem as suas fontes:

• Nunca adicione duas vezes. Guarde quais e-mails você já tratou. O meu importador de verdade também confere no BananaSplit se já existe um gasto igual antes de adicionar, caso um recibo chegue duas vezes.
• Marque o que é automático. Toda descrição termina com 🤖 automated, para você diferenciar esses gastos dos que você digitou.
• Use --notify-me. Você recebe uma notificação para cada gasto novo, que é a sua chance de pegar um valor errado.
• Teste antes de valer. Peça para o agente uma flag --dry-run que mostre o que seria adicionado sem mudar nada.
• Respeite o limite de requisições. A API do BananaSplit permite 20 requisições por minuto, então faça uma pausa de alguns segundos entre chamadas quando uma execução adicionar muitos gastos.

Agende

No macOS, uma tarefa do launchd roda o script toda segunda-feira às 10:00 e recupera o atraso se o Mac estava dormindo. Salve isto como ~/Library/LaunchAgents/net.bananasplit.receipts.plist, com os seus caminhos:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>net.bananasplit.receipts</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/bin/python3</string>
    <string>/Users/you/jobs/receipts-to-banana.py</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key><string>/Users/you/.local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
  </dict>
  <key>StartCalendarInterval</key>
  <dict>
    <key>Weekday</key><integer>1</integer>
    <key>Hour</key><integer>10</integer>
    <key>Minute</key><integer>0</integer>
  </dict>
  <key>StandardOutPath</key><string>/Users/you/Library/Logs/receipts-to-banana.log</string>
  <key>StandardErrorPath</key><string>/Users/you/Library/Logs/receipts-to-banana.log</string>
</dict>
</plist>

Carregue uma vez:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/net.bananasplit.receipts.plist

No Linux, uma linha no crontab -e faz o mesmo:

0 10 * * 1 /usr/bin/python3 $HOME/jobs/receipts-to-banana.py >> $HOME/receipts-to-banana.log 2>&1

Para adicionar um novo tipo de recibo depois, você não edita o script. Abra o agente na pasta da tarefa e diga "importa também a minha conta de luz". Ele adiciona uma entrada em SOURCES, faz um dry run e mostra o resultado.

Dê um pouco de cor ao log

Um log simples resolve, mas você vai ler mais vezes se ele for fácil de bater o olho. Peça para o seu agente:

Escreve um pequeno script em awk que coloque cor no log: horários em cinza, logins em azul, erros em vermelho, "done" em verde, gastos adicionados em negrito, recibos ignorados em cinza, HEY em roxo e BananaSplit em amarelo.

Ele escreve algo como este colorize.awk:

# Colors importer log lines: awk -f colorize.awk
BEGIN {
  e = "\033["; reset = e "0m"; bold = e "1m"; gray = e "90m"
  red = e "31m"; green = e "32m"; yellow = e "33m"; blue = e "34m"; purple = e "35m"
}
{
  if ($0 !~ /^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] /) { print; fflush(); next }
  ts = substr($0, 1, 19); rest = substr($0, 21)
  if      (rest ~ /ERROR|FATAL|not logged in|^done with/) c = red
  else if (rest ~ /^signed in/)                         c = blue
  else if (rest ~ /^done/)                              c = green
  else if (rest ~ /ADDED/)                              c = bold
  else if (rest ~ /already|nothing to add|dry run|no emails/) c = gray
  else                                                  c = ""
  gsub(/HEY/, purple "HEY" reset c, rest)
  gsub(/BananaSplit/, yellow "BananaSplit" reset c, rest)
  printf "%s%s%s %s%s%s\n", gray, ts, reset, c, rest, reset
  fflush()
}

O arquivo de log continua sendo texto simples. As cores só aparecem quando você lê:

tail -f ~/Library/Logs/receipts-to-banana.log | awk -f colorize.awk

Agora uma execução com falha salta aos olhos em vermelho, e um gasto novo se destaca em negrito no meio das linhas cinzas de "nada novo".

O que você ganha com isso

Conte os gastos que você digitou no mês passado. Para a maioria das pessoas são entre 15 e 40, cerca de um minuto cada, contando abrir o app, achar o grupo e conferir a divisão. É meia hora a uma hora por mês, todo mês, em um trabalho que não exige pensar.

Com a CLI e uma skill, os gastos avulsos viram uma frase para o seu agente. Com uma tarefa semanal, os recorrentes deixam de precisar de você: eles aparecem no BananaSplit, já divididos, com uma notificação no celular. Você continua vendo tudo. Só não precisa digitar.

Instale a CLI, peça para o seu agente instalar a skill e peça para ele adicionar a última coisa que você pagou. O resto está na página BananaSplit para agentes de IA e na documentação.