Beancount CLI-referentie

Gebruik deze referentie om bea-commando's en hun gedrag op te zoeken. Volg voor je eerste grootboek de CLI-snelstartgids. Doorloop voor een volledige maand van begin tot eind Je eerste maand met bea. Gebruik voor bankbestanden de import-walkthrough.

Commando's in één oogopslag​

Globale opties en paden​

Algemene opties gaan vóór het commando:

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

init maakt zijn eigen map-/bestandsdoel aan en negeert BEA_FILE. Het accepteert in plaats van zijn mapargument de algemene --file. format gebruikt zijn eigen positionele doel. Geef een bestandsnaam of map op. De algemene --file kiest niet het formatteringsdoel.

Maak een grootboek aan​

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

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, Expenses:Uncategorized en Equity:OpeningBalances.

Openingssaldi worden verrekend tegen Equity:OpeningBalances. Schuld is negatief. Valutainvoer wordt in hoofdletters omgezet. Aangepaste symbolen zijn toegestaan; een symbool dat niet uit drie hoofdletters bestaat, activeert een typowaarschuwing. Dit is geen controle tegen het ISO-valutaregister.

Bestaande bestanden worden nooit overschreven. Nieuwe bestanden gebruiken rechten voor alleen de eigenaar, modus 0600 op POSIX. Latere toevoegingen en importschrijfacties behouden rechten en respecteren alleen-lezen-bestemmingen. Formatteren ter plaatse gebruikt de native formatter en rapporteert zijn eigen bestandssysteemfouten.

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 zijn bedrag weglaten. Genummerde boekingen mogen de valuta weglaten wanneer een rekening één toegestane valuta heeft of het grootboek één compatibele operationele valuta heeft. Geef anders het symbool op.

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

Een valutawissel 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-koersen toe wanneer rapporten marktwaardering nodig hebben.

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

Enkele toevoegingen, bulktoevoegingen en imports vervangen regeleinden in begunstigden, toelichtingen en stringmetadata door spaties. Aanhalingstekens en backslashes behouden hun inhoud.

Voeg andere richtlijnen toe​

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

Rekeningnamen hebben een hoofdletter-root en door dubbele punten gescheiden segmenten. Elke subrekening begint met een hoofdletter of cijfer. Beancount ondersteunt Unicode-letters en geconfigureerde rootnamen.

Een balance 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 een pad en de bijbehorende saldocontrole samen te schrijven. De pad gebruikt standaard de vorige dag; --pad-date kan een andere eerdere dag selecteren. Beide rekeningen moeten actief zijn. Een losse pad heeft een latere balance nodig om hem te verbruiken. --allow-errors kan die tussenliggende toestand voorbereiden, maar kan geen ongeldige pad-rekening omzeilen.

add price slaat een exacte duplicaat op datum/commodity/prijs over het rootbestand en zijn includes over. Het stopt met exit 0 en vermeldt de bestaande locatie. Andere 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 je shell.

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

Bulk 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 ofwel amount ofwel units, zoals {"number":"45.00","currency":"USD"}. Laat beide weg voor de salderende boeking. Boekingsvelden omvatten ook cost, price, flag en meta. Kosten bevatten number en currency, met optionele date en label. Prijzen bevatten number en currency.

Gebruik strings voor decimalen. Metadata gebruikt gewone strings 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 source-locatie van de transactie wordt nooit als metadata geschreven.

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

Bulk toevoegen accepteert --into en --allow-errors. Het dedupliceert niet. Gebruik bea import voor het beoordelen van bankexports.

Gesplitste grootboeken en schrijversveiligheid​

Houd --file gericht op het rootbestand. 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"

De bestemming is relatief ten opzichte van de rootmap. Deze moet al zijn opgenomen; een niet-gerelateerd bestand benoemen wordt geweigerd. Toevoegcommando's, imports en interactieve AI-schrijfacties ondersteunen deze scheiding.

Schrijfacties valideren het volledige kandidaat-grootboek, inclusief plugins en cost-lot-boeking. Een gelijktijdige wijziging van het rootbestand of zijn include-graaf stopt met exit 4. Een alleen-lezen-bestemming stopt met exit 3. Succesvolle toevoegingen lijnen alleen de nieuwe regels uit. Bestaande bytes blijven ongewijzigd. Gebruik bea format -i PATH wanneer je het hele bestand opnieuw wilt uitlijnen.

Lijst van directives​

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

Andere richtlijntypen behouden de chronologische volgorde. Een op rekening gefilterde transactietabel labelt zijn bedragkolom als MATCHING POSTING AMOUNTS. Details en JSON bevatten nog steeds alle boekingen van elke geselecteerde transactie. Details geven geladen items weer, inclusief afgeleide bedragen; het zijn geen ruwe bronfragmenten.

Controleren, formatteren en opvragen​

bea check valideert het rootbestand en de includes. Het stopt stil met exit 0 bij succes en met 1 bij grootboekfouten. Algemene --json retourneert de validatie-envelope. Er is geen --allow-errors-optie voor check.

Query's, lijsten en rapporten waarschuwen en retourneren gedeeltelijke resultaten in een interactieve terminal. Algemene --strict, --json, --no-input, waarheidsgetrouwe CI of niet-terminale stdin maken reads strikt. Hun --allow-errors-optie staat expliciet gedeeltelijke resultaten toe.

Formatteren accepteert bestanden of doorzoekt recursief een map. In het gepubliceerde 0.2.0-pakket is een pad vereist ondanks de stdin-standaard die in de help wordt getoond. De algemene --file kiest niet het formatteringsdoel.

Formatteren lijnt tekst uit; het valideert geen grootboeksyntaxis of boekhouding. Voer bea check afzonderlijk uit. Selecteer met algemene --json -i, -o FILE, --check of --dry-run zodat stdout de envelope kan bevatten. Omleiden van stdout over het invoerbestand: gebruik -i om het te herschrijven.

bea query "BQL" voert een Beancount-query uit. Als BQL wordt weggelaten, worden query's van stdin gelezen of wordt de shell geopend wanneer stdin een terminal is. Gebruik .exit, exit of quit om de shell te sluiten. De standaardtabel van BQL heeft één rij per boeking. Querytabellen behouden precisie.

Selecteer het grootboek vóór het commando, bijvoorbeeld bea --file main.bean query -f csv -o balances.csv "SELECT account, sum(position) GROUP BY account". Algemene --json gebruikt de productenvelope met data.rows en data.columns; dit is iets anders dan CSV-weergave. Gebruik in de gepubliceerde 0.2.0-release shell-omleiding om JSON op te slaan, zoals bea --json query "SELECT account, sum(position) GROUP BY account" > result.json: query -o en -m zijn in die release niet van toepassing op JSON.

Native tools en optionele functies​

bea doctor context main.bean 42 toont de transactiecontext op regel 42. bea doctor --help toont de andere diagnostische commando's. bea example -o example.bean maakt een voorbeeldhistorie. bea treeify accounts.txt geeft hiërarchische namen weer vanuit een tekstbestand; laat het bestand weg om stdin te lezen. Deze commando's sturen native argumenten door. De bovenstaande voorbeelden benoemen die argumenten expliciet.

Schakel optionele tools één keer in met bea engine enable beanprice voor het ophalen van koersen of bea engine enable beangulp voor importerworkflows. Inschakelen vereist netwerktoegang; Beangulp vereist ook de systeembibliotheek libmagic. Gebruik bea engine status om beschikbaarheid te inspecteren. bea price --help en bea ingest --help beschrijven hun interfaces. bea import --csv en bea add price hebben geen van beide optionele functies nodig.

Beheerde prijs-includes​

Live Prices is een afzonderlijke workflow met beheerde includes. Gehoste grootboeken lossen ondersteunde prijs-URL's op; compatibele bea-versies ondersteunen ook beheerde includes en lokale prijsexports. Raadpleeg de versiespecifieke gids voor beheerde prijzen als je geïnstalleerde versie deze commando's niet herkent.

De CLI lost allowlisted beheerde URL's op zonder inloggegevens te verzenden en weigert redirects. Een feed die doorverwijst naar een gehoste login is daarom niet beschikbaar voor een nieuwe lokale fetch; aanmelden op de website authenticeert het CLI-prijsverzoek niet. Inspecteer price status op bronfouten. Gebruik waar passend gecachte gegevens, een bereikbare ondersteunde feed of lokale gedateerde prijzen.

price export schrijft feedbestanden onder prices/ en herschrijft includes naar lokale relatieve paden. Upstream Beancount, Fava en Beanquery kunnen die geëxporteerde kopie laden. Een niet-beschikbare bron weigert export tenzij --allow-errors wordt gebruikt, wat zijn bronmarkering zonder prijzen kan achterlaten.

Je eigen gedateerde prijs overschrijft een beheerde prijs voor dezelfde datum en hetzelfde paar. Feed-items zijn alleen-lezen. Mislukte verversingen behouden een eerder gevalideerde revisie, die verouderd kan zijn. Andere argumenten voor bea price worden nog steeds doorgestuurd naar Beanprice; als een quote-jobbestand status heet, geef dan ./status door om het van het subcommando te onderscheiden.

Homebrew installeert zowel de CLI als zijn beheerde engine. Bij PyPI downloadt het eerste engine-ondersteunde commando de vastgezette afhankelijkheden; houd uv op PATH en sta netwerktoegang toe voor die eerste run. Latere lokale commando's hergebruiken de engine offline. Klanten installeren alleen beancount-io, zonder apart Beancount-pakket of native console-scripts om te beheren.

Financiële rapporten​

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

bea balance [ACCOUNT...] toont sald-subbomen voor rekeningen die overeenkomen met hoofdletterongevoelige substrings, of het hele grootboek wanneer je er geen noemt. Het accepteert --conversion / -x, --time / -t en --allow-errors, en heeft geen interval- of rekeningoptie.

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 offsets zoals month-1. Rekeningfilters behouden elke boeking van een overeenkomende transactie.

Conversie gebruikt standaard de enige operationele valuta van het grootboek. Anders is de standaard units, waarbij commodities gescheiden blijven. at_cost gebruikt aanschafkosten. at_value gebruikt marktwaarden met een kostenterugval.

Een expliciete valutaconversie vereist prijzen op of vóór elke waarderingsdatum, inclusief intervaldatums. Een fout voor ontbrekende prijs noemt de werkelijke leemte, zoals No EUR → USD price on or before 2026-01-31. Een latere koers kan een eerdere leemte niet vullen. Voeg een historisch passende 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 bevat valuation: "partial", missing_prices en missing_price_dates. Betrokken nettowinst-/nettowaardetotalen zijn null in de gevraagde valuta.

Inkomsten, passiva en eigen vermogen gebruiken normaal gesproken negatieve Beancount-tekens. Nettowinst is -(income + expenses), positief bij een winst. Dezelfde conventie geldt voor perioderijen van de income-statement. Balansreconciliatie wordt voor het rapport afgeleid; het schrijft geen richtlijnen. equity_reconciled geeft aan of een volledige reconciliatie beschikbaar is.

Rapport-JSON identificeert ook de periode, exclusieve einddatum, as-of-datum, conversie, rekeningfilter en validatiestatus van het grootboek. Controleer die velden voordat je totalen vergelijkt.

Optionele AI-assistentie​

bea ask heeft zowel de ask-extra als Beancount.io-inloggegevens van bea cloud login of BEA_TOKEN nodig. 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

Installeer voor een uv-installatie beancount-io[ask] en voer bea ask direct uit. --print / -p antwoordt één keer en stopt. Anders is een terminalsessie interactief en vult een optionele vraag de invoer vooraf in. Niet-interactief gebruik vereist een vraag. JSON-modus wordt niet ondersteund.

Query's worden lokaal uitgevoerd. Vragen, skillcontext en toolresultaten gaan naar de gehoste Beancount.io AI-service. Interactieve schrijfacties worden vooraf bekeken, bevestigd, gevalideerd en atomair geschreven. Ze accepteren --into. Algemene --yes verleent geen AI-schrijfrechten. Eén-antwoordmodus past voorgestelde schrijfacties niet toe.

Ask leest NAME/SKILL.md uit .agents/skills/ in de werkmap en uit skills/ in de gebruikersconfiguratiemap. Projectdefinities winnen op naam. Elk bestand vereist YAML-velden name en description. Volledige instructies worden op aanvraag geladen. Zie Breid bea ask uit met skills voor de bestandsindeling en een uitgewerkt voorbeeld.

Gehoste grootboeken​

Met algemene --json geven bea cloud status, bea cloud ledger list, bea cloud ledger show, bea cloud ledger create en bea cloud ledger delete de standaardenvelope weer. Login vereist interactie; geslaagde logout en clone retourneren geen JSON-succesobject.

Aanmaken accepteert ook --clone en --dir. Git- en SSH-toegang zijn vereist om te klonen. Als klonen mislukt na aanmaken, bestaat het gehoste grootboek nog steeds. Lokale commando's uploaden je grootboek niet automatisch. Er is geen algemene --ledger-optie.

JSON en uitgangscodes​

Algemene --json plaatst succesvolle resultaten op stdout:

{
  "bea": "0.2.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 schrijfacties identificeren ook into. Decimale bedragen en datums gebruiken strings. Beperkte lijsten bevatten 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 je een mutatie opnieuw probeert. Een gedeeltelijke batch kan geaccepteerde rijen schrijven, recursief formatteren kan geldige bestanden wijzigen, en create-and-clone kan een gehost grootboek aanmaken voordat het niet-nul afsluit. Zie Automatiseer boekhouding met bea voor een script dat deze envelope met jq leest en op deze codes vertakt.

CLI-prompts worden uitgeschakeld door --no-input, JSON-modus, niet-terminale stdin of waarheidsgetrouwe CI. Cloudverwijdering vereist nog steeds expliciete --yes. Imports vereisen een expliciete duplicaatbeslissing wanneer overeenkomsten moeten worden beoordeeld.

Uitvoeruitzonderingen: doctor, example, treeify, door Beanprice doorgestuurde price-aanroepen en ingest behouden native uitvoer en exitstatus, zelfs met algemene --json; de envelope en exitcategorieën hierboven beschrijven die doorgestuurde resultaten niet. Ask weigert JSON; cloud-login vereist interactie; geslaagde cloud-logout en clone retourneren geen JSON-succesobject. Help, versie en aanvulling behouden tekstuitvoer. upgrade kan de uitvoer van zijn pakketbeheerder naar stderr streamen, ook in JSON-modus.

Instellingen, updates en opgeslagen staat​

Waarheidsgetrouwe waarden zijn 1, true, yes en on, waarbij case en omringende whitespace worden genegeerd. Configuratiestatus omvat inloggegevens, Ask-promptgeschiedenis, gebruikersskills, onthouden importerpaden en caches voor updatecontroles. Schrijfvergrendelingen staan onder locks/ in de cachemap, buiten je grootboekmap.

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 kopieën; expliciete upgrade --check wordt nog steeds uitgevoerd wanneer de passieve melder is uitgeschakeld.

Verwijder met de bijpassende beheerder: brew uninstall bea, uv tool uninstall beancount-io of pipx uninstall beancount-io. Je grootboekbestanden en gebruikersconfiguratie blijven behouden.

Veelvoorkomende oplossingen​

Gebruik bea COMMAND --help om je geïnstalleerde versie te inspecteren. De referentiebronrepository bevat aanvullende voorbeelden en de exacte definities van het richtlijnmodel.