Riferimento CLI Beancount

Usa questo riferimento per consultare i comandi bea e il loro comportamento. Per il tuo primo registro, segui la guida rapida alla CLI. Per chiudere un mese intero dall'inizio alla fine, segui Il tuo primo mese con bea. Per i file bancari, usa la guida all'importazione.

Comandi a colpo d'occhio​

Opzioni e percorsi globali​

Le opzioni globali vanno prima del comando:

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

init crea la propria directory/file di destinazione e ignora BEA_FILE. Accetta l'opzione globale --file al posto del suo argomento di directory. format usa il proprio target posizionale. Fornisci un nome di file o una directory. L'opzione globale --file non sceglie il target della formattazione.

Crea un libro mastro​

bea init [DIRECTORY] usa per impostazione predefinita la directory corrente. Una directory crea main.bean; un percorso .bean o .beancount nomina direttamente il nuovo file.

Il modello apre 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 ed Equity:OpeningBalances.

I saldi di apertura vengono compensati su Equity:OpeningBalances. Il debito è negativo. L'input della valuta viene convertito in maiuscolo. Sono ammessi simboli personalizzati; un simbolo che non è composto da tre lettere maiuscole attiva un avviso di errore di battitura. Non è una verifica del registro valutario ISO.

I file esistenti non vengono mai sovrascritti. I nuovi file usano permessi riservati al proprietario, modalità 0600 su POSIX. Le successive scritture di aggiunta e importazione preservano i permessi e rispettano le destinazioni di sola lettura. La formattazione sul posto usa il formattatore nativo e segnala i propri errori di filesystem.

Aggiungi transazioni​

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'

Un posting può omettere il proprio importo. I posting numerati possono omettere la valuta quando un conto ha una sola valuta ammessa o il registro ha una sola valuta operativa compatibile. Altrimenti, fornisci il simbolo.

La sintassi nativa dei posting supporta aritmetica come 84/2 EUR, costi come {100 USD}, costi totali {{1000 USD}} e prezzi @ o @@. Usa importi decimali come 1000, non la notazione esponenziale come 1e3.

Un cambio di valuta necessita del suo tasso di transazione effettivo. Ad esempio, registra 100 EUR @ 1.08 USD su un conto aperto in EUR e -108 USD sul conto corrente. Un acquisto di investimento può registrare 2 AAPL {100 USD} su un conto aperto in AAPL e -200 USD sul conto corrente. Aggiungi quotazioni price con data quando i report richiedono una valutazione di mercato.

I metadati accettano stringhe semplici come --meta 'receipt:IMG_42.jpg'. Numeri nativi, valori booleani, date e importi mantengono i loro tipi. Esempi includono --meta 'reviewed:TRUE', --meta 'received:2026-08-03' e --meta 'fee:2.50 USD'. Le virgolette interne forzano una stringa: --meta 'code:"1234"'. Le chiavi devono essere distinte; filename e lineno sono riservati.

Le aggiunte singole, le aggiunte in blocco e le importazioni sostituiscono le interruzioni di riga in controparti, narrazioni e metadati stringa con spazi. Le virgolette e le barre rovesciate mantengono i loro contenuti.

Aggiungere altre direttive​

Tutti questi comandi richiedono --date YYYY-MM-DD. Accettano anche --into FILE e --allow-errors.

I nomi dei conti hanno una radice con iniziale maiuscola e segmenti separati da due punti. Ogni sottoconto inizia con una lettera maiuscola o una cifra. Beancount supporta lettere Unicode e nomi di radice configurati.

Un saldo verifica il conto all'inizio della sua data. La sintassi di tolleranza è supportata, come --amount "1538 ~ 1 EUR". La tolleranza deve essere non negativa.

Usa add balance --pad-from Equity:OpeningBalances per scrivere insieme un pad e la sua asserzione di saldo. Il pad usa per impostazione predefinita il giorno precedente; --pad-date può selezionare un altro giorno precedente. Entrambi i conti devono essere attivi. Un pad autonomo necessita di un saldo successivo per essere consumato. --allow-errors può preparare quello stato intermedio ma non può aggirare un conto pad non valido.

add price salta un duplicato esatto data/commodity/prezzo tra la radice e i suoi include. Esce con 0 e identifica la posizione esistente. Date o prezzi diversi sono nuove aggiunte.

I percorsi dei documenti si risolvono accanto al file che contiene la direttiva. Con --into years/2026.bean, --filename receipt.pdf significa years/receipt.pdf, non un file accanto alla directory di lavoro della tua shell.

I tipi di valore personalizzati sono text, number, amount, account, bool e date. Ad esempio, un budget può usare --value "text:travel" --value "amount:500 USD".

Input JSON in massa​

bea add transactions --from transactions.json accetta un 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 }
  }
]

Ogni transazione richiede date e postings. I campi opzionali sono flag, payee, narration, tags, links e meta.

Un posting usa amount o units, come {"number":"45.00","currency":"USD"}. Ometti entrambi per il posting di bilanciamento. I campi del posting includono anche cost, price, flag e meta. I costi contengono number e currency, con date e label opzionali. I prezzi contengono number e currency.

Usa stringhe per i decimali. I metadati usano stringhe e valori booleani ordinari, oppure valori con tag come {"kind":"number","value":"1.125"}, {"kind":"date","value":"2026-08-04"} e {"kind":"amount","number":"2.50","currency":"USD"}. La posizione source opzionale della transazione non viene mai scritta come metadato.

L'impostazione predefinita è un batch atomico: qualsiasi riga rifiutata lascia il registro invariato ed esce con 1. --partial scrive un sottoinsieme valido ed esce comunque con 1 se alcune righe vengono rifiutate. Gli errori JSON descrivono l'esito in error.result; gli indici di riga sono basati su zero. I numeri di riga umani sono basati su uno.

L'aggiunta in blocco accetta --into e --allow-errors. Non elimina i duplicati. Usa bea import per la revisione delle esportazioni bancarie.

Registri separati e sicurezza di scrittura​

Mantieni --file puntato alla radice. Aggiungi --into per selezionare un file incluso esistente:

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

La destinazione è relativa alla directory radice. Deve essere già inclusa; nominare un file non correlato viene rifiutato. I comandi di aggiunta, le importazioni e le scritture AI interattive supportano questa separazione.

Le scritture convalidano il registro candidato completo, inclusi plugin e booking dei lotti di costo. Una modifica concorrente alla radice o al suo grafo di include esce con 4. Una destinazione di sola lettura esce con 3. Le aggiunte riuscite allineano solo le nuove righe. I byte esistenti rimangono invariati. Usa bea format -i PATH quando vuoi riallineare l'intero file.

Elenca direttive​

bea list TYPE supporta gli undici tipi: transaction, open, close, balance, pad, note, event, price, commodity, document e custom.

Gli altri tipi di direttiva mantengono l'ordine cronologico. Una tabella di transazioni filtrata per conto etichetta la sua colonna importi come MATCHING POSTING AMOUNTS. I dettagli e il JSON includono comunque tutti i posting di ogni transazione selezionata. I dettagli mostrano le voci caricate, inclusi gli importi dedotti; non sono estratti grezzi del codice sorgente.

Controlla, formatta e interroga​

bea check convalida la radice e gli include. Esce silenziosamente con 0 in caso di successo e con 1 per errori nel registro. L'opzione globale --json restituisce l'envelope di convalida. Non esiste un'opzione --allow-errors per check.

Le query, gli elenchi e i report avvisano e restituiscono risultati parziali in un terminale interattivo. Le opzioni globali --strict, --json, --no-input, CI con valore vero o stdin non terminale rendono le letture rigorose. La loro opzione --allow-errors consente esplicitamente risultati parziali.

La formattazione accetta file o cerca ricorsivamente in una directory. Nel pacchetto 0.2.0 pubblicato, è richiesto un percorso nonostante l'impostazione predefinita stdin mostrata nella guida. L'opzione globale --file non sceglie il target della formattazione.

La formattazione allinea il testo; non convalida la sintassi del registro né la contabilità. Esegui bea check separatamente. Con l'opzione globale --json, seleziona -i, -o FILE, --check o --dry-run affinché stdout possa contenere l'envelope. Non reindirizzare stdout sul file di input: usa -i per riscriverlo.

bea query "BQL" esegue una query Beancount. Omettere BQL legge le query da stdin o apre la shell quando stdin è un terminale. Usa .exit, exit o quit per chiudere la shell. La tabella predefinita di BQL ha una riga per posting. Le tabelle delle query mantengono la precisione.

Seleziona il registro prima del comando, ad esempio bea --file main.bean query -f csv -o balances.csv "SELECT account, sum(position) GROUP BY account". L'opzione globale --json usa l'envelope del prodotto con data.rows e data.columns; è distinta dalla resa CSV. Nella release 0.2.0 pubblicata, usa la redirezione della shell per salvare JSON, come bea --json query "SELECT account, sum(position) GROUP BY account" > result.json: le opzioni query -o e -m non si applicano a JSON in quella release.

Strumenti nativi e funzionalità opzionali​

bea doctor context main.bean 42 mostra il contesto della transazione alla riga 42. bea doctor --help elenca gli altri comandi diagnostici. bea example -o example.bean crea uno storico di esempio. bea treeify accounts.txt visualizza nomi gerarchici da un file di testo; ometti il file per leggere da stdin. Questi comandi inoltrano argomenti nativi. Gli esempi sopra nominano esplicitamente quegli argomenti.

Abilita gli strumenti opzionali una volta con bea engine enable beanprice per il recupero delle quotazioni o bea engine enable beangulp per i flussi di lavoro degli importer. L'abilitazione richiede accesso alla rete; Beangulp richiede anche la libreria di sistema libmagic. Usa bea engine status per ispezionare la disponibilità. bea price --help e bea ingest --help descrivono le loro interfacce. bea import --csv e bea add price non necessitano di nessuna delle due funzionalità opzionali.

Include dei prezzi gestiti​

Live Prices è un flusso di lavoro separato con include gestito. I registri ospitati risolvono gli URL dei prezzi supportati; le versioni compatibili di bea supportano anche gli include gestiti e le esportazioni dei prezzi locali. Consulta la guida ai prezzi gestiti specifica per versione se la versione installata non riconosce questi comandi.

La CLI risolve gli URL gestiti in allowlist senza inviare credenziali e rifiuta i reindirizzamenti. Un feed che reindirizza a un login ospitato è quindi non disponibile per un recupero locale nuovo; accedere al sito web non autentica la richiesta dei prezzi della CLI. Ispeziona price status per gli errori delle fonti. Usa dati in cache, un feed supportato raggiungibile o prezzi locali con data, a seconda dei casi.

price export scrive i file dei feed sotto prices/ e riscrive gli include come percorsi relativi locali. Beancount upstream, Fava e Beanquery possono caricare quella copia esportata. Una fonte non disponibile rifiuta l'esportazione a meno che non si usi --allow-errors, il che può lasciare il suo indicatore di fonte senza prezzi.

Un tuo prezzo con data sovrascrive un prezzo gestito per la stessa data e coppia. Le voci dei feed sono di sola lettura. I refresh falliti mantengono una revisione precedentemente convalidata, che potrebbe essere obsoleta. Gli altri argomenti di bea price vengono comunque inoltrati a Beanprice; se un file di quote-job si chiama status, passa ./status per distinguerlo dal sottocomando.

Homebrew installa sia la CLI sia il suo engine gestito. Con PyPI, il primo comando basato sull'engine scarica le dipendenze bloccate; mantieni uv nel PATH e consenti l'accesso alla rete per quella prima esecuzione. I comandi locali successivi riutilizzano l'engine offline. I clienti installano solo beancount-io, senza alcun pacchetto Beancount separato o script di console nativi da gestire.

Report finanziari​

Tutti i report accettano --conversion / -x, --time / -t, --account / -a e --allow-errors. Tutti tranne il bilancio di verifica accettano anche --interval / -i: monthly per impostazione predefinita, oppure quarterly, yearly, weekly o daily.

bea balance [ACCOUNT...] stampa i sottoalberi dei saldi per i conti che corrispondono a sottostringhe senza distinzione tra maiuscole e minuscole, o l'intero registro quando non ne nomini nessuno. Accetta --conversion / -x, --time / -t e --allow-errors, e non accetta alcuna opzione di intervallo o conto.

I filtri temporali includono un anno, mese, data, trimestre, settimana o intervallo, come 2026, 2026-08, 2026-08-31, 2026-Q3, 2026-W32 o "2026-01 - 2026-08". I periodi relativi includono year, quarter, month, week, day e offset come month-1. I filtri per conto mantengono ogni posting di una transazione corrispondente.

La conversione usa per impostazione predefinita l'unica valuta operativa del registro. Altrimenti, usa per impostazione predefinita units, mantenendo separate le commodity. at_cost usa i costi di acquisizione. at_value usa i valori di mercato con un fallback al costo.

Una conversione esplicita di valuta necessita di prezzi alla data o prima di ogni data di valutazione, incluse le date degli intervalli. Un errore di prezzo mancante nomina la lacuna effettiva, come No EUR → USD price on or before 2026-01-31. Una quotazione successiva non può colmare una lacuna precedente. Aggiungi un prezzo storicamente appropriato, usa --conversion units o scegli --allow-errors per ispezionare i valori parziali.

I report parziali conservano le valute di origine e contrassegnano i totali combinati come non disponibili. Il JSON include valuation: "partial", missing_prices e missing_price_dates. I totali interessati di utile netto/patrimonio netto sono null nella valuta richiesta.

Ricavi, passività e patrimonio usano normalmente i segni negativi di Beancount. L'utile netto è -(income + expenses), positivo per un guadagno. La stessa convenzione si applica alle righe del periodo del conto economico. La riconciliazione dello stato patrimoniale è derivata per il report; non scrive alcuna direttiva. equity_reconciled identifica se è disponibile una riconciliazione completa.

Il JSON del report identifica anche il periodo, la data di fine esclusiva, la data di riferimento, la conversione, il filtro per conto e lo stato di convalida del registro. Controlla quei campi prima di confrontare i totali.

Assistenza AI opzionale​

bea ask necessita sia dell'extra ask sia delle credenziali Beancount.io da bea cloud login o BEA_TOKEN. L'installazione predefinita di Homebrew omette le dipendenze AI. Gli utenti Homebrew possono eseguire:

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

Per un'installazione uv, installa beancount-io[ask] ed esegui bea ask direttamente. --print / -p risponde una volta ed esce. Altrimenti, una sessione terminale è interattiva e una domanda opzionale precompila il suo input. L'uso non interattivo richiede una domanda. La modalità JSON non è supportata.

Le query vengono eseguite localmente. Domande, contesto delle skill e risultati degli strumenti vanno al servizio AI ospitato di Beancount.io. Le scritture interattive vengono visualizzate in anteprima, confermate, convalidate e scritte atomicamente. Accettano --into. L'opzione globale --yes non concede il permesso di scrittura all'AI. La modalità a risposta singola non applica le scritture proposte.

Ask legge NAME/SKILL.md da .agents/skills/ nella directory di lavoro e da skills/ nella directory di configurazione dell'utente. Le definizioni del progetto hanno la precedenza per nome. Ogni file necessita dei campi YAML name e description. Le istruzioni complete vengono caricate su richiesta. Per la struttura dei file e un esempio pratico, vedi Estendere bea ask con le skill.

Registri ospitati​

Con l'opzione globale --json, bea cloud status, bea cloud ledger list, bea cloud ledger show, bea cloud ledger create e bea cloud ledger delete emettono l'envelope standard. Il login richiede interazione; il logout e il clone riusciti non restituiscono un oggetto JSON di successo.

La creazione accetta anche --clone e --dir. Git e l'accesso SSH sono necessari per il clone. Se il clone fallisce dopo la creazione, il registro ospitato esiste comunque. I comandi locali non caricano automaticamente il tuo registro. Non esiste un'opzione globale --ledger.

JSON e codici di uscita​

L'opzione globale --json mette i risultati riusciti su stdout:

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

bea è la versione installata; data dipende dal comando. I target identificano un file, una directory, un server o nessun target. Le scritture incluse identificano anche into. Gli importi decimali e le date usano stringhe. Gli elenchi limitati includono limit e truncated.

I fallimenti scrivono {"error":{"category":"validation","message":"…","exit_code":1}} su stderr. L'errore può anche includere details, result, un request_id del backend e un traceback con --debug.

Controlla error.result prima di ritentare una mutazione. Un batch parziale può scrivere le righe accettate, la formattazione ricorsiva può modificare i file validi e create-and-clone può creare un registro ospitato prima di uscire con un codice diverso da zero. Per uno script che legge questo envelope con jq e dirama su questi codici, vedi Automatizzare la contabilità con bea.

I prompt della CLI vengono disabilitati da --no-input, dalla modalità JSON, da stdin non terminale o da CI con valore vero. L'eliminazione cloud necessita comunque di --yes esplicito. Le importazioni necessitano di una decisione esplicita sui duplicati quando le corrispondenze devono essere riviste.

Eccezioni all'output: doctor, example, treeify, le invocazioni di price inoltrate a Beanprice e ingest preservano l'output nativo e lo stato di uscita, anche con l'opzione globale --json; l'envelope e le categorie di uscita sopra non descrivono quei risultati inoltrati. Ask rifiuta JSON; il login cloud necessita di interazione; il logout e il clone cloud riusciti non restituiscono alcun oggetto JSON di successo. Guida, versione e completamento mantengono l'output testuale. upgrade può trasmettere l'output del suo gestore di pacchetti su stderr, anche in modalità JSON.

Impostazioni, aggiornamenti e stato memorizzato​

I valori veri sono 1, true, yes e on, ignorando maiuscole/minuscole e spazi circostanti. Lo stato di configurazione include credenziali, cronologia dei prompt di Ask, skill utente, percorsi degli importer memorizzati e cache dei controlli di aggiornamento. I lock di scrittura risiedono sotto locks/ nella directory di cache, all'esterno della directory del tuo registro.

bea upgrade --check segnala le versioni e il metodo di installazione senza aggiornare. bea upgrade invoca brew upgrade bea, uv tool upgrade beancount-io o pipx upgrade beancount-io. Le installazioni modificabili ricevono indicazioni di aggiornamento manuale. I controlli passivi vengono eseguiti al massimo una volta al giorno nelle copie installate interattive; upgrade --check esplicito viene comunque eseguito quando il notificatore passivo è disabilitato.

Disinstalla con il gestore corrispondente: brew uninstall bea, uv tool uninstall beancount-io o pipx uninstall beancount-io. I file del tuo registro e la configurazione utente rimangono.

Correzioni comuni​

Usa bea COMMAND --help per ispezionare la versione installata. Il riferimento del repository dei sorgenti contiene esempi aggiuntivi e le definizioni esatte del modello delle direttive.