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 escrituração local não requer uma conta no Beancount.io.

Este passo a passo 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 o Homebrew no macOS ou Linux:

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

Se você não usa o Homebrew, instale o uv e use uv tool install beancount-io. O pacote Python requer Python 3.12 ou mais recente. O Homebrew provisiona o mecanismo contábil durante a instalação. Com o PyPI, mantenha o uv disponível: o primeiro comando local baixa o mecanismo gerenciado e, em seguida, comandos posteriores o reutilizam offline. Você não precisa instalar o Beancount separadamente.

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 comuns de conta corrente, poupança, dinheiro, cartão de crédito, receita e despesas. O saldo inicial é compensado com Equity:OpeningBalances.

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

O init nunca sobrescreve um livro-razão existente. Novos arquivos são privados em sistemas POSIX: somente 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 USD 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 todo o livro-razão antes que o arquivo seja substituído. Uma conta desconhecida ou uma transação desequilibrada 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 em 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 o sinalizador 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 -i main.bean para alinhar suas colunas no lugar. Sem -i, o texto formatado vai para a saída padrão e o arquivo permanece inalterado. 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, depois 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.
• Entregue dois trabalhos de escrituração a um agente externo com prompts copiáveis e equivalentes de CLI.
• Compare cinco ferramentas de contabilidade para agentes de IA sobre instalação, autenticação, escopo, dados, pré-visualização, saída e repetições, com fontes datadas.
• Consulte comandos e opções para contas, saldos, investimentos, relatórios e automação.
• Organize um livro-razão entre arquivos. Use --into para escrever 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.