Referência da CLI do Beancount

Use esta referência para consultar os comandos bea e seu comportamento. Para seu primeiro livro contábil, siga o início rápido da CLI. Para arquivos bancários, use o tutorial de importação.

Comandos de relance​

Opções globais e caminhos​

As opções globais vão antes do comando:

bea --file ~/my-books/main.bean check
bea --json list transaction --limit 100

init cria seu próprio alvo de diretório/arquivo e ignora BEA_FILE. Ele aceita a opção global --file em vez de seu argumento de diretório. format usa seu próprio alvo posicional, padronizando para o diretório de trabalho. A opção global --file não escolhe o alvo de formatação.

Criar um livro contábil​

bea init [DIRECTORY] usa por padrão o diretório atual. Um diretório cria main.bean; um caminho .bean ou .beancount nomeia o novo arquivo diretamente.

O modelo abre Assets:Checking, Assets:Savings, Assets:Cash, Liabilities:CreditCard, Income:Salary, Income:Interest, Expenses:Groceries, Expenses:Dining, Expenses:Rent, Expenses:Transport, Expenses:Utilities, Expenses:Fees e Equity:OpeningBalances.

Os saldos iniciais são compensados contra Equity:OpeningBalances. Dívida é negativa. A entrada de moeda é convertida para maiúsculas. Símbolos personalizados são permitidos; um símbolo que não seja três letras maiúsculas aciona um aviso de erro de digitação. Isso não é uma verificação de registro ISO de moedas.

Arquivos existentes nunca são sobrescritos. Novos arquivos usam permissões somente do proprietário, modo 0600 em POSIX. Gravações posteriores de add, import e format preservam permissões e respeitam destinos somente leitura.

Adicionar transações​

bea add transaction -n "Groceries" --payee "Corner Market" \
  -p "Expenses:Groceries 30" -p "Assets:Checking" \
  --flag '!' --tag household --link receipt-42 --meta 'receipt:IMG_42.jpg'

Um lançamento pode omitir seu valor. Lançamentos numerados podem omitir a moeda quando uma conta tem uma moeda permitida ou o livro contábil tem uma moeda operacional compatível. Caso contrário, forneça o símbolo.

A sintaxe nativa de lançamentos suporta aritmética como 84/2 EUR, custos como {100 USD}, custos totais {{1000 USD}} e preços @ ou @@. Use valores decimais como 1000, não notação exponencial como 1e3.

Uma conversão de moeda precisa da taxa de transação real. Por exemplo, lance 100 EUR @ 1.08 USD em uma conta aberta em EUR e -108 USD em conta corrente. Uma compra de investimento pode lançar 2 AAPL {100 USD} em uma conta aberta em AAPL e -200 USD em conta corrente. Adicione cotações de price datadas quando relatórios precisarem de avaliação de mercado.

Metadados aceitam strings simples como --meta 'receipt:IMG_42.jpg'. Números nativos, booleanos, datas e valores retêm seus tipos. Exemplos incluem --meta 'reviewed:TRUE', --meta 'received:2026-08-03' e --meta 'fee:2.50 USD'. Aspas internas forçam uma string: --meta 'code:"1234"'. Chaves devem ser distintas; filename e lineno são reservadas.

Adições individuais, em lote e importações substituem quebras de linha em pagadores, narrações e metadados de string por espaços. Aspas e barras invertidas mantêm seu conteúdo.

Adicionar outras diretivas​

Todos esses comandos exigem --date YYYY-MM-DD. Eles também aceitam --into FILE e --allow-errors.

Nomes de conta têm uma raiz capitalizada e segmentos separados por dois pontos. Cada subconta começa com uma letra maiúscula ou dígito. Beancount suporta letras Unicode e nomes de raiz configurados.

Um balance verifica a conta no início de sua data. A sintaxe de tolerância é suportada, como --amount "1538 ~ 1 EUR". A tolerância deve ser não negativa.

Use add balance --pad-from Equity:OpeningBalances para gravar um pad e sua verificação de balance juntos. O pad usa como padrão o dia anterior; --pad-date pode selecionar outro dia anterior. Ambas as contas devem estar ativas. Um pad independente precisa de um balance posterior para consumi-lo. --allow-errors pode preparar esse estado intermediário, mas não pode ignorar uma conta de pad inválida.

add price pula uma duplicata exata de data/mercadoria/preço na raiz e seus includes. Sai com código 0 e identifica a localização existente. Datas ou preços diferentes são novas adições.

Caminhos de documentos são resolvidos ao lado do arquivo que contém a diretiva. Com --into years/2026.bean, --filename receipt.pdf significa years/receipt.pdf, não um arquivo ao lado do diretório de trabalho do seu shell.

Tipos de valor personalizado são text, number, amount, account, bool e date. Por exemplo, um orçamento pode usar --value "text:travel" --value "amount:500 USD".

Entrada JSON em lote​

bea add transactions --from transactions.json aceita uma matriz JSON:

[
  {
    "date": "2026-08-04",
    "narration": "Groceries",
    "postings": [
      { "account": "Expenses:Groceries", "amount": "45.00 USD" },
      { "account": "Assets:Checking" }
    ],
    "meta": { "receipt": "R-43", "reviewed": true }
  }
]

Cada transação exige date e postings. Campos opcionais são flag, payee, narration, tags, links e meta.

Um lançamento usa amount ou units, como {"number":"45.00","currency":"USD"}. Omita ambos para o lançamento de equilíbrio. Campos de lançamento também incluem cost, price, flag e meta. Custos contêm number e currency, com date e label opcionais. Preços contêm number e currency.

Use strings para decimais. Metadados usam strings e booleanos comuns, ou valores marcados como {"kind":"number","value":"1.125"}, {"kind":"date","value":"2026-08-04"} e {"kind":"amount","number":"2.50","currency":"USD"}. A localização opcional source da transação nunca é gravada como metadados.

O padrão é um lote atômico: qualquer linha rejeitada deixa o livro contábil inalterado e sai com código 1. --partial grava um subconjunto válido e ainda sai com código 1 se quaisquer linhas forem rejeitadas. Erros JSON descrevem o resultado em error.result; índices de linha lá são baseados em zero. Números de linha humanos são baseados em um.

A adição em lote aceita --into e --allow-errors. Ela não deduplica. Use bea import para revisão de exportações bancárias.

Livros contábeis divididos e segurança de gravação​

Mantenha --file apontado para a raiz. Adicione --into para selecionar um arquivo incluído existente:

bea --file ~/my-books/main.bean add transaction --into 2026.bean \
  --date 2026-08-02 -n "Groceries" \
  -p "Expenses:Groceries 30" -p "Assets:Checking"

O destino é relativo ao diretório raiz. Ele já deve estar incluído; nomear um arquivo não relacionado é recusado. Comandos add, importações e gravações interativas de IA suportam essa separação.

Gravações validam o livro contábil candidato completo, incluindo plugins e reserva de lotes de custo. Uma mudança concorrente na raiz ou em seu grafo de includes sai com código 4. Um destino somente leitura sai com código 3. Adições bem-sucedidas usam o mesmo alinhamento que bea format, que pode realinhar colunas existentes nesse destino.

Listar diretivas​

bea list TYPE suporta os onze tipos: transaction, open, close, balance, pad, note, event, price, commodity, document e custom.

Outros tipos de diretivas mantêm ordem cronológica. Uma tabela de transações filtrada por conta rotula sua coluna de valor como MATCHING POSTING AMOUNTS. Detalhes e JSON ainda incluem todos os lançamentos de cada transação selecionada. Detalhes renderizam entradas carregadas, incluindo valores inferidos; não são trechos brutos de origem.

Check, format e query​

bea check valida a raiz e os includes. Sai com código 1 para erros de livro contábil e não tem opção --allow-errors. Queries, listas e relatórios também rejeitam erros do carregador a menos que você passe explicitamente sua opção --allow-errors.

A formatação aceita um arquivo .bean/.beancount ou um diretório. Um diretório é pesquisado recursivamente.

Cada modo relata erros de sintaxe por arquivo e linha, pula esses arquivos e sai com código 1. Uma execução normal recursiva ainda pode formatar os arquivos válidos. JSON relata scanned, formatted, skipped, dry_run e check, sob error.result em falha.

bea query "BQL" executa uma consulta Beancount. Omitir BQL abre um shell interativo; exit ou quit o fecha. Um argumento de consulta é necessário sem supervisão. A tabela padrão de BQL tem uma linha por lançamento. Tabelas de consulta retêm precisão. Resultados vazios imprimem (no rows) no stderr; JSON retorna um data.rows vazio e metadados de coluna em data.columns.

Relatórios financeiros​

Todos os relatórios aceitam --conversion / -x, --time / -t, --account / -a e --allow-errors. Todos exceto trial balance também aceitam --interval / -i: monthly por padrão, ou quarterly, yearly, weekly ou daily.

Filtros de tempo incluem ano, mês, data, trimestre, semana ou intervalo, como 2026, 2026-08, 2026-08-31, 2026-Q3, 2026-W32 ou "2026-01 - 2026-08". Períodos relativos incluem year, quarter, month, week, day e deslocamentos como month-1. Filtros de conta retêm cada lançamento de uma transação correspondente.

A conversão usa como padrão a única moeda operacional do livro contábil. Caso contrário, usa como padrão units, mantendo mercadorias separadas. at_cost usa custos de aquisição. at_value usa valores de mercado com fallback de custo.

Uma conversão de moeda explícita precisa de preços em ou antes de cada data de avaliação, incluindo datas de intervalo. Um erro de preço ausente nomeia a lacuna real, como No EUR → USD price on or before 2026-01-31. Uma cotação posterior não pode preencher uma lacuna anterior. Adicione um preço historicamente apropriado, use --conversion units ou escolha --allow-errors para inspecionar valores parciais.

Relatórios parciais preservam moedas de origem e marcam totais combinados como indisponíveis. JSON inclui valuation: "partial", missing_prices e missing_price_dates. Totais afetados de lucro líquido/patrimônio líquido são null na moeda solicitada.

Receitas, passivos e patrimônio normalmente usam sinais negativos do Beancount. Lucro líquido é -(income + expenses), positivo para um ganho. A mesma convenção se aplica a linhas de período do income-statement. A conciliação do balance-sheet é derivada para o relatório; ela não grava diretivas. equity_reconciled identifica se uma conciliação completa está disponível.

O JSON do relatório também identifica o período, data final exclusiva, data de referência, conversão, filtro de conta e status de validação do livro contábil. Verifique esses campos antes de comparar totais.

Assistência opcional de IA​

bea ask precisa tanto do extra ask quanto de credenciais Beancount.io de bea cloud login ou BEA_TOKEN. A instalação padrão do Homebrew omite dependências de IA. Usuários do Homebrew podem executar:

bea cloud login
uvx --from 'beancount-io[ask]' bea ask "What did I spend last month?" --print

Para uma instalação uv, instale beancount-io[ask] e execute bea ask diretamente. --print / -p responde uma vez e sai. Caso contrário, uma sessão de terminal é interativa, e uma pergunta opcional pré-preenche sua entrada. Uso não interativo requer uma pergunta. O modo JSON não é suportado.

Consultas são executadas localmente. Perguntas, contexto de habilidades e resultados de ferramentas vão para o serviço de IA hospedado do Beancount.io. Gravações interativas são pré-visualizadas, confirmadas, validadas e gravadas atomicamente. Elas aceitam --into. A opção global --yes não concede permissão de gravação à IA. O modo de uma resposta não aplica gravações propostas.

Ask lê NAME/SKILL.md de .agents/skills/ no diretório de trabalho e de skills/ no diretório de configuração do usuário. Definições de projeto vencem por nome. Cada arquivo precisa dos campos YAML name e description. Instruções completas são carregadas sob demanda.

Livros contábeis hospedados​

A criação também aceita --clone e --dir. Acesso Git e SSH são necessários para clonar. Se a clonagem falhar após a criação, o livro contábil hospedado ainda existe. Comandos locais não enviam seu livro contábil automaticamente. Não há opção global --ledger.

JSON e códigos de saída​

A opção global --json coloca resultados bem-sucedidos no stdout:

{
  "bea": "0.1.0",
  "target": { "file": "/home/alice/my-books/main.bean" },
  "data": [],
  "truncated": false,
  "limit": 50
}

bea é a versão instalada; data depende do comando. Alvos identificam um arquivo, diretório, servidor ou nenhum alvo. Gravações incluídas também identificam into. Valores decimais e datas usam strings. Listas limitadas incluem limit e truncated.

Falhas gravam {"error":{"category":"validation","message":"…","exit_code":1}} no stderr. O erro também pode incluir details, result, um request_id de backend e um traceback com --debug.

Verifique error.result antes de repetir uma mutação. Um lote parcial pode gravar linhas aceitas, formatação recursiva pode alterar arquivos válidos, e criar-e-clonar pode criar um livro contábil hospedado antes de sair com código diferente de zero.

Prompts da CLI são desativados por --no-input, modo JSON, stdin não terminal ou CI verdadeiro. Exclusão na nuvem ainda precisa de --yes explícito. Importações precisam de uma decisão explícita de duplicata quando correspondências precisam de revisão.

Exceções de saída: Ask rejeita JSON; login na nuvem precisa de interação; logout e clone bem-sucedidos na nuvem não retornam objeto de sucesso JSON. Ajuda, versão e conclusão mantêm saída de texto. upgrade pode transmitir a saída do gerenciador de pacotes para o stderr, inclusive no modo JSON.

Configurações, atualizações e estado armazenado​

Valores verdadeiros são 1, true, yes e on, ignorando maiúsculas/minúsculas e espaços ao redor. Estado de configuração inclui credenciais, histórico de prompts do Ask, habilidades do usuário, caminhos de importadores lembrados e caches de verificação de atualização. Bloqueios de gravação ficam sob locks/ no diretório de cache, fora do seu diretório de livro contábil.

bea upgrade --check relata versões e o método de instalação sem atualizar. bea upgrade invoca brew upgrade bea, uv tool upgrade beancount-io ou pipx upgrade beancount-io. Instalações editáveis recebem orientação de atualização manual. Verificações passivas ocorrem no máximo uma vez por dia em cópias instaladas interativas; upgrade --check explícito ainda executa quando o notificador passivo está desativado.

Desinstale com o gerenciador correspondente: brew uninstall bea, uv tool uninstall beancount-io ou pipx uninstall beancount-io. Seus arquivos de livro contábil e configuração de usuário permanecem.

Correções comuns​

Use bea COMMAND --help para inspecionar sua versão instalada. A referência do repositório de origem contém exemplos adicionais e as definições exatas do modelo de diretivas.