Boekhouding automatiseren met bea

Een script stuurt bea aan met vier beslissingen: welk grootboek het leest, --json voor machine-leesbare uitvoer, jq voor de waarde die het nodig heeft, en de exitcode waarop het vertakt. Deze handleiding doorloopt die vier beslissingen van begin tot eind en plant ze vervolgens in.

U hebt bea nodig op de machine die de taak uitvoert en een grootboek dat het kan bereiken. Als u nieuwe boeken start, volg dan eerst de CLI-snelstart. Elk feit over vlaggen, envelopsleutels en exitcodes wordt opgezocht in de Beancount CLI-referentie, niet hier herhaald.

Kies het grootboek expliciet​

Noem het bestand. Een lokale opdracht lost zijn doel op uit --file, dan $BEA_FILE, dan ./main.bean in de werkmap, en een geplande taak draait zelden waar u denkt dat het draait.

bea --file ~/books/main.bean check
BEA_FILE=~/books/main.bean bea check
cd ~/books && bea check

Globale opties gaan vóór de opdracht, zoals in bea --file main.bean check. Als het opgeloste bestand niet bestaat, eindigt de opdracht met exitcode 2 en noemt het alle drie de bronnen, zodat een typfout in een cron-regel luid faalt in plaats van de verkeerde boeken te valideren. Gericht hosten via een --ledger-vlag bestaat nog niet; bea uploadt nooit impliciet een lokaal bestand.

Lees de JSON-envelop​

Voeg globaal --json toe en elke ondersteunde opdracht antwoordt met dezelfde envelop: bea, target, data, truncated en limit op begrensde lijsten. Bedragen zijn decimale tekenreeksen en datums zijn ISO YYYY-MM-DD, zodat een waarde veilig te vergelijken is zonder dat er ooit een float in de pijplijn komt. De sleutels van de envelop staan in tabelvorm in de JSON- en exitcode-referentie.

bea --json --file main.bean report income-statement | jq .data.net_profit
bea --json --file main.bean list transaction --limit 2 | jq '.data[0].postings[0].units'
bea --json --file main.bean import statement.csv --csv date=Date,amount=Amount,payee=Payee \
  --account Assets:Checking --apply --duplicates skip | jq '.data | {written, ready, duplicates}'

Die drie opdrachten — report, list en import — behouden hun resultaatstructuren, zodat een jq-pad dat ertegen is geschreven geldig blijft. bea --json check en bea --json query zenden vandaag ook de envelop uit, maar het zijn de opdrachten die worden overgedragen aan de native Beancount-uitvoerbare bestanden, dus een script moet zich richten op de exitstatus van check in plaats van op de vorm van de uitvoer. Kies uw duplicaatbeleid bewust: --duplicates is nog steeds vereist wanneer een import een beslissing nodig heeft, zoals de importwalkthrough uitlegt.

Stop op de juiste exitcode​

Vertak op de status en lees het foutobject voordat u iets opnieuw probeert dat schrijft. In --json-modus schrijft een storing niets naar stdout en precies één object naar stderr, waarvan error.category de klasse noemt: validation (1), usage (2), auth (3), conflict (4).

#!/usr/bin/env bash
set -euo pipefail
 
out=$(mktemp)
err=$(mktemp)
status=0
 
bea --json --file main.bean report income-statement >"$out" 2>"$err" || status=$?
 
case "$status" in
  0) jq -r '.data.net_profit | to_entries[] | "net profit: \(.value) \(.key)"' "$out" ;;
  4) echo "conflict — inspect the ledger before retrying" >&2
     jq -r '.error.message' "$err" >&2
     exit 4 ;;
  *) jq -r '.error | "\(.category) (exit \(.exit_code)): \(.message)"' "$err" >&2
     exit "$status" ;;
esac

Exitcode 4 is degene waarop een script nooit blindelings opnieuw moet proberen: het betekent dat de uitkomst een conflict is of onbekend, zoals een externe bewerking die halverwege het schrijven binnenkomt of een init-doel dat al bestaat. Inspecteer het grootboek en probeer het dan opnieuw vanaf een verse lezing. Exitcode 1 dekt validatiestoringen en elke andere runtime-fout; error.details draagt de individuele grootboekfouten en error.result draagt wat een gedeeltelijke schrijfactie daadwerkelijk heeft gedaan. Een niet-nul exitcode garandeert nooit dat er niets is veranderd.

Draai zonder terminal​

bea stopt zelf met vragen. --no-input wordt geïmpliceerd wanneer stdin geen terminal is, wanneer --json is ingesteld en wanneer CI waarheidsgetrouw is — 1, true, yes of on. In die modus faalt een ontbrekende bevestiging met exitcode 2 in plaats van voor altijd te wachten.

CI=true BEA_NO_UPDATE_NOTIFIER=1 bea --json --file main.bean report balance-sheet
bea --json --file main.bean list transaction --limit 100 --sort oldest

Lezingen zijn tolerant in een terminal en streng overal elders. Wanneer het grootboek loader-fouten heeft, eindigen query, list en report met exitcode 1 onder --json, onder een gepijpte stdout, onder een waarheidsgetrouwe CI of met --strict; geef de eigen --allow-errors van de opdracht door om in plaats daarvan het gedeeltelijke antwoord te accepteren, wat ook ledger_valid: false instelt en ledger_errors in de JSON vult. --strict is het spiegelbeeld: het weigert gedeeltelijke antwoorden, zelfs in een terminal, wat u wilt wanneer een mens hetzelfde script handmatig draait. bea check heeft geen --allow-errors — het rapporteren van fouten is zijn hele taak — en eindigt altijd met exitcode 1 wanneer het er een vindt. Stel BEA_NO_UPDATE_NOTIFIER=1 in om de passieve updatemelding te dempen; een waarheidsgetrouwe CI doet dat al.

Plan een controle in​

Draai elke nacht een validatie en laat de exitcode de alert zijn. Beide blokken hieronder zijn sjablonen — de paden, het schema en de runner zijn aan u.

# crontab -e — 07:15 daily; cron mails you only when bea exits nonzero
15 7 * * * BEA_NO_UPDATE_NOTIFIER=1 /opt/homebrew/bin/bea --file /home/alice/books/main.bean check

name: ledger
on:
  schedule:
    - cron: "15 7 * * *"
  push:
jobs:
  check:
    runs-on: ubuntu-latest
    env:
      BEA_NO_UPDATE_NOTIFIER: "1"
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv tool install beancount-io==0.2.0
      - run: bea --file main.bean check
      - run: bea --json --file main.bean report balance-sheet > balance-sheet.json

De eerste engine-ondersteunde opdracht downloadt de beheerde engine, dus de runner heeft netwerktoegang nodig. Om het opnieuw te gebruiken tussen taken, cache ~/.local/share/bea/engine met een sleutel die de runner-OS, architectuur, Python-versie en vastgezette bea-versie bevat. Zet de versie vast wanneer de taak reproduceerbaar moet zijn, en laat de pin los wanneer u liever releases volgt. CI is al waarheidsgetrouw op GitHub Actions, dus prompts zijn uit en de updatemelding is stil voordat u iets instelt. Er is hier met opzet geen opmaakstap. Een geplande taak moet geen bestanden herschrijven die het niet hoefde, dus grijp naar bea format main.bean --check in een pre-commit-hook, die niets aanraakt en eindigt met exitcode 1 wanneer een bestand opmaak nodig heeft.

Gebruik een gehoste credential in een taak​

Stel BEA_TOKEN in, uit de geheime opslag van uw CI-provider, en sla de browseraanmelding volledig over. De token wordt uit de omgeving gelezen en nooit naar schijf geschreven, dus er belandt niets in de thuismap van de runner voor de volgende taak om te vinden.

export BEA_TOKEN="$YOUR_CI_SECRET"
bea --json cloud status

Exitcode 0 betekent dat de credential is opgelost en de envelop het account noemt waartoe het behoort; exitcode 3 met error.category van auth betekent dat dit niet het geval is, en het bericht onderscheidt een niet-ingestelde credential van een afgewezen credential. bea cloud logout doet niets met een op deze manier aangeleverde token — het trekt het noch in, noch stelt het niet in, aangezien een andere taak het kan delen — dus trek een gelekt token in via het dashboard in plaats daarvan. Lokale opdrachten hebben helemaal geen credential nodig; alleen bea cloud en bea ask bereiken de gehoste service. De volledige variabelemlijst staat in de instellingenreferentie.

Niet alles antwoordt in JSON. bea ask wijst JSON-modus ronduit af, bea cloud login heeft een mens nodig en een succesvolle bea cloud logout of bea cloud ledger clone retourneert geen JSON-succesobject — lees in plaats daarvan hun exitstatus. Help-, versie- en shell-completie-uitvoer blijft tekstueel.

Volgende stappen​

• Automatiseer bankbestanden met de CLI-importwalkthrough.
• Zoek elke vlag, envelopsleutel of exitcode op in de Beancount CLI-referentie.
• Grijp alleen naar Python wanneer de CLI opraakt: zie scriptbare workflows.