Automatitzeu la comptabilitat amb bea

Un script condueix bea amb quatre decisions: quin llibre llegeix, --json per a una sortida llegible per màquina, jq per al valor que necessita i el codi de sortida sobre el qual es ramifica. Aquesta guia recorre aquestes quatre decisions de principi a fi i després les programa.

Necessiteu bea a la màquina que executa la tasca i un llibre al qual pugui accedir. Si esteu començant llibres nous, seguiu primer la guia d'inici ràpid de la CLI. Tots els fets sobre banderes, claus d'embolcall i codis de sortida es consulten a la referència de la CLI de Beancount, no es repeteixen aquí.

Trieu el llibre explícitament​

Anomeneu el fitxer. Una ordre local resol el seu objectiu a partir de --file, després $BEA_FILE i després ./main.bean al directori de treball, i una tasca programada poques vegades s'executa on penseu.

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

Les opcions globals van abans de l'ordre, com ara bea --file main.bean check. Si el fitxer resolt no existeix, l'ordre surt amb 2 i anomena les tres fonts, de manera que una errada en una entrada de cron falla amb soroll en lloc de validar els llibres equivocats. L'adreçament allotjat mitjançant una bandera --ledger encara no existeix; bea no penja mai un fitxer local implícitament.

Llegiu l'embolcall JSON​

Afegiu el --json global i cada ordre compatible respon amb el mateix embolcall: bea, target, data, truncated i limit en llistes limitades. Els imports són cadenes decimals i les dates són ISO AAAA-MM-DD, de manera que un valor és segur de comparar sense que cap float entri mai a la canonada. Les claus de l'embolcall es tabulen a la referència de JSON i codis de sortida.

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}'

Aquestes tres ordres — report, list i import — mantenen les seves formes de resultat, de manera que una ruta jq escrita contra elles continua sent vàlida. bea --json check i bea --json query també emeten l'embolcall avui, però són les ordres que es lliuren als executables natius de Beancount, de manera que un script ha de clau en l'estat de sortida de check més que no pas en la seva forma de sortida. Trieu la vostra política de duplicats deliberadament: --duplicates encara és necessari quan una importació necessita una decisió, tal com explica el tutorial d'importació.

Atureu-vos en el codi de sortida correcte​

Ramifiqueu-vos en l'estat i llegiu l'objecte d'error abans de reintentar qualsevol cosa que escrigui. En mode --json, una fallada no escriu res a stdout i exactament un objecte a stderr, la error.category del qual anomena la classe: 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

La sortida 4 és la que un script no ha de reintentar mai a cegues: significa que el resultat és un conflicte o és desconegut, com una edició externa que arriba a mitja escriptura o un objectiu init que ja existeix. Inspeccioneu el llibre i després torneu a provar des d'una lectura fresca. La sortida 1 cobreix fallades de validació i qualsevol altre error en temps d'execució; error.details porta els errors individuals del llibre i error.result porta el que una escriptura parcial va fer realment. Una sortida diferent de zero no garanteix mai que res no hagi canviat.

Executeu sense terminal​

bea deixa de demanar entrada pel seu compte. --no-input s'implica sempre que stdin no sigui un terminal, sempre que --json estigui definit i sempre que CI sigui veritable — 1, true, yes o on. En aquest mode, una confirmació que falta falla amb sortida 2 en lloc d'esperar per sempre.

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

Les lectures són permissives en un terminal i estrictes a tot arreu més. Quan el llibre té errors de carregador, query, list i report surten amb 1 sota --json, sota una stdout canalitzada, sota un CI veritable o amb --strict; passeu la pròpia bandera --allow-errors de l'ordre per acceptar la resposta parcial, que també estableix ledger_valid: false i omple ledger_errors al JSON. --strict és la imatge mirall: refusa respostes parcials fins i tot en un terminal, que és el que voleu quan un humà executa el mateix script manualment. bea check no té cap --allow-errors — informar d'errors és tota la seva feina — i sempre surt amb 1 quan en troba. Establiu BEA_NO_UPDATE_NOTIFIER=1 per silenciar l'avís passiu d'actualització; un CI veritable ja ho fa.

Programeu una comprovació​

Executeu una validació cada nit i deixeu que el codi de sortida sigui l'alerta. Els dos blocs següents són plantilles — els camins, el calendari i l'executor són vostres.

# 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.1.0
      - run: bea --file main.bean check
      - run: bea --json --file main.bean report balance-sheet > balance-sheet.json

Fixa la versió quan la tasca ha de ser reproduïble i elimina la fixació quan preferiu seguir les versions. CI ja és veritable a GitHub Actions, de manera que les indicacions estan desactivades i l'avís d'actualització és silenciós abans que configureu res. Aquí no hi ha cap pas de formatatge deliberadament. Una tasca programada no hauria de reescriure fitxers que no havia de tocar, així que recorre a bea format --check en un ganxo de pre-commit, que no toca res i surt amb 1 quan un fitxer necessita formatatge.

Utilitzeu una credencial allotjada en una tasca​

Establiu BEA_TOKEN des de l'emmagatzematge de secrets del vostre proveïdor de CI i ometeu completament la inici de sessió al navegador. El token es llegeix de l'entorn i no s'escriu mai al disc, de manera que no queda res al directori d'inici de l'executor perquè el trobi la següent tasca.

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

La sortida 0 significa que la credencial es va resoldre i l'embolcall anomena el compte al qual pertany; la sortida 3 amb error.category de auth significa que no s'ha resolt, i el missatge distingeix una credencial no configurada d'una de rebutjada. bea cloud logout no fa res a un token subministrat d'aquesta manera — ni el revoca ni el desactiva, ja que una altra tasca pot compartir-lo — així que revoqueu un token filtrat des del tauler de control. Les ordres locals no necessiten cap credencial; només bea cloud i bea ask arriben al servei allotjat. La llista completa de variables es troba a la referència de configuració.

No tot respon en JSON. bea ask rebutja el mode JSON directament, bea cloud login necessita un humà i un bea cloud logout o bea cloud ledger clone amb èxit no retorna cap objecte d'èxit JSON — llegiu el seu estat de sortida. La sortida d'ajuda, versió i completat de shell es mantenen textuals.

Passos següents​

• Automatitzeu els fitxers bancaris amb el tutorial d'importació de la CLI.
• Consulteu qualsevol bandera, clau d'embolcall o codi de sortida a la referència de la CLI de Beancount.
• Recorreu a Python només quan la CLI s'acabi: vegeu fluxos de treball amb script.