Beancount-CLI-Referenz

Nutzen Sie diese Referenz, um bea-Befehle und deren Verhalten nachzuschlagen. Für Ihr erstes Hauptbuch folgen Sie dem CLI-Schnellstart. Für Bankdateien verwenden Sie den Import-Walkthrough.

Befehle im Überblick​

Globale Optionen und Pfade​

Globale Optionen stehen vor dem Befehl:

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

init erstellt sein eigenes Verzeichnis-/Dateiziel und ignoriert BEA_FILE. Es akzeptiert die globale Option --file anstelle seines Verzeichnisarguments. format verwendet sein eigenes Positionsziel, standardmäßig das Arbeitsverzeichnis. Globale --file wählt nicht das Formatierungsziel.

Ein Hauptbuch erstellen​

bea init [DIRECTORY] verwendet standardmäßig das aktuelle Verzeichnis. Ein Verzeichnis erstellt main.bean; ein .bean- oder .beancount-Pfad benennt die neue Datei direkt.

Die Vorlage eröffnet Assets:Checking, Assets:Savings, Assets:Cash, Liabilities:CreditCard, Income:Salary, Income:Interest, Expenses:Groceries, Expenses:Dining, Expenses:Rent, Expenses:Transport, Expenses:Utilities, Expenses:Fees und Equity:OpeningBalances.

Eröffnungssalden werden gegen Equity:OpeningBalances verrechnet. Schulden sind negativ. Währungseingaben werden in Großbuchstaben umgewandelt. Benutzerdefinierte Symbole sind erlaubt; ein Symbol, das nicht aus drei Großbuchstaben besteht, löst eine Tippfehlerwarnung aus. Dies ist keine ISO-Währungsregisterprüfung.

Bestehende Dateien werden niemals überschrieben. Neue Dateien verwenden nur Eigentümerberechtigungen, Modus 0600 auf POSIX. Spätere add-, import- und format-Schreibvorgänge erhalten Berechtigungen und respektieren schreibgeschützte Ziele.

Transaktionen hinzufügen​

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'

Eine Buchung kann ihren Betrag weglassen. Nummerierte Buchungen können die Währung weglassen, wenn ein Konto eine erlaubte Währung hat oder das Hauptbuch eine kompatible Betriebswährung hat. Andernfalls geben Sie das Symbol an.

Die native Buchungssyntax unterstützt Arithmetik wie 84/2 EUR, Kosten wie {100 USD}, Gesamtkosten {{1000 USD}} und Preise @ oder @@. Verwenden Sie Dezimalbeträge wie 1000, nicht Exponentennotation wie 1e3.

Ein Währungsumtausch benötigt den tatsächlichen Transaktionskurs. Buchen Sie beispielsweise 100 EUR @ 1.08 USD auf ein in EUR geführtes Konto und -108 USD auf das Girokonto. Ein Investmentkauf kann 2 AAPL {100 USD} auf ein in AAPL geführtes Konto und -200 USD auf das Girokonto buchen. Fügen Sie datierte price-Notierungen hinzu, wenn Berichte Marktbewertungen benötigen.

Metadaten akzeptieren nackte Zeichenketten wie --meta 'receipt:IMG_42.jpg'. Native Zahlen, boolesche Werte, Daten und Beträge behalten ihre Typen. Beispiele sind --meta 'reviewed:TRUE', --meta 'received:2026-08-03' und --meta 'fee:2.50 USD'. Innere Anführungszeichen erzwingen eine Zeichenkette: --meta 'code:"1234"'. Schlüssel müssen eindeutig sein; filename und lineno sind reserviert.

Einzelne Adds, Massen-Adds und Imports ersetzen Zeilenumbrüche in Zahlungsempfängern, Beschreibungen und Zeichenketten-Metadaten durch Leerzeichen. Anführungszeichen und Backslashes behalten ihren Inhalt.

Andere Direktiven hinzufügen​

Alle diese Befehle erfordern --date YYYY-MM-DD. Sie akzeptieren auch --into FILE und --allow-errors.

Kontonamen haben einen großgeschriebenen Stamm und durch Doppelpunkte getrennte Segmente. Jedes Unterkonto beginnt mit einem Großbuchstaben oder einer Ziffer. Beancount unterstützt Unicode-Buchstaben und konfigurierte Stammnamen.

Ein Saldo prüft das Konto zu Beginn seines Datums. Toleranzsyntax wird unterstützt, z. B. --amount "1538 ~ 1 EUR". Die Toleranz muss nicht negativ sein.

Verwenden Sie add balance --pad-from Equity:OpeningBalances, um einen Pad und seine Saldenprüfung zusammen zu schreiben. Der Pad standardisiert auf den vorherigen Tag; --pad-date kann einen anderen früheren Tag wählen. Beide Konten müssen aktiv sein. Ein eigenständiger Pad benötigt eine spätere Saldenprüfung, um ihn zu verbrauchen. --allow-errors kann diesen Zwischenzustand bereitstellen, kann aber kein ungültiges Pad-Konto umgehen.

add price überspringt ein exaktes Datum/Gut/Preis-Duplikat über den Root und seine Includeds. Es beendet mit 0 und identifiziert den vorhandenen Speicherort. Unterschiedliche Daten oder Preise sind neue Hinzufügungen.

Dokumentpfade werden relativ zur Datei aufgelöst, die die Direktive enthält. Mit --into years/2026.bean bedeutet --filename receipt.pdf years/receipt.pdf, nicht eine Datei neben dem Arbeitsverzeichnis Ihrer Shell.

Benutzerdefinierte Wertarten sind text, number, amount, account, bool und date. Beispielsweise kann ein Budget --value "text:travel" --value "amount:500 USD" verwenden.

Massen-JSON-Eingabe​

bea add transactions --from transactions.json akzeptiert ein JSON-Array:

[
  {
    "date": "2026-08-04",
    "narration": "Groceries",
    "postings": [
      { "account": "Expenses:Groceries", "amount": "45.00 USD" },
      { "account": "Assets:Checking" }
    ],
    "meta": { "receipt": "R-43", "reviewed": true }
  }
]

Jede Transaktion erfordert date und postings. Optionale Felder sind flag, payee, narration, tags, links und meta.

Eine Buchung verwendet entweder amount oder units, z. B. {"number":"45.00","currency":"USD"}. Lassen Sie beide für die Ausgleichsbuchung weg. Buchungsfelder umfassen auch cost, price, flag und meta. Kosten enthalten number und currency, mit optionalem date und label. Preise enthalten number und currency.

Verwenden Sie Zeichenketten für Dezimalzahlen. Metadaten verwenden gewöhnliche Zeichenketten und boolesche Werte oder getaggte Werte wie {"kind":"number","value":"1.125"}, {"kind":"date","value":"2026-08-04"} und {"kind":"amount","number":"2.50","currency":"USD"}. Der optionale Transaktions-source-Speicherort wird niemals als Metadaten geschrieben.

Der Standard ist ein atomarer Stapel: Jede abgelehnte Zeile lässt das Hauptbuch unverändert und beendet mit 1. --partial schreibt eine gültige Teilmenge und beendet weiterhin mit 1, wenn Zeilen abgelehnt werden. JSON-Fehler beschreiben das Ergebnis in error.result; Zeilenindizes dort sind nullbasiert. Menschliche Zeilennummern sind einsbasiert.

Massen-Add akzeptiert --into und --allow-errors. Es dedupliziert nicht. Verwenden Sie bea import für die Überprüfung von Bankexporten.

Aufgeteilte Hauptbücher und Schreibsicherheit​

Halten Sie --file auf den Root gerichtet. Fügen Sie --into hinzu, um eine vorhandene enthaltene Datei auszuwählen:

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

Das Ziel ist relativ zum Root-Verzeichnis. Es muss bereits enthalten sein; das Benennen einer nicht verwandten Datei wird verweigert. Add-Befehle, Imports und interaktive KI-Schreibvorgänge unterstützen diese Trennung.

Schreibvorgänge validieren das vollständige Kandidaten-Hauptbuch, einschließlich Plugins und Kostenlos-Buchung. Eine gleichzeitige Änderung am Root oder seinem Include-Graphen beendet mit 4. Ein schreibgeschütztes Ziel beendet mit 3. Erfolgreiche Hinzufügungen verwenden dieselbe Ausrichtung wie bea format, was vorhandene Spalten in diesem Ziel neu ausrichten kann.

Direktiven auflisten​

bea list TYPE unterstützt die elf Typen: transaction, open, close, balance, pad, note, event, price, commodity, document und custom.

Andere Direktiventypen behalten die chronologische Reihenfolge. Eine kontogefilterte Transaktionstabelle beschriftet ihre Betragsspalte mit MATCHING POSTING AMOUNTS. Details und JSON enthalten weiterhin alle Buchungen jeder ausgewählten Transaktion. Details rendern geladene Einträge, einschließlich abgeleiteter Beträge; sie sind keine rohen Quelltextauszüge.

Prüfen, formatieren und abfragen​

bea check validiert den Root und Includeds. Es beendet mit 1 bei Hauptbuchfehlern und hat keine --allow-errors-Option. Abfragen, Listen und Berichte lehnen ebenfalls Ladefehler ab, es sei denn, Sie übergeben explizit deren --allow-errors-Option.

Die Formatierung nimmt eine .bean/.beancount-Datei oder ein Verzeichnis. Ein Verzeichnis wird rekursiv durchsucht.

Jeder Modus meldet Syntaxfehler nach Datei und Zeile, überspringt diese Dateien und beendet mit 1. Ein rekursiver normaler Lauf kann die gültigen Dateien weiterhin formatieren. JSON meldet scanned, formatted, skipped, dry_run und check unter error.result bei Fehlern.

bea query "BQL" führt eine Beancount-Abfrage aus. Das Weglassen von BQL öffnet eine interaktive Shell; exit oder quit schließt sie. Ein Abfrageargument ist unbeaufsichtigt erforderlich. Die Standardtabelle von BQL hat eine Zeile pro Buchung. Abfragetabellen behalten Präzision. Leere Ergebnisse geben (no rows) auf stderr aus; JSON gibt leere data.rows und Spaltenmetadaten in data.columns zurück.

Finanzberichte​

Alle Berichte akzeptieren --conversion / -x, --time / -t, --account / -a und --allow-errors. Alle außer der Probebilanz akzeptieren auch --interval / -i: standardmäßig monthly, oder quarterly, yearly, weekly oder daily.

Zeitfilter umfassen ein Jahr, einen Monat, ein Datum, ein Quartal, eine Woche oder einen Bereich, z. B. 2026, 2026-08, 2026-08-31, 2026-Q3, 2026-W32 oder "2026-01 - 2026-08". Relative Zeiträume umfassen year, quarter, month, week, day und Offsets wie month-1. Kontofilter behalten jede Buchung einer übereinstimmenden Transaktion.

Die Konvertierung standardisiert auf die einzige Betriebswährung des Hauptbuchs. Andernfalls standardisiert sie auf units, wobei Waren getrennt bleiben. at_cost verwendet Anschaffungskosten. at_value verwendet Marktwerte mit Kosten-Fallback.

Eine explizite Währungskonvertierung benötigt Preise am oder vor jedem Bewertungsdatum, einschließlich Intervalldaten. Ein fehlender Preisfehler benennt die tatsächliche Lücke, z. B. No EUR → USD price on or before 2026-01-31. Ein späteres Angebot kann eine frühere Lücke nicht füllen. Fügen Sie einen historisch angemessenen Preis hinzu, verwenden Sie --conversion units oder wählen Sie --allow-errors, um Teilwerte zu prüfen.

Teilberichte bewahren Quellwährungen und markieren kombinierte Gesamtsummen als nicht verfügbar. JSON umfasst valuation: "partial", missing_prices und missing_price_dates. Betroffene Nettogewinn-/Nettovermögenssummen sind null in der angeforderten Währung.

Einnahmen, Verbindlichkeiten und Eigenkapital verwenden normalerweise negative Beancount-Vorzeichen. Der Nettogewinn ist -(income + expenses), positiv für einen Gewinn. Dieselbe Konvention gilt für Zeitraumszeilen der Gewinn- und Verlustrechnung. Die Bilanzabstimmung wird für den Bericht abgeleitet; er schreibt keine Direktiven. equity_reconciled identifiziert, ob eine vollständige Abstimmung verfügbar ist.

Berichts-JSON identifiziert auch den Zeitraum, das exklusive Enddatum, das Stichtagsdatum, die Konvertierung, den Kontofilter und den Validierungsstatus des Hauptbuchs. Prüfen Sie diese Felder, bevor Sie Gesamtsummen vergleichen.

Optionale KI-Unterstützung​

bea ask benötigt sowohl das ask-Extra als auch Beancount.io-Anmeldeinformationen von bea cloud login oder BEA_TOKEN. Die Standard-Homebrew-Installation lässt KI-Abhängigkeiten aus. Homebrew-Benutzer können ausführen:

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

Für eine uv-Installation installieren Sie beancount-io[ask] und führen Sie bea ask direkt aus. --print / -p antwortet einmal und beendet sich. Andernfalls ist eine Terminalsitzung interaktiv, und eine optionale Frage füllt ihre Eingabe vor. Nicht-interaktive Nutzung erfordert eine Frage. Der JSON-Modus wird nicht unterstützt.

Abfragen werden lokal ausgeführt. Fragen, Skill-Kontext und Tool-Ergebnisse gehen an den gehosteten Beancount.io-KI-Dienst. Interaktive Schreibvorgänge werden in der Vorschau angezeigt, bestätigt, validiert und atomar geschrieben. Sie akzeptieren --into. Globale --yes gewährt keine KI-Schreibberechtigung. Der Ein-Antwort-Modus wendet vorgeschlagene Schreibvorgänge nicht an.

Ask liest NAME/SKILL.md aus .agents/skills/ im Arbeitsverzeichnis und aus skills/ im Benutzerkonfigurationsverzeichnis. Projektdefinitionen gewinnen nach Namen. Jede Datei benötigt YAML-Felder name und description. Vollständige Anweisungen werden bei Bedarf geladen.

Gehostete Hauptbücher​

Die Erstellung akzeptiert auch --clone und --dir. Git- und SSH-Zugriff sind zum Klonen erforderlich. Wenn das Klonen nach der Erstellung fehlschlägt, existiert das gehostete Hauptbuch weiterhin. Lokale Befehle laden Ihr Hauptbuch nicht automatisch hoch. Es gibt keine globale --ledger-Option.

JSON und Exit-Codes​

Globale --json platziert erfolgreiche Ergebnisse auf stdout:

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

bea ist die installierte Version; data hängt vom Befehl ab. Ziele identifizieren eine Datei, ein Verzeichnis, einen Server oder kein Ziel. Enthaltene Schreibvorgänge identifizieren auch into. Dezimalbeträge und Daten verwenden Zeichenketten. Begrenzte Listen umfassen limit und truncated.

Fehler schreiben {"error":{"category":"validation","message":"…","exit_code":1}} auf stderr. Der Fehler kann auch details, result, eine Backend-request_id und einen traceback mit --debug enthalten.

Prüfen Sie error.result, bevor Sie eine Mutation erneut versuchen. Ein Teilstapel kann akzeptierte Zeilen schreiben, rekursive Formatierung kann gültige Dateien ändern, und Erstellen-und-Klonen kann ein gehostetes Hauptbuch erstellen, bevor mit Nicht-Null beendet wird.

CLI-Eingabeaufforderungen werden durch --no-input, JSON-Modus, Nicht-Terminal-stdin oder wahrheitsgemäßes CI deaktiviert. Cloud-Löschung benötigt weiterhin explizites --yes. Imports benötigen eine explizite Duplikatentscheidung, wenn Übereinstimmungen geprüft werden müssen.

Ausnahmeausgaben: Ask lehnt JSON ab; Cloud-Login benötigt Interaktion; erfolgreiche Cloud-Abmeldung und Klonen geben kein JSON-Erfolgsobjekt zurück. Hilfe, Version und Vervollständigung behalten Textausgabe. upgrade kann die Ausgabe seines Paketmanagers auf stderr streamen, einschließlich im JSON-Modus.

Einstellungen, Updates und gespeicherter Zustand​

Wahrheitsgemäße Werte sind 1, true, yes und on, Groß-/Kleinschreibung und umgebende Leerzeichen werden ignoriert. Konfigurationszustand umfasst Anmeldeinformationen, Ask-Eingabeaufforderungsverlauf, Benutzer-Skills, gespeicherte Importer-Pfade und Update-Prüf-Caches. Schreibsperren befinden sich unter locks/ des Cache-Verzeichnisses, außerhalb Ihres Hauptbuchverzeichnisses.

bea upgrade --check meldet Versionen und die Installationsmethode ohne Upgrade. bea upgrade ruft brew upgrade bea, uv tool upgrade beancount-io oder pipx upgrade beancount-io auf. Editierbare Installationen erhalten manuelle Update-Anleitung. Passive Prüfungen laufen höchstens einmal täglich in interaktiven installierten Kopien; explizites upgrade --check läuft auch, wenn der passive Benachrichtiger deaktiviert ist.

Deinstallieren Sie mit dem passenden Manager: brew uninstall bea, uv tool uninstall beancount-io oder pipx uninstall beancount-io. Ihre Hauptbuchdateien und Benutzerkonfiguration bleiben erhalten.

Häufige Lösungen​

Verwenden Sie bea COMMAND --help, um Ihre installierte Version zu prüfen. Die Quellrepository-Referenz enthält zusätzliche Beispiele und die genauen Direktivmodell-Definitionen.