Primeiros passos com a CLI do BananaSplit: automatiza o registo e a divisão de despesas com agentes de IA

A maioria das despesas não precisa de uma decisão. Precisa de alguém que as escreva. Um jantar com a equipa, a fatura mensal do alojamento, a encomenda da Amazon que dividiste com quem vive contigo: já sabes quem pagou e como dividir. Escrever é que é a parte chata.

A CLI do BananaSplit passa essa parte para o teu agente de IA. Dizes o que aconteceu por palavras tuas e o agente regista no BananaSplit. Dá mais um passo e o agente nem precisa que lhe peças: lê os recibos da tua caixa de entrada e adiciona-os de forma agendada.

Este guia leva-te do zero às duas coisas.

1. Instala 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

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

Depois inicia sessão. Isto abre o browser e a CLI guarda o login de forma segura no teu computador:

banana login

Confirma que está tudo pronto:

banana doctor
banana balance

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

2. Abre o teu agente

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

claude

3. Pede ao teu agente para instalar a skill banana

A skill ensina ao teu agente como funciona a CLI: que comandos existem, como as divisões batem certo, como chamar grupos e amigos, e quando perguntar antes de alterar alguma coisa. Não precisas de procurar nada disto. Basta pedir:

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

Quando terminar, abre uma nova sessão (sai e corre claude outra vez) para o agente carregar a skill.

Preferes fazer tu? Corre isto no terminal:

banana skill install

Sem --agent, encontra todos os agentes que tens instalados e escreve a skill para cada um. Também a podes instalar com npx skills add teotti/banana-cli --skill banana --global.

4. Adiciona a tua primeira despesa a pedir

Agora é só dizer o que aconteceu:

Adiciona o jantar de ontem no Wendy's com o Leo, 40 €

E pronto. O agente regista a despesa, divide-a e diz-te o que fez. O Leo vê-a no BananaSplit logo a seguir.

Mais coisas que podes pedir:

• "Quem me deve dinheiro, e quanto?"
• "Mostra as últimas 10 despesas da Viagem a Lisboa."
• "O Leo devolveu-me 20 €, regista isso."
• "Adiciona a renda, 1800 €, todos os dias 1 do mês, dividida com o Leo."

O que acontece nos bastidores

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

banana expenses add --title "Jantar no Wendy's" --amount 40 --currency EUR \
  --date 2026-10-27 --split me=20 --split Leo=20

Para um jantar de grupo, usa --group. Com --group e sem divisão, a despesa é dividida em partes iguais por todas as pessoas do grupo:

banana expenses add --title "Jantar de equipa no Rosetta" --amount 239 --currency EUR \
  --date 2026-10-27 --group "Equipa"

Nunca tens de escrever estes comandos, mas podes. São os mesmos comandos que escreverias tu, por isso podes sempre ler o que o agente fez, ou dispensar o agente e corrê-los diretamente. O banana expenses add --help lista todas as opções.

5. Deixa a tua caixa de entrada alimentar o BananaSplit

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

Muitas despesas já chegam por email: encomendas da Amazon, faturas de alojamento, contas da luz, extratos de portagens. Dá ao teu agente acesso à tua caixa de entrada e ele transforma esses emails em despesas por ti.

Nós usamos o HEY, que tem a sua própria CLI, por isso o agente consegue pesquisar emails e ler recibos a partir do terminal. O Gmail e o Outlook funcionam da mesma forma através dos seus servidores MCP ou APIs.

Numa sessão que tenha as skills do HEY e do BananaSplit, experimenta:

Procura emails de encomendas da Amazon da última semana e adiciona cada um ao BananaSplit como despesa pessoal. Usa --notify-me.

A flag --notify-me é o mais importante. Normalmente não recebes notificação de uma despesa que adicionaste tu. Com --notify-me, o BananaSplit envia-te na mesma a notificação de "despesa criada", por isso cada despesa automática te dá um toque no ombro e podes vê-la de relance no telemóvel:

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

6. Transforma isto numa tarefa que corre todas as semanas

Fazer isto à mão uma vez por semana continua a ser uma tarefa chata. Por isso o passo seguinte é pedir ao agente que o escreva como um pequeno script e o agende. Algo assim:

Escreve um script que procure no HEY recibos da Amazon e do nosso fornecedor de alojamento dos últimos 10 dias e adicione cada um ao BananaSplit com --notify-me. Nunca adiciones o mesmo recibo duas vezes. Regista num log o que faz. Depois agenda-o para correr todas as segundas-feiras às 10:00.

Foi assim que o meu próprio importador nasceu. Corre todas as segundas-feiras 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 fica uma versão reduzida que podes copiar e adaptar. Faz três coisas: pesquisa a caixa de entrada, lê o valor de cada recibo e adiciona-o ao BananaSplit. As duas CLIs devolvem JSON com --json, o que as torna fáceis de 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 a pena manter, sejam quais forem as tuas fontes:

• Nunca adicionar duas vezes. Guarda os emails que já trataste. O meu importador verdadeiro também confirma no BananaSplit se já existe uma despesa igual antes de adicionar, caso um recibo chegue duas vezes.
• Marca o que é automático. Todas as descrições terminam com 🤖 automated, para distinguires estas despesas das que escreveste tu.
• Usa --notify-me. Recebes uma notificação por cada despesa nova, que é a tua oportunidade de apanhar um valor errado.
• Testa antes de ser a sério. Pede ao agente uma flag --dry-run que mostre o que seria adicionado sem alterar nada.
• Respeita o limite de pedidos. A API do BananaSplit permite 20 pedidos por minuto, por isso faz uma pausa de alguns segundos entre chamadas quando uma execução adiciona muitas despesas.

Agenda-o

No macOS, uma tarefa do launchd corre o script todas as segundas-feiras às 10:00 e recupera o atraso se o Mac estava a dormir. Guarda isto como ~/Library/LaunchAgents/net.bananasplit.receipts.plist, com os teus 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>

Carrega-o 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 mais tarde, não editas o script tu. Abre o agente na pasta da tarefa e diz "importa também a minha conta da luz". Ele acrescenta uma entrada a SOURCES, faz um dry run e mostra-te o resultado.

Dá alguma cor ao log

Um log simples cumpre a função, mas vais lê-lo mais vezes se for fácil de percorrer. Pede ao teu agente:

Escreve um pequeno script em awk que dê cor ao log: horas a cinzento, inícios de sessão a azul, erros a vermelho, "done" a verde, despesas adicionadas a negrito, recibos ignorados a cinzento, HEY a roxo e BananaSplit a 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 ficheiro de log continua a ser texto simples. As cores só aparecem quando o lês:

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

Agora uma execução falhada salta à vista a vermelho, e uma despesa nova destaca-se a negrito entre as linhas cinzentas de "nada de novo".

O que ganhas com isto

Conta as despesas que escreveste no mês passado. Para a maioria das pessoas são entre 15 e 40, a cerca de um minuto cada, contando com abrir a app, encontrar o grupo e confirmar a divisão. É meia hora a uma hora por mês, todos os meses, num trabalho que não exige pensar.

Com a CLI e uma skill, as despesas pontuais passam a ser uma frase para o teu agente. Com uma tarefa semanal, as recorrentes deixam de precisar de ti: aparecem no BananaSplit, já divididas, com uma notificação no telemóvel. Continuas a ver tudo. Só não tens de escrever.

Instala a CLI, pede ao teu agente para instalar a skill e pede-lhe para adicionar a última coisa que pagaste. O resto está na página BananaSplit para agentes de IA e na documentação.