Beancount CLI-referentie

Gebruik deze referentie om bea-commando's en hun gedrag op te zoeken. Voor uw eerste boekhouding volgt u de CLI-snelstart. Voor bankbestanden gebruikt u de importwalkthrough.

Commando's in één oogopslag​

Globale opties en paden​

Globale opties komen vóór het commando:

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

init maakt zijn eigen map/bestandsdoel en negeert BEA_FILE. Het accepteert het globale --file in plaats van het mappargument. format gebruikt zijn eigen positionele doel, standaard de werkmap. Het globale --file kiest niet het formatteerdoel.

Een boekhouding aanmaken​

bea init [DIRECTORY] gebruikt standaard de huidige map. Een map maakt main.bean; een .bean- of .beancount-pad benoemt direct het nieuwe bestand.

Het sjabloon opent Assets:Checking, Assets:Savings, Assets:Cash, Liabilities:CreditCard, Income:Salary, Income:Interest, Expenses:Groceries, Expenses:Dining, Expenses:Rent, Expenses:Transport, Expenses:Utilities, Expenses:Fees en Equity:OpeningBalances.

Openingssaldi worden gecompenseerd tegen Equity:OpeningBalances. Schuld is negatief. Valutainvoer wordt in hoofdletters gezet. Aangepaste symbolen zijn toegestaan; een symbool dat niet uit drie hoofdletters bestaat, activeert een typfoutwaarschuwing. Dit is geen ISO-valutaregistercontrole.

Bestaande bestanden worden nooit overschreven. Nieuwe bestanden gebruiken alleen-eigenaar-rechten, modus 0600 op POSIX. Latere toevoeg-, import- en formatteerschrijfbewerkingen behouden rechten en respecteren alleen-lezen doelen.

Transacties toevoegen​

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'

Eén boeking mag het bedrag weglaten. Genummerde boekingen mogen de valuta weglaten wanneer een rekening één toegestane valuta heeft of de boekhouding één compatibele functionele valuta heeft. Anders levert u het symbool.

Native boekingssyntaxis ondersteunt rekenkunde zoals 84/2 EUR, kosten zoals {100 USD}, totale kosten {{1000 USD}} en prijzen @ of @@. Gebruik decimale bedragen zoals 1000, niet exponentnotatie zoals 1e3.

Een valuta-uitwisseling heeft de werkelijke transactiekoers nodig. Boek bijvoorbeeld 100 EUR @ 1.08 USD naar een rekening die in EUR is geopend en -108 USD naar de betaalrekening. Een beleggingsaankoop kan 2 AAPL {100 USD} boeken naar een rekening die in AAPL is geopend en -200 USD naar de betaalrekening. Voeg gedateerde price-noteringen toe wanneer rapporten marktwaardering nodig hebben.

Metadata accepteert kale tekenreeksen zoals --meta 'receipt:IMG_42.jpg'. Native getallen, booleans, datums en bedragen behouden hun type. Voorbeelden zijn --meta 'reviewed:TRUE', --meta 'received:2026-08-03' en --meta 'fee:2.50 USD'. Binnenste aanhalingstekens dwingen een tekenreeks af: --meta 'code:"1234"'. Sleutels moeten verschillend zijn; filename en lineno zijn gereserveerd.

Enkele toevoegingen, bulksgewijze toevoegingen en imports vervangen regeleinden in begunstigden, omschrijvingen en tekenreeksmetadata door spaties. Aanhalingstekens en backslashes behouden hun inhoud.

Andere richtlijnen toevoegen​

Al deze commando's vereisen --date YYYY-MM-DD. Ze accepteren ook --into FILE en --allow-errors.

Rekeningnamen hebben een met hoofdletter geschreven wortel en door dubbele punten gescheiden segmenten. Elk subaccount begint met een hoofdletter of cijfer. Beancount ondersteunt Unicode-letters en geconfigureerde wortelnamen.

Een balans controleert de rekening aan het begin van zijn datum. Tolerantiesyntaxis wordt ondersteund, zoals --amount "1538 ~ 1 EUR". De tolerantie moet niet-negatief zijn.

Gebruik add balance --pad-from Equity:OpeningBalances om samen een pad en een balansassertie te schrijven. Het pad gebruikt standaard de vorige dag; --pad-date kan een andere eerdere dag selecteren. Beide rekeningen moeten actief zijn. Een zelfstandig pad heeft een latere balans nodig om het te consumeren. --allow-errors kan die tussenliggende staat opvoeren, maar kan geen ongeldige padrekening omzeilen.

add price slaat een exacte datum/goed/prijs-duplicatie over in de hoofdmap en zijn includes. Het eindigt met code 0 en identificeert de bestaande locatie. Verschillende datums of prijzen zijn nieuwe toevoegingen.

Documentpaden worden opgelost naast het bestand dat de richtlijn bevat. Met --into years/2026.bean betekent --filename receipt.pdf years/receipt.pdf, niet een bestand naast de werkmap van uw shell.

Aangepaste waardesoorten zijn text, number, amount, account, bool en date. Een budget kan bijvoorbeeld --value "text:travel" --value "amount:500 USD" gebruiken.

Bulksgewijze JSON-invoer​

bea add transactions --from transactions.json accepteert een 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 }
  }
]

Elke transactie vereist date en postings. Optionele velden zijn flag, payee, narration, tags, links en meta.

Een boeking gebruikt amount of units, zoals {"number":"45.00","currency":"USD"}. Laat beide weg voor de salderingsboeking. Boekingsvelden omvatten ook cost, price, flag en meta. Kosten bevatten number en currency, met optionele date en label. Prijzen bevatten number en currency.

Gebruik tekenreeksen voor decimalen. Metadata gebruikt gewone tekenreeksen en booleans, of getagde waarden zoals {"kind":"number","value":"1.125"}, {"kind":"date","value":"2026-08-04"} en {"kind":"amount","number":"2.50","currency":"USD"}. De optionele transactie-source-locatie wordt nooit als metadata geschreven.

De standaard is een atomaire batch: elke afgewezen rij laat de boekhouding ongewijzigd en eindigt met code 1. --partial schrijft een geldige subset en eindigt nog steeds met code 1 als rijen worden afgewezen. JSON-fouten beschrijven de uitkomst in error.result; rij-indexen daar zijn nul-gebaseerd. Menselijke rijnummers zijn één-gebaseerd.

Bulksgewijze toevoeging accepteert --into en --allow-errors. Het de-dupliceert niet. Gebruik bea import voor beoordeling van bankexporten.

Gesplitste boekhoudingen en schrijfveiligheid​

Houd --file gericht op de hoofdmap. Voeg --into toe om een bestaand opgenomen bestand te selecteren:

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

Het doel is relatief ten opzichte van de hoofdmap. Het moet al zijn opgenomen; het benoemen van een niet-gerelateerd bestand wordt geweigerd. Toevoegcommando's, imports en interactieve AI-schrijfbewerkingen ondersteunen deze scheiding.

Schrijfbewerkingen valideren de volledige kandidaatboekhouding, inclusief plug-ins en kostlotboeking. Een gelijktijdige wijziging aan de hoofdmap of zijn opnamegrafiek eindigt met code 4. Een alleen-lezen doel eindigt met code 3. Succesvolle toevoegingen gebruiken dezelfde uitlijning als bea format, die bestaande kolommen in dat doel opnieuw kan uitlijnen.

Richtlijnen weergeven​

bea list TYPE ondersteunt de elf typen: transaction, open, close, balance, pad, note, event, price, commodity, document en custom.

Andere richtlijntypen behouden chronologische volgorde. Een transactietabel met accountfilter labelt de bedragkolom MATCHING POSTING AMOUNTS. Details en JSON bevatten nog steeds alle boekingen van elke geselecteerde transactie. Details weergeven geladen vermeldingen, inclusief afgeleide bedragen; ze zijn geen ruwe bronexcerpten.

Controleren, formatteren en query's​

bea check valideert de hoofdmap en includes. Het eindigt met code 1 voor boekhoudfouten en heeft geen --allow-errors-optie. Query's, lijsten en rapporten verwerpen ook loaderfouten tenzij u expliciet hun --allow-errors-optie doorgeeft.

Formatteren neemt een .bean/.beancount-bestand of een map. Een map wordt recursief doorzocht.

Elke modus rapporteert syntaxisfouten per bestand en regel, slaat die bestanden over en eindigt met code 1. Een recursieve normale run kan de geldige bestanden nog steeds formatteren. JSON rapporteert scanned, formatted, skipped, dry_run en check, onder error.result bij mislukking.

bea query "BQL" voert een Beancount-query uit. Het weglaten van BQL opent een interactieve shell; exit of quit sluit deze. Een queryargument is vereist onbemand. De standaardtabel in BQL heeft één rij per boeking. Querytabellen behouden precisie. Lege resultaten printen (no rows) naar stderr; JSON retourneert een lege data.rows en kolommetadata in data.columns.

Financiële rapporten​

Alle rapporten accepteren --conversion / -x, --time / -t, --account / -a en --allow-errors. Alle behalve proefbalans accepteren ook --interval / -i: standaard monthly, of quarterly, yearly, weekly of daily.

Tijdfilters omvatten een jaar, maand, datum, kwartaal, week of bereik, zoals 2026, 2026-08, 2026-08-31, 2026-Q3, 2026-W32 of "2026-01 - 2026-08". Relatieve perioden omvatten year, quarter, month, week, day en verschuivingen zoals month-1. Accountfilters behouden elke boeking van een overeenkomende transactie.

Conversie gebruikt standaard de enige functionele valuta van de boekhouding. Anders gebruikt het standaard units, waarbij goederen gescheiden blijven. at_cost gebruikt aanschafkosten. at_value gebruikt marktwaarden met een kostenfallback.

Een expliciete valutaconversie vereist prijzen op of vóór elke waarderingsdatum, inclusief intervaldatums. Een fout met ontbrekende prijs benoemt de werkelijke hiaat, zoals No EUR → USD price on or before 2026-01-31. Een latere notering kan een eerder hiaat niet opvullen. Voeg een historisch geschikte prijs toe, gebruik --conversion units of kies --allow-errors om gedeeltelijke waarden te inspecteren.

Gedeeltelijke rapporten behouden bronvaluta's en markeren gecombineerde totalen als niet beschikbaar. JSON omvat valuation: "partial", missing_prices en missing_price_dates. Getroffen nettowinst-/vermogenstotalen zijn null in de gevraagde valuta.

Inkomsten, passiva en eigen vermogen gebruiken normaal negatieve Beancount-tekens. Nettowinst is -(income + expenses), positief voor een winst. Dezelfde conventie geldt voor perioderijen in de resultatenrekening. Balansreconciliatie wordt afgeleid voor het rapport; het schrijft geen richtlijnen. equity_reconciled identificeert of een complete reconciliatie beschikbaar is.

Rapport-JSON identificeert ook de periode, exclusieve einddatum, peildatum, conversie, accountfilter en validatiestatus van de boekhouding. Controleer die velden voordat u totalen vergelijkt.

Optionele AI-assistentie​

bea ask vereist zowel het ask-extra als Beancount.io-referenties van bea cloud login of BEA_TOKEN. De standaard Homebrew-installatie laat AI-afhankelijkheden weg. Homebrew-gebruikers kunnen uitvoeren:

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

Voor een uv-installatie installeert u beancount-io[ask] en voert u bea ask direct uit. --print / -p beantwoordt eenmalig en eindigt. Anders is een terminalsessie interactief, en een optionele vraag vult de invoer vooraf. Niet-interactief gebruik vereist een vraag. JSON-modus wordt niet ondersteund.

Query's worden lokaal uitgevoerd. Vragen, vaardigheidscontext en toolresultaten gaan naar de gehoste Beancount.io-AI-service. Interactieve schrijfbewerkingen worden voorvertoond, bevestigd, gevalideerd en atomair geschreven. Ze accepteren --into. Het globale --yes verleent geen AI-schrijfrechten. Eén-antwoordmodus past geen voorgestelde schrijfbewerkingen toe.

Ask leest NAME/SKILL.md uit .agents/skills/ in de werkmap en uit skills/ in de gebruikersconfiguratiemap. Projectdefinities winnen per naam. Elk bestand heeft YAML-velden name en description nodig. Volledige instructies worden op aanvraag geladen.

Gehoste boekhoudingen​

Creatie accepteert ook --clone en --dir. Git- en SSH-toegang zijn vereist om te klonen. Als het klonen na creatie mislukt, bestaat de gehoste boekhouding nog steeds. Lokale commando's uploaden uw boekhouding niet automatisch. Er is geen globale --ledger-optie.

JSON en exitcodes​

Global --json plaatst succesvolle resultaten op stdout:

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

bea is de geïnstalleerde versie; data hangt af van het commando. Doelen identificeren een bestand, map, server of geen doel. Opgenomen schrijfbewerkingen identificeren ook into. Decimale bedragen en datums gebruiken tekenreeksen. Beperkte lijsten omvatten limit en truncated.

Mislukkingen schrijven {"error":{"category":"validation","message":"…","exit_code":1}} naar stderr. De fout kan ook details, result, een backend-request_id en een traceback met --debug bevatten.

Controleer error.result voordat u een mutatie opnieuw probeert. Een gedeeltelijke batch kan geaccepteerde rijen schrijven, recursief formatteren kan geldige bestanden wijzigen, en create-and-clone kan een gehoste boekhouding maken vóór het beëindigen met een code ongelijk aan nul.

CLI-prompts worden uitgeschakeld door --no-input, JSON-modus, niet-terminal-stdin of truthy CI. Cloudverwijdering vereist nog steeds expliciet --yes. Imports vereisen een expliciete duplicaatbeslissing wanneer matches beoordeling nodig hebben.

Uitvoeruitzonderingen: Ask verwerpt JSON; cloudaanmelding vereist interactie; succesvolle cloudafmelding en kloon retourneren geen JSON-succesobject. Help, versie en completion behouden tekstuitvoer. upgrade kan de uitvoer van de packagemanager naar stderr streamen, ook in JSON-modus.

Instellingen, updates en opgeslagen status​

Truthy-waarden zijn 1, true, yes en on, ongeacht hoofdletters en omringende witruimte. Configuratiestatus omvat referenties, Ask-promptgeschiedenis, gebruikersvaardigheden, onthouden importer-paden en updatecontrol-caches. Schrijflockers bevinden zich onder locks/ van de cachemap, buiten uw boekhoudmap.

bea upgrade --check rapporteert versies en de installatiemethode zonder te upgraden. bea upgrade roept brew upgrade bea, uv tool upgrade beancount-io of pipx upgrade beancount-io aan. Bewerkbare installaties ontvangen handmatige updatebegeleiding. Passieve controles worden maximaal één keer per dag uitgevoerd in interactieve geïnstalleerde exemplaren; expliciet upgrade --check wordt nog steeds uitgevoerd wanneer de passieve melder is uitgeschakeld.

Verwijder met de bijbehorende manager: brew uninstall bea, uv tool uninstall beancount-io of pipx uninstall beancount-io. Uw boekhoudbestanden en gebruikersconfiguratie blijven behouden.

Veelvoorkomende oplossingen​

Gebruik bea COMMAND --help om uw geïnstalleerde versie te inspecteren. De bronrepository-referentie bevat aanvullende voorbeelden en de exacte richtlijnmodeldefinities.