Riferimento CLI di Beancount

Usa questo riferimento per consultare i comandi bea e il loro comportamento. Per il tuo primo registro, segui la guida rapida CLI. Per i file bancari, usa il percorso guidato per l'importazione.

Comandi a colpo d'occhio​

Opzioni globali e percorsi​

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 --file globale al posto dell'argomento della directory. format usa la propria destinazione posizionale, con default la directory di lavoro. --file globale non sceglie la destinazione di formattazione.

Crea un registro​

bea init [DIRECTORY] usa come default 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, e Equity:OpeningBalances.

I saldi di apertura sono compensati con Equity:OpeningBalances. Il debito è negativo. L'input della valuta viene convertito in maiuscolo. I simboli personalizzati sono consentiti; un simbolo che non è di tre lettere maiuscole attiva un avviso di errore di battitura. Questo non è un controllo del registro valutario ISO.

I file esistenti non vengono mai sovrascritti. I nuovi file usano permessi solo proprietario, modalità 0600 su POSIX. Le successive scritture di add, import e format preservano i permessi e rispettano le destinazioni di sola lettura.

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'

Una registrazione può omettere il proprio importo. Le registrazioni numerate possono omettere la valuta quando un conto ha una sola valuta consentita o il registro ha una sola valuta operativa compatibile. Altrimenti, fornisci il simbolo.

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

Un cambio 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 su conto corrente. Un acquisto di investimento può registrare 2 AAPL {100 USD} su un conto aperto in AAPL e -200 USD su conto corrente. Aggiungi quotazioni price datate quando i report necessitano della valutazione di mercato.

I metadati accettano stringhe semplici come --meta 'receipt:IMG_42.jpg'. Numeri nativi, booleani, date e importi mantengono i loro tipi. Gli 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 riservate.

Le aggiunte singole, le aggiunte in blocco e le importazioni sostituiscono i ritorni a capo in pagatori, descrizioni e metadati stringa con spazi. Virgolette e barre rovesciate mantengono i loro contenuti.

Aggiungi altre direttive​

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

I nomi dei conti hanno una radice 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 ha come default 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ò bypassare un conto pad non valido.

add price salta un duplicato esatto di data/merce/prezzo attraverso la radice e i suoi include. Esce con codice 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 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 blocco​

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.

Una registrazione usa amount o units, come {"number":"45.00","currency":"USD"}. Ometti entrambi per la registrazione di bilanciamento. I campi della registrazione 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 ordinarie e booleani, o valori taggati come {"kind":"number","value":"1.125"}, {"kind":"date","value":"2026-08-04"} e {"kind":"amount","number":"2.50","currency":"USD"}. La posizione opzionale source della transazione non viene mai scritta come metadato.

Il default è un lotto atomico: qualsiasi riga rifiutata lascia il registro invariato ed esce con codice 1. --partial scrive un sottoinsieme valido e esce comunque con codice 1 se alcune righe vengono rifiutate. Gli errori JSON descrivono l'esito in error.result; gli indici delle righe lì sono a base zero. I numeri di riga umani sono a base uno.

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

Registri suddivisi 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 add, le importazioni e le scritture AI interattive supportano questa separazione.

Le scritture validano l'intero registro candidato, inclusi plugin e prenotazione dei lotti di costo. Una modifica concorrente alla radice o al suo grafo di inclusione esce con codice 4. Una destinazione di sola lettura esce con codice 3. Le aggiunte riuscite usano lo stesso allineamento di bea format, che può riallineare le colonne esistenti in quella destinazione.

Elenca le 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 importo MATCHING POSTING AMOUNTS. I dettagli e il JSON includono comunque tutte le registrazioni di ogni transazione selezionata. I dettagli mostrano le voci caricate, inclusi gli importi dedotti; non sono estratti grezzi della sorgente.

Controlla, formatta e interroga​

bea check valida la radice e gli include. Esce con codice 1 per errori del registro e non ha l'opzione --allow-errors. Query, elenchi e report rifiutano anche errori del caricatore a meno che tu non passi esplicitamente la loro opzione --allow-errors.

La formattazione accetta un file .bean/.beancount o una directory. Una directory viene cercata ricorsivamente.

Ogni modalità segnala errori di sintassi per file e riga, salta quei file ed esce con codice 1. Un'esecuzione ricorsiva normale può comunque formattare i file validi. Il JSON riporta scanned, formatted, skipped, dry_run e check, sotto error.result in caso di errore.

bea query "BQL" esegue una query Beancount. Omettendo BQL si apre una shell interattiva; exit o quit la chiudono. Un argomento di query è richiesto in modalità non presidiata. La tabella predefinita di BQL ha una riga per registrazione. Le tabelle delle query mantengono la precisione. I risultati vuoti stampano (no rows) su stderr; il JSON restituisce un data.rows vuoto e metadati delle colonne in data.columns.

Report finanziari​

Tutti i report accettano --conversion / -x, --time / -t, --account / -a e --allow-errors. Tutti tranne il trial balance accettano anche --interval / -i: monthly come default, oppure quarterly, yearly, weekly o daily.

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 registrazione di una transazione corrispondente.

La conversione ha come default l'unica valuta operativa del registro. Altrimenti, ha come default units, mantenendo separate le merci. at_cost usa i costi di acquisizione. at_value usa i valori di mercato con un fallback al costo.

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

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

Entrate, passività e patrimonio netto usano normalmente i segni negativi di Beancount. L'utile netto è -(income + expenses), positivo per un guadagno. La stessa convenzione si applica alle righe di periodo del conto economico. La riconciliazione del bilancio è derivata per il report; non scrive direttive. 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 validazione del registro. Controlla questi campi prima di confrontare i totali.

Assistenza AI opzionale​

bea ask richiede sia l'extra ask sia le credenziali Beancount.io da bea cloud login o BEA_TOKEN. L'installazione Homebrew predefinita 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 competenze e risultati degli strumenti vanno al servizio AI ospitato di Beancount.io. Le scritture interattive vengono visualizzate in anteprima, confermate, validate e scritte in modo atomico. Accettano --into. Il --yes globale non concede il permesso di scrittura 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 utente. Le definizioni di progetto vincono per nome. Ogni file necessita dei campi YAML name e description. Le istruzioni complete vengono caricate su richiesta.

Registri ospitati​

La creazione accetta anche --clone e --dir. L'accesso Git e SSH è necessario per clonare. Se la clonazione fallisce dopo la creazione, il registro ospitato esiste ancora. I comandi locali non caricano automaticamente il tuo registro. Non esiste un'opzione globale --ledger.

JSON e codici di uscita​

Il --json globale mette i risultati riusciti su stdout:

{
  "bea": "0.1.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.

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

Controlla error.result prima di ritentare una mutazione. Un lotto parziale può scrivere righe accettate, la formattazione ricorsiva può modificare file validi e crea-e-clona può creare un registro ospitato prima di uscire con codice diverso da zero.

I prompt CLI sono disattivati da --no-input, modalità JSON, stdin non terminale o CI vero. L'eliminazione cloud richiede comunque --yes esplicito. Le importazioni richiedono una decisione esplicita sui duplicati quando le corrispondenze necessitano di revisione.

Eccezioni di output: Ask rifiuta JSON; l'accesso cloud richiede interazione; logout e clone cloud riusciti non restituiscono alcun oggetto di successo JSON. Aiuto, versione e completamento mantengono l'output testuale. upgrade può trasmettere l'output del suo gestore di pacchetti su stderr, incluso 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, competenze utente, percorsi di importazione ricordati e cache di controllo aggiornamenti. I blocchi di scrittura vivono sotto locks/ nella directory cache, fuori dalla tua directory del registro.

bea upgrade --check riporta versioni e 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 eseguito anche quando l'indicatore passivo è disattivato.

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

Correzioni comuni​

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