Guida rapida alla CLI di Beancount

Crea una contabilità locale e registra il tuo primo acquisto con bea, lo strumento a riga di comando di Beancount.io. La contabilità locale non richiede un account Beancount.io.

Questa guida inizia con 1.000 USD sul conto corrente. Dopo un acquisto di un caffè da 12,50 USD, verificherai un saldo di 987,50 USD.

1. Installa il comando​

Con Homebrew su macOS o Linux:

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

Se non usi Homebrew, installa uv e usa uv tool install beancount-io. Il pacchetto Python richiede Python 3.12 o versioni successive.

2. Crea la tua contabilità​

Scegli una nuova directory. Questo esempio crea main.bean all'interno di ~/my-books:

bea --no-input init ~/my-books --currency USD --date 2026-08-01 \
  --opening-balance "Assets:Checking 1000"
cd ~/my-books

Il modello apre i conti comuni: correnti, risparmio, contanti, carta di credito, entrate e spese. Il saldo di apertura è compensato con Equity:OpeningBalances.

Per i tuoi libri contabili, scegli la data più antica che intendi registrare. Tutti i conti del modello si aprono in quella data. Il saldo di apertura deve descrivere il conto in quel giorno. Il debito della carta di credito usa un importo negativo.

init non sovrascrive mai una contabilità esistente. I nuovi file sono privati sui sistemi POSIX: solo il proprietario può leggerli e scriverli. Per condividere con il tuo gruppo di utenti locale, modifica esplicitamente i permessi con chmod 640 main.bean.

Per una configurazione guidata, esegui bea init ~/my-books in un terminale. La procedura guidata chiede la valuta, la data di inizio e il saldo del conto corrente.

3. Registra un acquisto​

bea add transaction --date 2026-08-02 --narration "Coffee" \
  --posting "Expenses:Dining 12.50" \
  --posting "Assets:Checking"

La spesa usa la valuta del conto. Beancount completa l'altra registrazione come -12.50 USD. Puoi omettere --date per gli acquisti effettuati oggi.

Ogni aggiunta viene controllata rispetto alla contabilità completa prima che il file venga sostituito. Un conto sconosciuto o una transazione non bilanciata produce un errore con indicazioni.

4. Controlla il risultato​

bea check
bea list transaction --limit 10
bea report balance-sheet

L'elenco delle transazioni mostra le voci più recenti per prime, con i relativi importi. Il bilancio mostra 987,50 USD sul conto corrente.

Per verificare direttamente tale importo:

bea query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"

Le tabelle delle query preservano la precisione del risultato. Per un output strutturato, metti il flag globale --json prima del comando:

bea --json list transaction --limit 10

5. Tieni in ordine i tuoi libri contabili​

Esegui bea check dopo aver modificato il file manualmente. Esegui bea format main.bean per allineare le colonne. Usa bea format main.bean --check quando uno script deve fallire se la formattazione non è corretta.

Per lavorare da un'altra directory, seleziona il file principale esplicitamente:

bea --file ~/my-books/main.bean check

Il file principale viene selezionato da --file, poi da BEA_FILE, poi da main.bean nella directory di lavoro. Le opzioni globali vanno prima del comando. La formattazione accetta un file o una directory come argomento.

Continua con i tuoi registri​

• Importa un export bancario con anteprima e revisione dei duplicati.
• Consulta comandi e opzioni per conti, saldi, investimenti, report e automazione.
• Organizza una contabilità su più file. Usa --into per scrivere un file incluso validando rispetto al file principale.
• Usa l'interfaccia browser se preferisci i moduli ai comandi.

Controlla gli aggiornamenti con bea upgrade --check. Esegui bea upgrade per invocare il gestore di pacchetti che ha installato la tua copia. Usa bea --help o bea add transaction --help per esaminare le opzioni disponibili nella versione installata.