Referência da CLI do Beancount

Use esta referência para consultar os comandos bea e seu comportamento. Para o seu primeiro livro-caixa, siga o início rápido da CLI. Para fechar um mês completo de ponta a ponta, percorra Seu primeiro mês com o bea. Para arquivos bancários, use o passo a passo de importação.

Comandos em resumo​

Opções globais e caminhos​

As opções globais vêm antes do comando:

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

init cria seu próprio diretório/arquivo de destino e ignora BEA_FILE. Ele aceita o --file global em vez de seu argumento de diretório. format usa seu próprio alvo posicional. Forneça um nome de arquivo ou diretório. O --file global não escolhe o alvo da formatação.

Criar um ledger​

bea init [DIRECTORY] usa o diretório atual por padrão. 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, Expenses:Uncategorized e Equity:OpeningBalances.

Os saldos de abertura 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 dispara um aviso de erro de digitação. Esta não é uma verificação do registro ISO de moedas.

Arquivos existentes nunca são sobrescritos. Novos arquivos usam permissões apenas para o proprietário, modo 0600 em POSIX. Escritas posteriores de add e import preservam as permissões e respeitam destinos somente leitura. A formatação no local usa o formatador nativo e relata seus próprios erros de sistema de arquivos.

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 única moeda permitida ou o livro-caixa tem uma única moeda operacional compatível. Caso contrário, forneça o símbolo.

A sintaxe nativa de lançamento 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 troca de moeda precisa da taxa real da transação. Por exemplo, lance 100 EUR @ 1.08 USD em uma conta aberta em EUR e -108 USD na conta corrente. Uma compra de investimento pode lançar 2 AAPL {100 USD} em uma conta aberta em AAPL e -200 USD na conta corrente. Adicione cotações 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 mantê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"'. As chaves devem ser distintas; filename e lineno são reservados.

Adições individuais, adições em massa e importações substituem quebras de linha em contrapartes, 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 contas têm uma raiz com inicial maiúscula e segmentos separados por dois-pontos. Cada subconta começa com uma letra maiúscula ou dígito. O Beancount suporta letras Unicode e nomes de raiz configurados.

Um saldo 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 escrever um pad e sua asserção de saldo juntos. O pad usa o dia anterior por padrão; --pad-date pode selecionar outro dia anterior. Ambas as contas devem estar ativas. Um pad autônomo precisa de um saldo 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/ativo/preço em toda a raiz e suas inclusões. Ele encerra com 0 e identifica o local 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.

Os tipos de valor personalizados 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 um array 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 balanceamento. 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"}. O local source opcional da transação nunca é escrito como metadado.

O padrão é um lote atômico: qualquer linha rejeitada deixa o livro-caixa inalterado e encerra com código 1. --partial escreve um subconjunto válido e ainda encerra com código 1 se alguma linha for rejeitada. Erros de JSON descrevem o resultado em error.result; os índices de linha ali são baseados em zero. Os números de linha humanos são baseados em um.

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

Livros razão divididos e segurança na gravação​

Mantenha --file apontando 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 de adição, importações e escritas interativas da IA suportam essa separação.

As escritas validam o livro-caixa candidato completo, incluindo plugins e booking de lotes de custo. Uma alteração concorrente na raiz ou em seu grafo de inclusão encerra com código 4. Um destino somente leitura encerra com código 3. Adições bem-sucedidas alinham apenas as novas linhas. Os bytes existentes permanecem inalterados. Use bea format -i PATH quando quiser realinhar o arquivo inteiro.

Diretivas de lista​

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

Outros tipos de diretiva mantêm a ordem cronológica. Uma tabela de transações filtrada por conta rotula sua coluna de valores 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; eles não são trechos brutos da fonte.

Verificar, formatar e consultar​

bea check valida a raiz e as inclusões. Ele encerra silenciosamente com 0 em caso de sucesso e 1 para erros do livro-caixa. O --json global retorna o envelope de validação. Não há opção --allow-errors para check.

Consultas, listas e relatórios avisam e retornam resultados parciais em um terminal interativo. O --strict global, --json, --no-input, CI verdadeiro ou stdin não terminal tornam as leituras estritas. A opção --allow-errors deles permite explicitamente resultados parciais.

A formatação aceita arquivos ou busca recursivamente em um diretório. No pacote publicado 0.2.0, um caminho é obrigatório apesar do padrão stdin mostrado na ajuda. O --file global não escolhe o alvo da formatação.

A formatação alinha texto; ela não valida a sintaxe do livro-caixa nem a contabilidade. Execute bea check separadamente. Com o --json global, selecione -i, -o FILE, --check ou --dry-run para que stdout possa carregar o envelope. Não redirecione stdout sobre o arquivo de entrada: use -i para reescrevê-lo.

bea query "BQL" executa uma consulta Beancount. Omitir BQL lê consultas de stdin ou abre o shell quando stdin é um terminal. Use .exit, exit ou quit para fechar o shell. A tabela padrão do BQL tem uma linha por lançamento. Tabelas de consulta mantêm a precisão.

Selecione o livro-caixa antes do comando, por exemplo bea --file main.bean query -f csv -o balances.csv "SELECT account, sum(position) GROUP BY account". O --json global usa o envelope do produto com data.rows e data.columns; é distinto da renderização CSV. Na versão publicada 0.2.0, use redirecionamento de shell para salvar JSON, como bea --json query "SELECT account, sum(position) GROUP BY account" > result.json: os -o e -m da consulta não se aplicam ao JSON naquela versão.

Ferramentas nativas e recursos opcionais​

bea doctor context main.bean 42 mostra o contexto da transação na linha 42. bea doctor --help lista os outros comandos de diagnóstico. bea example -o example.bean cria um histórico de exemplo. bea treeify accounts.txt renderiza nomes hierárquicos a partir de um arquivo de texto; omita o arquivo para ler de stdin. Esses comandos encaminham argumentos nativos. Os exemplos acima nomeiam esses argumentos explicitamente.

Habilite ferramentas opcionais uma vez com bea engine enable beanprice para busca de cotações ou bea engine enable beangulp para fluxos de trabalho de importadores. A habilitação precisa de acesso à rede; o Beangulp também precisa da biblioteca libmagic do sistema. Use bea engine status para inspecionar a disponibilidade. bea price --help e bea ingest --help descrevem suas interfaces. bea import --csv e bea add price não precisam de nenhum recurso opcional.

Inclusões de preços gerenciados​

Live Prices é um fluxo de trabalho separado de inclusão gerenciada. Livros-caixa hospedados resolvem URLs de preços suportadas; versões compatíveis do bea também suportam inclusões gerenciadas e exportações de preços locais. Consulte o guia de preços gerenciados específico da versão se sua versão instalada não reconhecer esses comandos.

A CLI resolve URLs gerenciadas da lista de permissões sem enviar credenciais e recusa redirecionamentos. Um feed que redireciona para um login hospedado fica, portanto, indisponível para uma busca local nova; entrar no site não autentica a requisição de preços da CLI. Inspecione price status para erros de origem. Use dados em cache, um feed suportado acessível ou preços locais datados conforme apropriado.

price export escreve arquivos de feed em prices/ e reescreve inclusões para caminhos relativos locais. Beancount, Fava e Beanquery upstream podem carregar essa cópia exportada. Uma fonte indisponível recusa a exportação, a menos que --allow-errors seja usado, o que pode deixar seu marcador de origem sem preços.

Seu próprio preço datado substitui um preço gerenciado para a mesma data e par. As entradas de feed são somente leitura. Atualizações falhas mantêm uma revisão validada anteriormente, que pode estar desatualizada. Outros argumentos para bea price ainda são encaminhados ao Beanprice; se um arquivo de tarefa de cotação for chamado status, passe ./status para distingui-lo do subcomando.

O Homebrew instala tanto a CLI quanto seu motor gerenciado. Com o PyPI, o primeiro comando com suporte do motor baixa as dependências fixadas; mantenha uv no PATH e permita acesso à rede nessa primeira execução. Comandos locais posteriores reutilizam o motor offline. Clientes instalam apenas beancount-io, sem pacote Beancount separado nem scripts de console nativos para gerenciar.

Relatórios financeiros​

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

bea balance [ACCOUNT...] imprime subárvores de saldo para contas que correspondem a substrings sem distinção de maiúsculas/minúsculas, ou o livro-caixa inteiro quando você não nomeia nenhuma. Ele aceita --conversion / -x, --time / -t e --allow-errors, e não tem opção de intervalo ou conta.

Filtros de tempo incluem um 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 por padrão a única moeda operacional do livro-caixa. Caso contrário, usa units por padrão, mantendo os ativos separados. at_cost usa custos de aquisição. at_value usa valores de mercado com fallback para custo.

Uma conversão de moeda explícita precisa de preços na 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 as moedas de origem e marcam totais combinados como indisponíveis. O JSON inclui valuation: "partial", missing_prices e missing_price_dates. Os 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. O lucro líquido é -(income + expenses), positivo para um ganho. A mesma convenção se aplica às linhas de período da demonstração de resultados. A reconciliação do balanço patrimonial é derivada para o relatório; não escreve diretivas. equity_reconciled identifica se uma reconciliação completa está disponível.

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

Assistência opcional por IA​

bea ask precisa tanto do extra ask quanto das credenciais do Beancount.io obtidas via bea cloud login ou BEA_TOKEN. A instalação padrão do Homebrew omite as 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 via uv, instale beancount-io[ask] e execute bea ask diretamente. --print / -p responde uma vez e encerra. Caso contrário, uma sessão de terminal é interativa, e uma pergunta opcional pré-preenche sua entrada. O uso não interativo exige uma pergunta. O modo JSON não é suportado.

As 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. Escritas interativas são pré-visualizadas, confirmadas, validadas e gravadas atomicamente. Elas aceitam --into. O --yes global não concede permissão de escrita à IA. O modo de resposta única não aplica escritas propostas.

O 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 têm precedência por nome. Cada arquivo precisa dos campos YAML name e description. Instruções completas são carregadas sob demanda. Para o layout de arquivos e um exemplo prático, consulte Estenda o bea ask com habilidades.

Razões hospedadas​

Com o --json global, bea cloud status, bea cloud ledger list, bea cloud ledger show, bea cloud ledger create e bea cloud ledger delete emitem o envelope padrão. O login exige interação; logout e clone bem-sucedidos não retornam um objeto de sucesso JSON.

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-caixa hospedado ainda existe. Comandos locais não fazem upload automático do seu livro-caixa. Não há opção global --ledger.

JSON e códigos de saída​

O --json global coloca resultados bem-sucedidos em stdout:

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

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

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

Verifique error.result antes de tentar novamente uma mutação. Um lote parcial pode gravar linhas aceitas, a formatação recursiva pode alterar arquivos válidos, e criar-e-clonar pode criar um livro-caixa hospedado antes de encerrar com código diferente de zero. Para um script que lê esse envelope com jq e ramifica nesses códigos, consulte Automatize a contabilidade com o bea.

Os prompts da CLI são desabilitados por --no-input, modo JSON, stdin não terminal ou CI verdadeiro. A exclusão na nuvem ainda precisa de --yes explícito. As importações precisam de uma decisão explícita de duplicata quando correspondências precisam de revisão.

Exceções de saída: doctor, example, treeify, invocações de price encaminhadas ao Beanprice e ingest preservam a saída nativa e o status de saída, mesmo com o --json global; o envelope e as categorias de saída acima não descrevem esses resultados encaminhados. O ask rejeita JSON; o login na nuvem precisa de interação; logout e clone bem-sucedidos na nuvem não retornam um objeto de sucesso JSON. Ajuda, versão e conclusão automática mantêm saída em texto. upgrade pode transmitir a saída de seu gerenciador de pacotes para 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. O estado de configuração inclui credenciais, histórico de prompts do Ask, habilidades do usuário, caminhos de importadores memorizados e caches de verificação de atualização. Os bloqueios de escrita ficam em locks/ no diretório de cache, fora do diretório do seu livro-caixa.

bea upgrade --check informa 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 são executadas no máximo uma vez por dia em cópias instaladas interativas; o upgrade --check explícito ainda é executado quando o notificador passivo está desabilitado.

Desinstale com o gerenciador correspondente: brew uninstall bea, uv tool uninstall beancount-io ou pipx uninstall beancount-io. Seus arquivos de livro-caixa e a configuração do 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.