Seu primeiro mês com bea

Feche um mês de escrituração de ponta a ponta com bea, a ferramenta de linha de comando do Beancount.io. Você vai abrir um livro-razão, registrar compras, importar um export bancário, reconciliar com um saldo de extrato de 3206,81 USD e ler o demonstrativo de resultados e o balanço patrimonial do mês.

O mês é agosto de 2026 e o livro-razão começa com 1.250 USD em conta corrente. Nada aqui pede que você escreva Python ou uma consulta.

Instale bea primeiro, se ainda não o fez: o guia rápido do CLI Beancount cobre Homebrew e uv. A escrituração local não precisa de conta no Beancount.io.

Trabalhe em um diretório vazio. Baixe os dois arquivos de entrada para ele antes de começar:

• first-month.csv — o export bancário que você importa na semana 3.
• rules.toml — as regras de categorização que esse export usa.

Todo comando nomeia o livro-razão com --file august/main.bean, para que você possa executá-los desse diretório sem entrar no livro-razão.

Semana 1 — configurar os livros​

Crie o livro-razão e, em seguida, abra a única conta que o modelo não inclui para este mês.

bea --no-input init august --currency USD --date 2026-08-01 \
  --opening-balance "Assets:Checking 1250"
bea --file august/main.bean add open --date 2026-08-01 --account Expenses:Transport:Fuel -c USD

init grava august/main.bean com catorze contas, incluindo Expenses:Uncategorized. Importações depositam linhas que não conseguem categorizar lá.

Semana 2 — registrar compras diárias​

Registre compras conforme elas acontecem. A data padrão é hoje, então histórico retroativo exige --date explicitamente.

bea --file august/main.bean add transaction "Coffee" --date 2026-08-03 \
  --posting "Expenses:Dining 4.50" --posting "Assets:Checking"
bea --file august/main.bean add transaction "Weekly groceries" --date 2026-08-05 \
  --posting "Expenses:Groceries 62.30" --posting "Assets:Checking"
bea --file august/main.bean add transaction --date 2026-08-07 --payee "Employer" \
  --narration "August salary" --posting "Assets:Checking 2100" --posting "Income:Salary"

Cada adição é verificada em relação ao livro-razão inteiro antes de o arquivo ser substituído. O segundo lançamento fica em branco, então o Beancount preenche o valor de equilíbrio.

Semana 3 — importar o export bancário​

O export para o restante de agosto contém três linhas:

Date,Payee,Amount
2026-08-10,Whole Foods,-28.40
2026-08-12,Shell,-35.00
2026-08-20,Mystery Shop,-9.99

O arquivo de regras associa um favorecido a uma conta. As regras são executadas na ordem do arquivo e a primeira correspondência vence.

[[rule]]
match = "whole foods|trader joe|corner market"
account = "Expenses:Groceries"
 
[[rule]]
match = "shell|chevron|exxon"
account = "Expenses:Transport:Fuel"
 
[[rule]]
match = "salary|payroll|employer"
account = "Income:Salary"

Mapeie as colunas do export com --csv, visualize o resultado e repita com --apply para gravá-lo.

bea --file august/main.bean import first-month.csv \
  --csv date=Date,amount=Amount,payee=Payee --account Assets:Checking --rules rules.toml
bea --file august/main.bean import first-month.csv --apply

A visualização imprime uma linha por linha com a regra que a correspondeu, além do diff exato que seria gravado. Nada é gravado até --apply.

O segundo comando não precisa de flags: o mapeamento de colunas, a conta e as regras são lembrados para aquele arquivo. Cada entrada gravada carrega uma linha import-id, então importar o mesmo export novamente pula o que já está no livro-razão.

Duas linhas correspondem a uma regra. A terceira, Mystery Shop, não corresponde a nada, então ela é lançada em Expenses:Uncategorized com a flag ! — sua fila de revisão para depois.

Para o formato de colunas de débito e crédito, outras moedas e importadores Python, veja Importar exports bancários com o CLI.

Semana 4 — reconciliar com o extrato​

O extrato de agosto fecha a conta corrente em 3206,81 USD. Seus livros dizem 3209,81 USD. A diferença é uma tarifa bancária de 3,00 USD que o export não registrou.

Registre a tarifa e então afirme o saldo do extrato. O Beancount verifica uma asserção no início do seu dia, então uma asserção em 1º de setembro cobre todas as transações de agosto.

bea --file august/main.bean add transaction "Bank fee" --date 2026-08-31 \
  --posting "Expenses:Fees 3.00" --posting "Assets:Checking"
bea --file august/main.bean add balance --date 2026-09-01 --account Assets:Checking \
  --amount "3206.81 USD"
bea --file august/main.bean list transaction --flag '!' --details

A fila contém uma transação, a linha Mystery Shop. --details imprime o arquivo e o número da linha dela.

Abra essa linha em seu editor. Altere o lançamento Expenses:Uncategorized para a conta à qual pertence — Expenses:Dining aqui — e mude a flag de ! para * para marcá-la como revisada. Mantenha a linha import-id para que uma importação repetida ainda pule a linha.

Depois confirme que o livro-razão carrega e que a fila está vazia:

bea --file august/main.bean check
bea --file august/main.bean list transaction --flag '!' --details

Um livro-razão limpo sai com código 0. Uma asserção quebrada ou uma conta desconhecida é listada com saída não zero. A fila agora imprime Nenhuma transação encontrada.

Leia o mês​

bea --file august/main.bean report income-statement --time 2026-08
bea --file august/main.bean report balance-sheet
bea --file august/main.bean report income-statement --time month

O demonstrativo de resultados compensa o salário de 2.100,00 USD contra 143,19 USD de despesas para um lucro líquido de 1.956,81 USD. Os saldos das contas são impressos nos sinais do Beancount, então linhas de receita são negativas. O balanço patrimonial mostra a conta corrente em 3.206,81 USD, correspondendo ao extrato com o qual você reconciliou.

--time 2026-08 fixa o mês deste tutorial. --time month sempre significa o mês atual, que é o que você usará quando seus livros estiverem em dia.

Continue daqui​

• Importar exports bancários com o CLI para revisão de duplicatas, outros layouts de colunas e importações repetidas.
• Automatizar a escrituração com bea para o envelope JSON, códigos de saída e execuções não assistidas.
• Referência do CLI Beancount para todos os comandos e opções.