Beancount-CLI-Referenz

Verwenden Sie diese Referenz, um bea-Befehle und deren Verhalten nachzuschlagen. Für Ihr erstes Ledger folgen Sie dem CLI-Schnellstart. Um einen vollständigen Monatsabschluss von Anfang bis Ende durchzuführen, arbeiten Sie Ihren ersten Monat mit bea durch. Für Bankdateien verwenden Sie die Import-Anleitung.

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 das globale --file anstelle seines Verzeichnisarguments. format verwendet sein eigenes positionales Ziel. Geben Sie einen Dateinamen oder ein Verzeichnis an. Das 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 Pfad mit .bean oder .beancount 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, Expenses:Uncategorized 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 Prüfung des ISO-Währungsregisters.

Bestehende Dateien werden niemals überschrieben. Neue Dateien verwenden nur-eigentümer-Berechtigungen, Modus 0600 auf POSIX. Spätere Add- und Import-Schreibvorgänge bewahren Berechtigungen und respektieren schreibgeschützte Ziele. In-Place-Formatierung verwendet den nativen Formatierer und meldet seine eigenen Dateisystemfehler.

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'

Ein Posten darf seinen Betrag weglassen. Nummerierte Posten dürfen die Währung weglassen, wenn ein Konto eine zulässige Währung hat oder das Ledger eine kompatible Funktionswährung hat. Andernfalls geben Sie das Symbol an.

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

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

Metadaten akzeptieren einfache Zeichenfolgen wie --meta 'receipt:IMG_42.jpg'. Native Zahlen, Booleans, 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 Zeichenfolge: --meta 'code:"1234"'. Schlüssel müssen eindeutig sein; filename und lineno sind reserviert.

Einzelne Adds, Bulk-Adds und Importe ersetzen Zeilenumbrüche in Payees, Narrations und String-Metadaten durch Leerzeichen. Anführungszeichen und Backslashes behalten ihren Inhalt.

Weitere Direktiven hinzufügen​

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

Kontonamen haben eine großgeschriebene Wurzel und durch Doppelpunkte getrennte Segmente. Jedes Unterkonto beginnt mit einem Großbuchstaben oder einer Ziffer. Beancount unterstützt Unicode-Buchstaben und konfigurierte Wurzelnamen.

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

Verwenden Sie add balance --pad-from Equity:OpeningBalances, um einen Pad und seine Balance-Assertion zusammen zu schreiben. Der Pad verwendet standardmäßig den Vortag; --pad-date kann einen anderen früheren Tag auswählen. Beide Konten müssen aktiv sein. Ein eigenständiger Pad benötigt ein späteres Balance, um ihn zu verbrauchen. --allow-errors kann diesen Zwischenzustand vorbereiten, aber kein ungültiges Pad-Konto umgehen.

add price überspringt ein exaktes Duplikat aus Datum/Commodity/Preis über die Wurzel und ihre Includes hinweg. Es beendet mit Exit 0 und identifiziert die vorhandene Stelle. Unterschiedliche Daten oder Preise sind neue Hinzufügungen.

Dokumentpfade werden neben der Datei aufgelöst, die die Anweisung 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.

Stapel-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.

Ein Posten verwendet entweder amount oder units, etwa {"number":"45.00","currency":"USD"}. Lassen Sie beide für den ausgleichenden Posten weg. Posten-Felder umfassen außerdem cost, price, flag und meta. Kosten enthalten number und currency, mit optionalem date und label. Preise enthalten number und currency.

Verwenden Sie Zeichenfolgen für Dezimalzahlen. Metadaten verwenden gewöhnliche Zeichenfolgen und Booleans 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 source-Speicherort der Transaktion wird niemals als Metadaten geschrieben.

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

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

Geteilte Hauptbücher und Schreibsicherheit​

Halten Sie --file auf die Wurzel gerichtet. Fügen Sie --into hinzu, um eine vorhandene eingebundene 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 Wurzelverzeichnis. Es muss bereits eingebunden sein; das Benennen einer nicht zugehörigen Datei wird abgelehnt. Add-Befehle, Importe und interaktive KI-Schreibvorgänge unterstützen diese Trennung.

Schreibvorgänge validieren das vollständige Kandidaten-Ledger, einschließlich Plugins und Cost-Lot-Booking. Eine gleichzeitige Änderung an der Wurzel oder ihrem Include-Graph beendet mit Exit 4. Ein schreibgeschütztes Ziel beendet mit Exit 3. Erfolgreiche Hinzufügungen richten nur die neuen Zeilen aus. Bestehende Bytes bleiben unverändert. Verwenden Sie bea format -i PATH, wenn Sie die gesamte Datei neu ausrichten möchten.

Listen-Direktiven​

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

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

Prüfen, formatieren und abfragen​

bea check validiert die Wurzel und Includes. Es beendet bei Erfolg still mit Exit 0 und bei Ledger-Fehlern mit Exit 1. Globales --json gibt den Validierungs-Envelope zurück. Es gibt keine --allow-errors-Option für check.

Abfragen, Listen und Berichte warnen und geben Teilergebnisse in einem interaktiven Terminal zurück. Globales --strict, --json, --no-input, truthy CI oder nicht-terminales stdin machen Lesevorgänge strikt. Deren --allow-errors-Option erlaubt ausdrücklich Teilergebnisse.

Formatierung akzeptiert Dateien oder durchsucht ein Verzeichnis rekursiv. Im veröffentlichten Paket 0.2.0 ist ein Pfad erforderlich, trotz des in der Hilfe gezeigten stdin-Standards. Globales --file wählt nicht das Formatierungsziel.

Formatierung richtet Text aus; sie validiert nicht die Ledger-Syntax oder Buchhaltung. Führen Sie bea check separat aus. Wählen Sie bei globalem --json -i, -o FILE, --check oder --dry-run, damit stdout den Envelope tragen kann. Leiten Sie stdout nicht über die Eingabedatei um: Verwenden Sie -i, um sie neu zu schreiben.

bea query "BQL" führt eine Beancount-Abfrage aus. Das Weglassen von BQL liest Abfragen aus stdin oder öffnet die Shell, wenn stdin ein Terminal ist. Verwenden Sie .exit, exit oder quit, um die Shell zu schließen. Die Standardtabelle von BQL hat eine Zeile pro Posten. Abfragetabellen bewahren die Präzision.

Wählen Sie das Ledger vor dem Befehl, zum Beispiel bea --file main.bean query -f csv -o balances.csv "SELECT account, sum(position) GROUP BY account". Globales --json verwendet den Produkt-Envelope mit data.rows und data.columns; es unterscheidet sich von der CSV-Darstellung. Verwenden Sie in der veröffentlichten Version 0.2.0 die Shell-Umleitung, um JSON zu speichern, etwa bea --json query "SELECT account, sum(position) GROUP BY account" > result.json: Die Abfrageoptionen -o und -m gelten in dieser Version nicht für JSON.

Native Werkzeuge und optionale Funktionen​

bea doctor context main.bean 42 zeigt den Transaktionskontext in Zeile 42. bea doctor --help listet die anderen Diagnosebefehle auf. bea example -o example.bean erstellt eine Beispielhistorie. bea treeify accounts.txt stellt hierarchische Namen aus einer Textdatei dar; lassen Sie die Datei weg, um stdin zu lesen. Diese Befehle leiten native Argumente weiter. Die obigen Beispiele benennen diese Argumente explizit.

Aktivieren Sie optionale Tools einmalig mit bea engine enable beanprice für den Kursabruf oder bea engine enable beangulp für Importer-Workflows. Das Aktivieren benötigt Netzwerkzugriff; Beangulp benötigt außerdem die Systembibliothek libmagic. Verwenden Sie bea engine status, um die Verfügbarkeit zu prüfen. bea price --help und bea ingest --help beschreiben ihre Schnittstellen. bea import --csv und bea add price benötigen keine der beiden optionalen Funktionen.

Verwaltete Preis-Includes​

Live-Preise ist ein separater Managed-Include-Workflow. Gehostete Ledger lösen unterstützte Preis-URLs auf; kompatible bea-Versionen unterstützen auch verwaltete Includes und lokale Preisexporte. Prüfen Sie den versionsspezifischen Leitfaden zu verwalteten Preisen, wenn Ihre installierte Version diese Befehle nicht erkennt.

Die CLI löst allowlistete verwaltete URLs auf, ohne Anmeldedaten zu senden, und lehnt Weiterleitungen ab. Ein Feed, der auf eine gehostete Anmeldung weiterleitet, ist daher für einen frischen lokalen Abruf nicht verfügbar; die Anmeldung auf der Website authentifiziert die Preisabfrage der CLI nicht. Prüfen Sie price status auf Quellfehler. Verwenden Sie je nach Situation gecachte Daten, einen erreichbaren unterstützten Feed oder lokale datierte Preise.

price export schreibt Feed-Dateien unter prices/ und schreibt Includes in lokale relative Pfade um. Upstream-Beancount, Fava und Beanquery können diese exportierte Kopie laden. Eine nicht verfügbare Quelle verweigert den Export, es sei denn --allow-errors wird verwendet, was ihren Quellmarker ohne Preise hinterlassen kann.

Ihr eigener datierter Preis überschreibt einen verwalteten Preis für dasselbe Datum und Paar. Feed-Einträge sind schreibgeschützt. Fehlgeschlagene Aktualisierungen behalten eine zuvor validierte Revision, die veraltet sein kann. Andere Argumente für bea price werden weiterhin an Beanprice weitergeleitet; wenn eine Quote-Job-Datei status heißt, übergeben Sie ./status, um sie vom Unterbefehl zu unterscheiden.

Homebrew installiert sowohl die CLI als auch ihre verwaltete Engine. Bei PyPI lädt der erste engine-gestützte Befehl die angehefteten Abhängigkeiten herunter; halten Sie uv im PATH und erlauben Sie Netzwerkzugriff für diesen ersten Lauf. Spätere lokale Befehle verwenden die Engine offline wieder. Kunden installieren nur beancount-io, ohne separates Beancount-Paket oder native Konsolenskripte, die verwaltet werden müssen.

Finanzberichte​

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

bea balance [ACCOUNT...] gibt Saldo-Unterbäume für Konten aus, die groß-/kleinschreibungsunabhängigen Teilstrings entsprechen, oder das gesamte Ledger, wenn Sie keines benennen. Es akzeptiert --conversion / -x, --time / -t und --allow-errors und nimmt keine Intervall- oder Kontooption.

Zeitfilter umfassen ein Jahr, einen Monat, ein Datum, ein Quartal, eine Woche oder einen Bereich, etwa 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 jeden Posten einer passenden Transaktion.

Die Umrechnung verwendet standardmäßig die einzige Funktionswährung des Ledgers. Andernfalls wird standardmäßig units verwendet, wodurch Commodities getrennt bleiben. at_cost verwendet Anschaffungskosten. at_value verwendet Marktwerte mit einem Kosten-Fallback.

Eine explizite Währungsumrechnung benötigt Preise an oder vor jedem Bewertungsdatum, einschließlich der Intervalltermine. Ein Fehler über einen fehlenden Preis benennt die tatsächliche Lücke, etwa No EUR → USD price on or before 2026-01-31. Eine spätere Notierung kann eine frühere Lücke nicht füllen. Fügen Sie einen historisch passenden Preis hinzu, verwenden Sie --conversion units oder wählen Sie --allow-errors, um Teilwerte zu prüfen.

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

Erträge, Passiva und Eigenkapital verwenden normalerweise negative Beancount-Vorzeichen. Der Nettogewinn ist -(income + expenses), positiv bei einem Gewinn. Dieselbe Konvention gilt für Periodenzeilen der Gewinn- und Verlustrechnung. Die Bilanzabstimmung wird für den Bericht abgeleitet; sie schreibt keine Anweisungen. equity_reconciled gibt an, ob eine vollständige Abstimmung verfügbar ist.

Bericht-JSON identifiziert auch die Periode, das exklusive Enddatum, das Stichtagsdatum, die Umrechnung, den Kontofilter und den Validierungsstatus des Ledgers. Prüfen Sie diese Felder, bevor Sie Summen vergleichen.

Optionale AI-Unterstützung​

bea ask benötigt sowohl das ask-Extra als auch Beancount.io-Anmeldedaten aus bea cloud login oder BEA_TOKEN. Die Standard-Homebrew-Installation lässt KI-Abhängigkeiten weg. 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 bea ask direkt aus. --print / -p antwortet einmal und beendet. Andernfalls ist eine Terminal-Sitzung interaktiv, und eine optionale Frage füllt deren 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 KI-Dienst von Beancount.io. Interaktive Schreibvorgänge werden in der Vorschau angezeigt, bestätigt, validiert und atomar geschrieben. Sie akzeptieren --into. Globales --yes erteilt 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 die YAML-Felder name und description. Vollständige Anweisungen werden bei Bedarf geladen. Für das Dateilayout und ein ausgearbeitetes Beispiel siehe bea ask mit Skills erweitern.

Gehostete Hauptbücher​

Mit globalem --json geben bea cloud status, bea cloud ledger list, bea cloud ledger show, bea cloud ledger create und bea cloud ledger delete den Standard-Envelope aus. Login erfordert Interaktion; erfolgreiches Logout und Klonen geben kein JSON-Erfolgsobjekt zurück.

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

JSON und Exit-Codes​

Globales --json legt erfolgreiche Ergebnisse auf stdout:

{
  "bea": "0.2.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. Targets identifizieren eine Datei, ein Verzeichnis, einen Server oder kein Target. Eingebundene Schreibvorgänge identifizieren außerdem into. Dezimalbeträge und Daten verwenden Zeichenfolgen. Begrenzte Listen enthalten limit und truncated.

Fehler schreiben {"error":{"category":"validation","message":"…","exit_code":1}} nach stderr. Der Fehler kann außerdem details, result, eine Backend-request_id und ein traceback mit --debug enthalten.

Prüfen Sie error.result, bevor Sie eine Mutation erneut versuchen. Ein partieller Stapel kann akzeptierte Zeilen schreiben, rekursive Formatierung kann gültige Dateien ändern, und Create-and-Clone kann ein gehostetes Ledger erstellen, bevor mit einem Exit ungleich null beendet wird. Für ein Skript, das diesen Envelope mit jq liest und anhand dieser Codes verzweigt, siehe Buchhaltung mit bea automatisieren.

CLI-Eingabeaufforderungen werden durch --no-input, JSON-Modus, nicht-terminales stdin oder truthy CI deaktiviert. Cloud-Löschung benötigt weiterhin explizites --yes. Importe benötigen eine explizite Duplikatentscheidung, wenn Übereinstimmungen überprüft werden müssen.

Ausgabeausnahmen: doctor, example, treeify, an Beanprice weitergeleitete price-Aufrufe und ingest bewahren native Ausgabe und Exit-Status, selbst mit globalem --json; der Envelope und die Exit-Kategorien oben beschreiben diese weitergeleiteten Ergebnisse nicht. Ask lehnt JSON ab; Cloud-Login erfordert Interaktion; erfolgreiches Cloud-Logout und -Klonen geben kein JSON-Erfolgsobjekt zurück. Hilfe, Version und Vervollständigung behalten die Textausgabe. upgrade kann die Ausgabe seines Paketmanagers nach stderr streamen, auch im JSON-Modus.

Einstellungen, Updates und gespeicherter Zustand​

Truthy-Werte sind 1, true, yes und on, ohne Berücksichtigung von Groß-/Kleinschreibung und umgebenden Leerzeichen. Der Konfigurationszustand umfasst Anmeldedaten, Ask-Prompt-Verlauf, Benutzer-Skills, gemerkte Importer-Pfade und Update-Prüf-Caches. Schreibsperren liegen unter locks/ im Cache-Verzeichnis, außerhalb Ihres Ledger-Verzeichnisses.

bea upgrade --check meldet Versionen und die Installationsmethode, ohne zu aktualisieren. bea upgrade ruft brew upgrade bea, uv tool upgrade beancount-io oder pipx upgrade beancount-io auf. Editierbare Installationen erhalten manuelle Update-Anleitungen. Passive Prüfungen laufen höchstens einmal pro Tag in interaktiven installierten Kopien; explizites upgrade --check läuft weiterhin, wenn der passive Notifier deaktiviert ist.

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

Übliche Fehlerbehebungen​

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