Início rápido da CLI do Beancount

Crie um livro-razão local e registre sua primeira compra com bea, a ferramenta de linha de comando do Beancount.io. A contabilidade local não requer uma conta no Beancount.io.

Este tutorial começa com 1.000 USD em conta corrente. Após uma compra de café de 12,50 USD, você verificará um saldo de 987,50 USD.

1. Instale o comando​

Com Homebrew no macOS ou Linux:

brew install bex-co/tap/bea
bea --version

Se você não usa Homebrew, instale uv e use uv tool install beancount-io. O pacote Python requer Python 3.12 ou mais recente.

2. Crie seu livro-razão​

Escolha um novo diretório. Este exemplo cria main.bean dentro de ~/my-books:

bea --no-input init ~/my-books --currency USD --date 2026-08-01 \
  --opening-balance "Assets:Checking 1000"
cd ~/my-books

O modelo abre contas de conta corrente, dinheiro, cartão de crédito, receita e despesa. O saldo inicial é compensado contra Equity:OpeningBalances.

Para seus próprios livros, escolha a data mais antiga que pretende registrar. Todas as contas do modelo abrem nessa data. O saldo inicial deve descrever a conta nesse dia. Dívida de cartão de crédito usa um valor negativo.

init nunca sobrescreve um livro-razão existente. Novos arquivos são privados em sistemas POSIX: apenas o proprietário pode lê-los e escrevê-los. Para compartilhar com seu grupo de usuários local, altere explicitamente as permissões com chmod 640 main.bean.

Para configuração guiada, execute bea init ~/my-books em um terminal. O assistente pergunta sobre sua moeda, data de início do histórico e saldo da conta corrente.

3. Registre uma compra​

bea add transaction --date 2026-08-02 --narration "Coffee" \
  --posting "Expenses:Dining 12.50" \
  --posting "Assets:Checking"

A despesa usa a moeda da conta. O Beancount preenche o outro lançamento como -12.50 USD. Você pode omitir --date para compras feitas hoje.

Cada adição é verificada contra o livro-razão completo antes que o arquivo seja substituído. Uma conta desconhecida ou uma transação desbalanceada produz um erro com orientação.

4. Verifique o resultado​

bea check
bea list transaction --limit 10
bea report balance-sheet

A lista de transações mostra as entradas mais recentes primeiro, com seus valores de lançamento. O balanço patrimonial mostra 987.50 USD na conta corrente.

Para verificar esse valor diretamente:

bea query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"

As tabelas de consulta preservam a precisão do resultado. Para saída estruturada, coloque a flag global --json antes do comando:

bea --json list transaction --limit 10

5. Mantenha seus livros em boa forma​

Execute bea check após editar o arquivo manualmente. Execute bea format main.bean para alinhar suas colunas. Use bea format main.bean --check quando um script deve falhar se a formatação for necessária.

Para trabalhar de outro diretório, selecione o arquivo raiz explicitamente:

bea --file ~/my-books/main.bean check

A raiz é selecionada por --file, depois BEA_FILE, e então main.bean no diretório de trabalho. Opções globais vão antes do comando. A formatação aceita seu próprio argumento de arquivo ou diretório.

Continue com seus próprios registros​

• Importe uma exportação bancária com pré-visualização e revisão de duplicatas.
• Consulte comandos e opções para contas, saldos, investimentos, automação e relatórios.
• Organize um livro-razão em vários arquivos. Use --into para escrever em um arquivo incluído enquanto valida contra a raiz.
• Use a interface do navegador se preferir formulários a comandos de terminal.

Verifique atualizações com bea upgrade --check. Execute bea upgrade para invocar o gerenciador de pacotes que instalou sua cópia. Use bea --help ou bea add transaction --help para inspecionar as opções disponíveis na sua versão instalada.