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 bifurca. Aquesta guia recorre aquestes quatre decisions de cap a cap 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 uns llibres nous, seguiu primer la guia d'inici ràpid de la CLI. Cada fet sobre les opcions, les claus de l'embolcall i els codis de sortida es consulta a la referència de la CLI de Beancount, no es repeteix aquí.

Trieu el llibre explícitament​

Anomeneu el fitxer. Una ordre local resol el seu objectiu des de --file, després $BEA_FILE i després ./main.bean al directori de treball, i una tasca programada rarament 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 a bea --file main.bean check. Si el fitxer resolt no existeix, l'ordre surt amb 2 i anomena les tres fonts, de manera que un error tipogràfic en una entrada de cron falla de manera evident en lloc de validar els llibres equivocats. L'orientació allotjada mitjançant una opció --ledger encara no existeix; bea no carrega mai un fitxer local implícitament.

Llegiu l'embolcall JSON​

Afegiu --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 YYYY-MM-DD, de manera que un valor és segur de comparar sense que mai entri un número de coma flotant al pipeline. Les claus de l'embolcall estan tabulades 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 de jq escrita per a elles continua sent vàlida. bea --json check i bea --json query també emeten l'embolcall avui dia, però són les ordres que es lliuren als executables nadius de Beancount, de manera que un script s'ha de basar 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ó, com explica la guia d'importació.

Atureu-vos amb el codi de sortida correcte​

Bifurqueu segons 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 mai no ha de reintentar a cegues: significa que el resultat és un conflicte o és desconegut, com ara una edició externa que arriba a mitja escriptura o un objectiu init que ja existeix. Inspeccioneu el llibre i després reintenteu des d'una lectura nova. La sortida 1 cobreix les fallades de validació i qualsevol altre error d'execució; error.details porta els errors individuals del llibre i error.result porta el que una escriptura parcial va fer realment. Una sortida no zero mai garanteix que no ha canviat res.

Executeu sense un terminal​

bea deixa de demanar confirmació pel seu compte. --no-input està implicat 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 la 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 el --allow-errors propi de l'ordre per acceptar la resposta parcial en lloc d'això, que també estableix ledger_valid: false i omple ledger_errors al JSON. --strict és la imatge mirall: rebutja respostes parcials fins i tot en un terminal, que és el que voleu quan un humà executa el mateix script a mà. bea check no té --allow-errors — informar d'errors és tota la seva feina — i sempre surt amb 1 quan en troba qualsevol. 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 programa 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.2.0
      - run: bea --file main.bean check
      - run: bea --json --file main.bean report balance-sheet > balance-sheet.json

La primera ordre basada en el motor descarrega el motor gestionat, de manera que l'executor necessita accés a la xarxa. Per reutilitzar-lo entre tasques, emmagatzemeu a la memòria cau ~/.local/share/bea/engine amb una clau que contingui el SO de l'executor, l'arquitectura, la versió de Python i la versió bea fixada. Fixeu la versió quan la tasca ha de ser reproduïble i deixeu-la anar quan preferiu seguir les versions. CI ja és veritable a GitHub Actions, de manera que els avisos estan desactivats i l'avís d'actualització és silenciós abans d'establir res. No hi ha cap pas de formatatge aquí deliberadament. Una tasca programada no ha de reescriure fitxers que no havia de fer-ho, de manera que recorregeu a bea format main.bean --check en un hook de pre-commit, que no toca res i surt amb 1 quan un fitxer necessita format.

Utilitzeu una credencial allotjada en una tasca​

Establiu BEA_TOKEN, des de la botiga de secrets del vostre proveïdor de CI, i salteu-vos l'inici de sessió al navegador completament. El token es llegeix de l'entorn i mai no s'escriu al disc, de manera que res no arriba al directori personal de l'executor perquè la propera tasca el trobi.

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

La sortida 0 significa que la credencial s'ha resolt i l'embolcall nomena 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 definida 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 — de manera que revocau un token filtrat des del panell de control. Les ordres locals no necessiten cap credencial; només bea cloud i bea ask accedeixen al servei allotjat. La llista completa de variables és a la referència de configuracó.

No tot es 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 JSON d'èxit — llegiu el seu estat de sortida en lloc. La sortida d'ajuda, de versió i de compleció de shell es manté textual.

Següents passos​

• Automatitzeu fitxers de banc amb la guia d'importació de la CLI.
• Consultau qualsevol opció, clau de l'embolcall o codi de sortida a la referència de la CLI de Beancount.
• Recorregeu a Python només quan la CLI s'acabi: vegeu fluxos de treball amb scripts.