Avvio rapido della CLI di Beancount

Crea un libro mastro locale e registra il tuo primo acquisto con bea, lo strumento da linea di comando di Beancount.io. La contabilità locale non richiede un account Beancount.io.

Questa guida inizia con 1.000 USD in conto corrente. Dopo un acquisto di 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 superiore. Homebrew installa il motore contabile durante l'installazione. Con PyPI, tieni disponibile uv: il primo comando locale scarica il motore gestito, poi i comandi successivi lo riutilizzano offline. Non è necessario installare Beancount separatamente.

2. Crea il tuo libro mastro​

Scegli una nuova directory. Questo esempio crea main.bean dentro ~/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 conti comuni di conto corrente, risparmio, contanti, carta di credito, entrate e spese. Il saldo iniziale si compensa contro Equity:OpeningBalances.

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

init non sovrascrive mai un libro mastro esistente. I nuovi file sono privati su sistemi POSIX: solo il proprietario può leggerli e scriverli. Per condividere con il tuo gruppo locale di utenti, cambia esplicitamente i permessi con chmod 640 main.bean.

Per una configurazione guidata, invece, esegui bea init ~/my-books in un terminale. La procedura guidata chiede la tua valuta, la data di inizio storica 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 USD del conto. Beancount compila l'altra registrazione come -12.50 USD. Puoi omettere --date per acquisti fatti oggi.

Ogni aggiunta viene verificata rispetto al libro completo prima che il file venga sostituito. Un conto sconosciuto o una transazione squilibrata produce un errore con suggerimenti.

4. Controlla il risultato​

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

La lista delle transazioni mostra prima le voci più recenti, con i loro importi. Il bilancio mostra 987,50 USD in conto corrente.

Per verificare quell'importo direttamente:

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

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

bea --json list transaction --limit 10

5. Mantieni i tuoi libri in ordine​

Esegui bea check dopo aver modificato il file manualmente. Esegui bea format -i main.bean per allineare le sue colonne in loco. Senza -i, il testo formattato viene inviato a stdout e il file rimane invariato. Usa bea format main.bean --check quando uno script deve fallire se è necessaria la formattazione.

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

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

La root viene selezionata da --file, poi BEA_FILE, quindi main.bean nella directory di lavoro. Le opzioni globali vanno prima del comando. La formattazione prende il proprio argomento file o directory.

Continua con i tuoi record​

• Importa un export bancario con anteprima e revisione dei duplicati.
• Affida a un agente esterno due compiti di contabilità con prompt copiabili ed equivalenti CLI.
• Confronta cinque strumenti di contabilità per agenti AI su installazione, autenticazione, ambito, dati, anteprima, output e ripetizioni, con fonti datate.
• Cerca comandi e opzioni per conti, saldi, investimenti, report e automazione.
• Organizza un registro su più file. Usa --into per scrivere un file incluso mentre convalidi contro la root.
• Usa l'interfaccia browser se preferisci i moduli ai comandi da terminale.

Controlla 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 ispezionare le opzioni disponibili nella tua versione installata.